This is part of a larger tutorial created and presented as "A hands on introduction to GeoBlacklight".

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

  1. Basic principles
  2. Customize metadata shown
  3. Changing the style of your application
  4. Overriding a partial

Basic principles

When it comes to customizing your GeoBlacklight application there are some basic principles to keep in mind.

  1. 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)

  2. Reach out and ask for help on the Blacklight Developers or GeoBlacklight Google Groups

    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.

  1. Make sure your Solr server and Rails application are started.

    $ rake geoblacklight:server
    
  2. Open the catalog_controller.rb file in your text editor.

    Hint: catalog_controller.rb is located at “app/controllers/catalog_controller.rb” in your application

  3. 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”.

  4. 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.

  5. Next we will remove the “Author(s)” metadata field from being shown. Comment out or remove the Settings.FIELDS.CREATOR line (121).

    # 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.

  1. Rename application.css to application.scss

    $ mv app/assets/stylesheets/application.css app/assets/stylesheets/application.scss
    
  2. Delete everything from application.scss and manually import blacklight.scss and geoblacklight.scss rather than require tree.

    // in app/assets/stylesheets/application.scss
    @import 'blacklight';
    @import 'geoblacklight';
    
  3. Similarly in geoblacklight.scss, remove requires and import them instead.

    // in app/assets/stylesheets/geoblacklight.scss
    @import 'geoblacklight/application';
    
  4. Create file app/assets/stylesheets/bootstrap-variables.scss and import it from blacklight.scss

    $ touch app/assets/stylesheets/bootstrap-variables.scss
    
    // in app/assets/stylesheets/blacklight.scss
    @import 'bootstrap-variables';
    
    @import 'bootstrap-sprockets';
    
    @import 'bootstrap';
    
    @import 'blacklight/blacklight';
    
  5. Now you can easily update Bootstrap variables in your bootstrap-variables.scss!

    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.

  1. Check out home page partial on Github. https://github.com/geoblacklight/geoblacklight/blob/master/app/views/catalog/_home_text.html.erb

  2. This same partial is being overriden from Blacklight https://github.com/projectblacklight/blacklight/blob/master/app/views/catalog/_home_text.html.erb

  3. 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
    
  4. 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.

  1. Open up file config/locales/blacklight.en.yml

    en:
      blacklight:
        application_name: 'Blacklight'
    
  2. 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: - Blacklight Configurable Keys - GeoBlacklight Configurable Keys

Wrapping Up

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