Skip to content

Use with Hyrax

Jump to bottom
Julie Allinson edited this page Nov 6, 2017 · 37 revisions

Using DogBiscuits in a Hyrax Application

To make use of DogBiscuits 🐶 🍪 models in a Hyrax application there is still a lot of manual work to do, adding the new models, forms, presenters, views and so on.

DogBiscuits has generators to make this easier.

Note: The Hyrax Knowledge Base has excellent documentation on adding works and customizing metadata: How do I customize metadata?. The DogBiscuits generators are taking on a lot of the work described in those pages, but the guide is an excellent way of understanding all of the moving parts.

  1. Generating Works in DogBiscuits
  2. Configuration
  3. Adding New Local Properties
  4. What Not To Do
  5. The Generators And What They Do

Generating Works in DogBiscuits

Make sure you already run the DogBiscuits Install Generator (rails generate dog_biscuits:install).

Add your chosen DogBiscuits works to your Hyrax application like so:

  1. (Recommended) Edit the DogBiscuits configuration file (config/initializers/dog_biscuits.rb) with your own preferences. See the 'Configuration' section, below for more details.
  2. Run the Work Generator for each DogBiscuits Work you want in the application. Alternatively, if you have configured selected_models in step (1) run the Generate All generator.
rails generate dog_biscuits:work Work
OR
rails generate dog_biscuits:generate_all

Don't worry if you've gone straight to step (2), or want to make configuration changes later. You can re-run the work generator or generate_all generator any time. If you've customised the model and indexer, eg. with local properties, there is a --skipmodel option to ensure the generator doesn't overwrite those changes.

Do I have to run the Hyrax work generator? No. The DogBiscuits work generator runs the Hyrax work generator for you. If you've already done it, that's fine too.

Configuration

You will likely want to do some custom configuration, such as choose the properties that appear on the form and show pages, or change the facets and search results. DogBiscuits supports this through generators.

Configuration happens in config/initializers/dog_biscuits.rb and there are two kinds of things to configure:

  • global configurations that apply across the application
  • work-specific configurations apply only to given works

Note: When configuring properties, you cannot add properties that are not available in dog_biscuits. You can only do this by following the 'add new local properties' instructions below.

Global configuration

Set the models you want to use in your application

  config.selected_models = ['ConferenceItem']

Facets: add, remove or replace

  config.facet_properties += [:property_to_add]
  config.facet_properties -= [:property_to_remove]
  config.facet_properties = [:chosen_property_1, :chosen_property_2]

Search results display: add, remove or replace

  config.index_properties += [:property_to_add]
  config.index_properties -= [:property_to_remove]
  config.index_properties = [:chosen_property_1, :chosen_property_2]

Singular properties: add, remove or replace the list of fields to display as 'singular' in the form ie. where only a single value can be entered

  config.singular_properties += [:property_to_make_singular]
  config.singular_properties -= [:property_to_stop_being_singular]
  config.singular_properties = [:chosen_property_1, :chosen_property_2]

Change information associated with an existing property_mapping

  config.property_mappings[:my_changed_property] =
    {
      index: "('my_changed_property', :stored_searchable)",
      label: 'My Property Label',
      help_text: 'Use this to describe something or other',
      render_as: 'my_changed_property',
      helper_method: 'my_changed_property_helper',
      schema_org: {
        property: 'contributor' # the closest property match in schema.org is contributor
      }
    }

About property_mappings: a hash containing a key for each property in DogBiscuits. This part of the configuration gives us local control over various things without needing to edit multiple files. It is used to create or update the following:

  • catalog_controller - labels, helper_methods other setup for the search index and facets
  • locales - labels and help text for use in the search, facets, form and show pages
  • schema_org - mappings to schema_org properties for embedded page metadata
  • attribute_rows - labels and renderers for the show page

