Use with Hyrax

Using DogBiscuits in a Hyrax Application

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

Fear not, 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 too.

Adding New Local Properties

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

• Add the new local property into the Model
• Optionally add any custom indexing into the Indexer
• Add the new property into the SolrDocument
• Edit 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)

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.

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/

Edit Fields and Inputs Generator

This generator makes the following changes to your application:

1. Creates files needed for the forms.

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

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

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.

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

Examples:

• rails generate dog_biscuits:install

• rails generate dog_biscuits:authority

• rails generate dog_biscuits:edit_fields_and_inputs

• rails generate dog_biscuits:catalog_controller

• rails generate dog_biscuits:schema_org

• rails generate dog_biscuits:locales All

• rails generate dog_biscuits:locales ConferenceItem

• rails generate dog_biscuits:attribute_rows All

• rails generate dog_biscuits:attribute_rows ConferenceItem

Description: The DogBiscuits Work 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

Example: rails generate dog_biscuits:work ConferenceItem

Making changes post-generation: 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 local properties Add the local property into the model (in app/models/) Add an attribute into the solr_document (app/models/solr_document.rb) Add the property to the config (config/initializers/dog_biscuits.rb), eg: # property mappings config.property_mappings[:my_new_property] = {} # properties list config.work_properties += [:my_new_property] # required properties list config.work_properties_required += [:my_new_property] # make it a facet config.facet_properties += [:my_new_property] # show in search results config.index_properties += [:my_new_property]

  eg.
  # property_mappings
  config.property_mappings[:my_new_property] =
    {
        index: "('new_property', :stored_sortable)"
    }

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

The generator can be re-run without overwriting the model file using the --skip_model option

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

Example: rails generate dog_biscuits:work ConferenceItem --skip_model