Customize your application - Part 5 - GeoBlacklight Workshop"
Feb 9, 2015
There are many ways to customize your GeoBlacklight application, and unfortunately we can’t cover them all with this tutorial. GeoBlacklight tries to stick to similar patterns as Blacklight, so most of the Blacklight customization techniques should hold true.
Blacklight Customization - from the Project Blacklight Wiki
Customizing your GeoBlacklight Application
- Basic principles
- Customize metadata shown
- Changing the style of your application
- Overriding a partial
When it comes to customizing your GeoBlacklight application there are some basic principles to keep in mind.
The less you override the easier it is to upgrade.
Blacklight and GeoBlacklight adhere to some basic principles which all adopters to override helper methods, view partials, and even classes. A lot of things are configurable out of the box. However, there are some best practices around what to override and where to do it to make sure your application can take advantage to improvements to both Blacklight and GeoBlacklight. Both projects use semantic versioning to make this upgrade path easier for adopters.
Providing your own view templates - Blacklight Wiki (Customizing the User Interface)
Asking questions, reaching out to others, and getting feedback from experienced developpers is a great practice in general. In this particular case its helps foster the community and start conversations that might help others.
Customize metadata shown
In this example we are going to change the way the GeoBlacklight is configured to show certain metadata fields on an items page. This is the same way a Blacklight application would configure these fields.
Make sure your Solr server and Rails application are started.
$ rake geoblacklight:server
catalog_controller.rbfile in your text editor.
catalog_controller.rbis located at “app/controllers/catalog_controller.rb” in your application
Scroll down to lines 121 - 128.
... config.add_show_field Settings.FIELDS.CREATOR, label: 'Author(s)', itemprop: 'author' config.add_show_field Settings.FIELDS.DESCRIPTION, label: 'Description', itemprop: 'description', helper_method: :render_value_as_truncate_abstract config.add_show_field Settings.FIELDS.PUBLISHER, label: 'Publisher', itemprop: 'publisher' config.add_show_field Settings.FIELDS.PART_OF, label: 'Collection', itemprop: 'isPartOf' config.add_show_field Settings.FIELDS.SPATIAL_COVERAGE, label: 'Place(s)', itemprop: 'spatial', link_to_search: true config.add_show_field Settings.FIELDS.SUBJECT, label: 'Subject(s)', itemprop: 'keywords', link_to_search: true config.add_show_field Settings.FIELDS.TEMPORAL, label: 'Year', itemprop: 'temporal' config.add_show_field Settings.FIELDS.PROVENANCE, label: 'Held by', link_to_search: true ...
These configuration options relate to fields that are indexed in Solr. You can disable a metadata field being shown on an items show page. If you navigate to an items page, it will currently show field called publisher. Maybe you would like to rename that field to “Data publisher”.
Modify the label in line 123
# change this config.add_show_field Settings.FIELDS.PUBLISHER, label: 'Publisher', itemprop: 'publisher' # to this config.add_show_field Settings.FIELDS.PUBLISHER, label: 'Data publisher', itemprop: 'publisher'
Save the file and reload the page. You should see the label change.
Next we will remove the “Author(s)” metadata field from being shown. Comment out or remove the
# config.add_show_field Settings.FIELDS.CREATOR, label: 'Author(s)', itemprop: 'author'
Save the file and reload the page. You should no longer see the “Author(s)” field.
You have now customized a layer’s show page!
Changing the style of your application
GeoBlacklight uses Twitter Bootstrap as a base for UI components and is implemented using the bootstrap-sass gem. This approach should make things easier for adopters wanting to customize the look and feel of their application. Bootstrap variables can easily be modified which will change how the application looks.
$ mv app/assets/stylesheets/application.css app/assets/stylesheets/application.scss
Delete everything from application.scss and manually import
geoblacklight.scssrather than require tree.
// in app/assets/stylesheets/application.scss @import 'blacklight'; @import 'geoblacklight';
geoblacklight.scss, remove requires and import them instead.
// in app/assets/stylesheets/geoblacklight.scss @import 'geoblacklight/application';
app/assets/stylesheets/bootstrap-variables.scssand import it from
$ touch app/assets/stylesheets/bootstrap-variables.scss
// in app/assets/stylesheets/blacklight.scss @import 'bootstrap-variables'; @import 'bootstrap-sprockets'; @import 'bootstrap'; @import 'blacklight/blacklight';
Now you can easily update Bootstrap variables in your
Change the navbar height
// in app/assets/stylesheets/bootstrap-variables.scss // Navbar $navbar-height: 80px;
Change the primary brand color
// in app/assets/stylesheets/bootstrap-variables.scss // Colors $brand-primary: #32cd32;
Great job! You can configure a whole host of options using this Bootstrap customization technique. Once again, here is the list of Bootstrap variables you can customize http://getbootstrap.com/customize/ .
Overriding a partial
Lets say you want to override the homepage that is shown in GeoBlacklight that can easily be done by just creating same-named a partial at the same path in your GeoBlacklight application.
Check out home page partial on Github. https://github.com/geoblacklight/geoblacklight/blob/master/app/views/catalog/_home_text.html.erb
This same partial is being overriden from Blacklight https://github.com/projectblacklight/blacklight/blob/master/app/views/catalog/_home_text.html.erb
Create a file with the same name and path in your application.
$ mkdir -p app/views/catalog $ touch app/views/catalog/_home_text.html.erb
Edit this file and add some custom text
This is the home page. Search bar: <%= render_search_form_no_navbar %>
See how easy that was? You even included another partial!
Customize i18n keys
Blacklight and GeoBlacklight use i18n for internationalization support. These keys provide a quick way to customize your app without having to override partials.
Open up file
en: blacklight: application_name: 'Blacklight'
Edit the file, adding a customization to the search form label
en: blacklight: application_name: 'Your Geo App' search: form: submit: 'Search this'
Refresh your home page and you should see the submit button text changed. If you inspect the html you will notice the HTML title attribute changed.
More configurable keys are available, check out what you can customize using this approach:
Thanks for attending this workshop. You can contribute feedback about this workshop by filling out a quick survey.
This workshop is open source, and you can contribute back to it.
Don’t forget to stop your virtual machine.
$ vagrant halt # stops the virtual machine
- Part 1 - GeoBlacklight overview
- Part 2 - Setting up your environment
- Part 3 - Create your application
- Part 4 - Index Solr documents
- Part 5 - Customize your application
This work is licensed under a Creative Commons Attribution 4.0 International License.