The following example shows how each property_mapping should be constructed.

  config.property_mappings[:my_changed_property] =
    {
      # REQUIRED (if the property will appear in search results): a string formatted as per the example shown
      index: "('my_changed_property', :stored_searchable)",
      
      # OPTIONAL: label for use in the form, show page, search results and facet
      label: 'My Property Label', 

      # OPTIONAL: help_text for use in the form
      help_text: 'Use this to describe something or other',
      
      # OPTIONAL: reference to a renderer used to format the display of the text in the show page
      # in this eg. `app/renderers/my_changed_property_attribute_renderer.rb` must exist
      render_as: 'my_changed_property',
      
      # OPTIONAL reference to a helper method used to format the display of the text in the search results
      # in this eg. the `my_changed_property_helper` method must exist in app/helpers, eg. in hyrax_helper.rb
      helper_method: 'my_new_property_helper',
      
      # OPTIONAL mapping to a schema.org property to be used in embedded metadata
      schema_org: {
        # in this eg. we have decided that the closest property match in schema.org is contributor
        property: 'contributor' 
      }
    }

Work-specific configuration

These configurations only apply to one Work type (using ConferenceItem as an example):

Properties in the form and show page

  # replace all of them - also use this if you want to re-order them
  config.conference_item_properties = [:chosen_property_1, :chosen_property_2]
  # remove some
  config.conference_item_properties -= [:chosen_property_1, :chosen_property_2]
  # add some, eg. new locally defined properties
  config.conference_item_properties += [:new_property_1, :new_property_2]

Required properties: add, remove or replace required properties

  config.conference_item_properties_required += [:property_to_add]
  config.conference_item_properties_required -= [:property_to_remove]
  config.conference_item_properties_required = [:chosen_property_1, :chosen_property_2]

Note: Making changes post-generation:

If you have already generated the Work, you can re-run the generator with the --force or -f flag to update the existing files. This may be useful, for example:

  • where you wish to locally remove, or configure the order of properties in the form
  • where you wish to add a local renderer or change a label in the property_mappings config
  • use --skipmodel if you've added new local properties to the model and/or indexer - these files won't be overwritten

Adding New Local Properties

Requires a few steps (although fewer than doing this manually!):

  • Add the local property into the Model (in app/models/)
  • Optionally add any custom indexing into the Indexer
  • Add the property into the SolrDocument (app/models/solr_document.rb)
  • Add the property to the DogBiscuits configuration file (config/initializers/dog_biscuits.rb)
  • Run the Work Generator (with --skipmodel to leave local changes to the model and indexer in place)

For example, to add a property called 'my_new_property' to ConferenceItem

In app/models/conference_item.rb

  property :my_new_property, predicate: ::RDF::URI('http://example.com/myNewProperty') do |index|
    index.as :stored_searchable, :facetable
  end

In app/models/solr_document.rb

  def my_new_property
    self[Solrizer.solr_name('my_new_property')]
  end

In config/initializers/dog_biscuits.rb:

  # add to the work properties (required)
  config.conference_item_properties += [:property_to_add]
  
  # make it a required field (optional)
  config.conference_item_properties_required += [:property_to_facet]

  # add to the facets (optional)
  config.facet_properties += [:property_to_index]

  # add to the search results (optional)
  config.index_properties += [:property_to_add]

  # add a property mapping (recommended; required if adding the property to config.index_properties)
  config.property_mappings[:my_new_property] =
    {
      index: "('my_new_property', :stored_searchable)",
      label: 'My Property Label',
      help_text: 'Use this to describe something or other',
      schema_org: {
        property: 'identifier'
      }
    }

Add custom helper methods or renderers (in app/helpers/ and app/renderers) and add them to the property_mappings as shown above.

The generator can be re-run without overwriting the model and indexer files using the --skipmodel option

This will update the form, presenter, catalog_controller, attribute_rows and locales with the new property.

What Not To Do

If you want to manage your works with DogBiscuits, don't manually edit:

  • catalog_controller.rb
  • presenters
  • forms
  • _attribute_rows.html.erb
  • locales
  • schema_org.yml

If you do, you won't be able to use the generators without overwriting your local changes.

Clone this wiki locally