Customizing Metadata Tutorial: Modifying the Edit Form

1 Notable WorkForm methods
2 Adding the properties to the work-type’s new/edit form
- 2.1 The modified work class
- 2.2 Default form field behavior
3 Customizing the form field

This tutorial assumes that you generated a work type name GenericWork. If you used a different name, substitute that name for all occurrences of GenericWork and generic_work.

The inclusion of properties in the new/edit form is controlled by the GenericWorkForm class. The GenericWorkForm class is generated with the basic set of properties (aka terms, aka metadata fields) to include. The generated version of the file looks like…

# Generated via
#  `rails generate hyrax:work GenericWork`
module Hyrax
  class GenericWorkForm < Hyrax::Forms::WorkForm
    self.model_class = ::GenericWork
    self.terms += [:resource_type]
  end
end

NOTE:

As generated, model_class is the generated model class
As generated, terms includes basic work terms defined in Hyrax’s work_form.rb.
A controller class was also generated and configures form_class to be the one described here, e.g., self.form_class = Hyrax::Forms::GenericWorkForm

Notable WorkForm methods

This class inherits from Hyrax::Forms::WorkForm which has several methods of note.

Method	Description	Overridden?

Method	Description	Overridden?
terms	Returns an array of all terms that will be displayed on the form.	Common
required_fields	Returns an array of terms that are required and will be displayed at the top of the form (above the fold). They will be visible when the new/edit form is initially displayed.	Common
primary_terms	Returns the required_fields array.	NO
secondary_terms	Returns the array of terms that are optional and will be displayed at the bottom of the form (below the fold). These fields are hidden until the user clicks `Additional fields` button. This method also removes fields that are not filled in by a user for various reasons (e.g. populated by the system, displayed on another tab, set based on data in other fields, etc.).	Sometimes
multiple?	Given a field, return true if it is multi-value. This is sometimes overridden to force a basic multi-value metadata field provided by the system to be single-value.	Sometimes
sanitize_params	Clean up params passed back from the form. This is sometimes overridden to put a single-value into the format of a multi-value metadata field for basic multi-value metadata that was forced to be single-value.	Sometimes

See Other Metadata Customizations in section Making a default property single-value for an example of when you would override multiple? and sanitize_params.

Adding the properties to the work-type’s new/edit form

Now we want to update GenericWorkForm to include each of the new properties. Edit app/forms/hyrax/generic_work_form.rb and modify self.terms to include all the new properties on the new/edit form. See Defining Metadata in the Model in section The modified model to see which properties were added as part of this tutorial.

self.terms += [:resource_type, :contact_email, :contact_phone, :department]

Optionally, you can add properties to the set of required fields. In this example, we will require the department and contact email.

self.required_fields += [:department, :contact_email]

Optionally, you can also remove one of the basic properties defined by Hyrax from the set of required fields. See Other Metadata Customization in section Remove a default property from the set of required fields for an example of removing a basic metadata property from the set of required properties.

The modified work class

The full class after the changes looks like…

Default form field behavior

Default behavior:

By adding the property to self.terms, it will be added to the new/edit form.
Without additional customization, the field will be a text input field. (See Sufia’s app/views/records/edit_fields/_default.html.erb
For contact_email and department, because we did NOT set multiple: true in the model, there will be only a single value set for this property.
For contact_phone, because we DID set multiple: true in the model, there will be an Add another link below these fields allowing for multiple values to be set.
Because we added contact_email to the required_fields set, it will be displayed as required on the initial display of metadata fields on the form.
Because we did NOT add contact_phone and department to the required_fields set, they will only display in the form when you click the Additional Fields button.

Customizing the form field

To customize a form field, you create a partial with the property name under app/views/records/edit_fields. Add form code to display the form as desired. If this is the first form field customization you have made, you will need to create the records/edit_fields directories under app/views.

You can see more examples by exploring those created for the default fields in Sufia.

For a single-value field (optional)

Use something similar to…

For a multi-value field (optional)

Use something similar to…

For a controlled vocabulary field (required)

You must customize the creation of the form field to use autocomplete with a controlled vocabulary. You can use one of the external authorities with access provided through the Questioning Authority gem. Or you can create your own controlled vocabulary. This tutorial includes instructions for defining a simple local controlled vocabulary.

For a controlled-value field, you can use something similar to…

For additional instructions, see Hyrax Autocomplete.