Use with Hyrax
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.
- Generating Works in DogBiscuits
- Configuration
- Adding New Local Properties
- What Not To Do
- The Generators And What They Do
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:
- (Recommended) Edit the DogBiscuits configuration file (
config/initializers/dog_biscuits.rb) with your own preferences. See the 'Configuration' section, below for more details. - Run the Work Generator for each DogBiscuits Work you want in the application.
Alternatively, if you have configured
selected_modelsin 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 --skip_model 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.
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.
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_new_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'
}
}
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 --skip_model if you've added new local properties to the model and/or indexer - these files won't be overwritten
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_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 --skip_model option
This will update the form, presenter, catalog_controller, attribute_rows and locales with the new property.
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.
This generator makes the following changes to your application:
- Adds a dog_biscuits initializer in config/initializers/dog_biscuits.rb.
- Adds a dog_biscuits yml configuration file in config/dog_biscuits.yml.
- Includes DogBiscuits::ExtendedSolrDocument in the SolrDocument
- Runs the authorities and schema_org generators
- Adds the LocalFormMetadataService
- Adds two view files as a temporary fix.
Run with:
- rails generate dog_biscuits:install
This generator makes the following changes to your application:
- Runs the work generator for selected models configured in
onfig/initializers/dog_biscuits.rb - Runs the catalog_controller generator
- Runs the attribute_rows generator
- Runs the locales generator
- Runs the schema_org generator
Run:
rails generate dog_biscuits:generate_all
Don't overwrite the models and indexers:
rails generate dog_biscuits:generate_all --skip_model
This generator makes the following changes to your application:
- Copies authorities into config/authorities.
- Registers all subauthorities in config/intitializers/dog_biscuits.rb
- Sets up references to the authority concept_schemes in config/dog_biscuits.yml
- Copies the authority services into app/services/
Run:
rails generate dog_biscuits:authority
This generator makes the following changes to your application:
- Creates files needed for the forms.
# Run:
rails generate dog_biscuits:edit_fields_and_inputs
This generator makes the following changes to your application:
- Creates a new app/controllers/catalog_controller.rb.
- Injects facet, show and index fields using confingured properties
# Run:
rails generate dog_biscuits:catalog_controller
This generator makes the following changes to your application:
- Creates a schema_org.yml file in ./config
- Injects schema_org metadata for all properties where this information is configured in property_mappings
# Run:
rails generate dog_biscuits:schema_org
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:
- Injects labels and help_text into the en locale for the given model.
- Injects new labels into the en blacklight locale.
# Run all:
rails generate dog_biscuits:locales All
# Run one:
rails generate dog_biscuits:locales ConferenceItem
This generator can be run for an existing Model, or for All models (with All).
This generator makes the following changes to your application:
- Creates an _attribute_rows.html.erb file for the given Work
- 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
This generator makes the following changes to your application:
- Checks that the requested Work is supported by DogBiscuits
- Runs the Hyrax generator for the given model
- Creates a new model, form and indexer to replace the Hyrax one
- Injects properties into the Hyrax-generated presenter
- Creates an attribute_rows view file using the configured properties for the work
- Updates the schema_org config, blacklight (en) locale and work (en) locale using the configured properties for the work
- 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
