Use with Hyrax

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.

Generating Works in DogBiscuits

You should have already run the DogBiscuits Install Generator.

The Hyrax application can be set-up with your chosen DogBiscuits works like so:

1. (Recommended) Edit the DogBiscuits configuration file (config/initializers/dog_biscuits.rb) to add your choices and customisations. See the 'Configuration' section, below for more details.
2. Run the Work Generator for each DogBiscuits Work you want in the application or run the Generate All for the models you have configured in step (1)

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, there is a --skip_model option to ensure the generator doesn't overwrite those changes.

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 apply across all works, and 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

Select the models you want to use in your application - see the comments in the file for available models

  config.selected_models = ['ConferenceItem']

**Add to or remove facets **

  config.facet_properties += [:property_to_add]
  config.facet_properties -= [:property_to_remove]

Replace all facets with a new set

  config.facet_properties = [:chosen_property_1, :chosen_property_2]

Add to or remove from search results view

  config.index_properties += [:property_to_add]
  config.index_properties -= [:property_to_remove]

Replace all properties show in search results with a new set

  config.index_properties = [:chosen_property_1, :chosen_property_2]  

Change information associated with an existing property_mapping

  config.property_mappings[:my_changed_property] =
    {
      # REQUIRED only 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
      # here `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
      # here 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: {
        property: 'contributor' # the closest property match in schema.org is contributor
      }
    }

Work-specific configuration only applies to one Work type (using ConferenceItem as an example):

  # select and order the properties used in the form and show page
  config.conference_item_properties = [:chosen_property_1, :chosen_property_2]
  
  # add more required properties
  config.conference_item_properties_required += [:property_to_add]
  # replace required properties
  config.conference_item_properties_required = [:chosen_property_1, :chosen_property_2]

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

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 --skip_model 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_add]

  # add to the facets (optional)

  # add to the search results (optional)

  # add a property mapping (recommended)
  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',
      # app/renderers/my_new_property_attribute_renderer.rb` must exist
      render_as: 'my_new_property',
      # the `my_new_property_helper` method must exist in app/helpers, eg. in hyrax_helper.rb
      helper_method: 'my_new_property_helper',
      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 --skip_model 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.

The Generators And What They Do

Install Generator

This generator makes the following changes to your application:

1. Adds a dog_biscuits initializer in config/initializers/dog_biscuits.rb.
2. Adds a dog_biscuits yml configuration file in config/dog_biscuits.yml.
3. Includes DogBiscuits::ExtendedSolrDocument in the SolrDocument
4. Runs the authorities, edit_fields_and_inputs and schema_org generators
5. Adds two view files as a temporary fix.

Run with:

• rails generate dog_biscuits:install

Regenerate All Generator

This generator makes the following changes to your application:

1. Runs the catalog_controller generator
2. Runs the attribute_rows generator
3. Runs the locales generator
4. Runs the schema_org generator

Authority Generator:

This generator makes the following changes to your application:

1. Copies authorities into config/authorities.
2. Registers all subauthorities in config/intitializers/dog_biscuits.rb
3. Sets up references to the authority concept_schemes in config/dog_biscuits.yml
4. Copies the authority services into app/services/

Run:
rails generate dog_biscuits:authority

Edit Fields and Inputs Generator

This generator makes the following changes to your application:

1. Creates files needed for the forms.

# Run:
rails generate dog_biscuits:edit_fields_and_inputs

Catalog Controller Generator

This generator makes the following changes to your application:

1. Creates a new app/controllers/catalog_controller.rb.
2. Injects facet, show and index fields using confingured properties

# Run:
rails generate dog_biscuits:catalog_controller

Schema Org Generator

This generator makes the following changes to your application:

1. Creates a schema_org.yml file in ./config
2. Injects schema_org metadata for all properties where this information is configured in property_mappings

# Run:
rails generate dog_biscuits:schema_org

Locales Generator

This generator can be run for an existing Model, or for All models (with All).

This generator makes the following changes to your application where information is available in property_mappings:

1. Injects labels and help_text into the en locale for the given model.
2. Injects new labels into the en blacklight locale.

# Run all:
rails generate dog_biscuits:locales All
# Run one:
rails generate dog_biscuits:locales ConferenceItem

Attribute Rows Generator

This generator can be run for an existing Model, or for All models (with All).

This generator makes the following changes to your application:

1. Creates an _attribute_rows.html.erb file for the given Work
2. Injects a row for each attribute where information is available in property_mappings

# Run all:
rails generate dog_biscuits:attribute_rows All
# Run one:
rails generate dog_biscuits:attribute_rows ConferenceItem

Work Generator

This generator makes the following changes to your application:

1. Checks that the requested Work is supported by DogBiscuits
2. Runs the Hyrax generator for the given model
3. Creates a new model, form and indexer to replace the Hyrax one
4. Injects properties into the Hyrax-generated presenter
5. Creates an attribute_rows view file using the configured properties for the work
6. Updates the schema_org config, blacklight (en) locale and work (en) locale using the configured properties for the work
7. Updates the catalog controller with the configured properties for the work

# Run with the model name as an attribute:
rails generate dog_biscuits:work ConferenceItem
# Skip generating the model and indexer:
rails generate dog_biscuits:work ConferenceItem --skip_model