Custom Metadata-entry Pages for Submission

Introduction

This section explains how to customize the Web forms used by submitters and editors to enter and modify the metadata for a new item.

You can customize the "default" metadata forms used by all collections, and also create alternate sets of metadata forms and assign them to specific collections. In creating custom metadata forms, you can choose:

The number of metadata-entry pages.
Which fields appear on each page, and their sequence.
Labels, prompts, and other text associated with each field.
List of available choices for each menu-driven field.

N.B.The cosmetic and ergonomic details of metadata entry fields remain the same as the fixed metadata pages in previous DSpace releases, and can only be altered by modifying the appropriate stylesheet and JSP pages.

All of the custom metadata-entry forms for a DSpace instance are controlled by a single XML file, input-forms.xml, in the config subdirectory under the DSpace home. DSpace comes with a sample configuration that implements the traditional metadata-entry forms, which also serves as a well-documented example. The rest of this section explains how to create your own sets of custom forms.

Describing Custom Metadata Forms

The description of a set of pages through which submitters enter their metadata is called a form (although it is actually a set of forms, in the HTML sense of the term). A form is identified by a unique symbolic name. In the XML structure, the form is broken down into a series of pages: each of these represents a separate Web page for collecting metadata elements.

To set up one of your DSpace collections with customized submission forms, first you make an entry in the form-map. This is effectively a table that relates a collection to a form set, by connecting the collection's Handle to the form name. Collections are identified by handle because their names are mutable and not necessarily unique, while handles are unique and persistent.

A special map entry, for the collection handle "default", defines the default form set. It applies to all collections which are not explicitly mentioned in the map. In the example XML this form set is named traditional (for the "traditional" DSpace user interface) but it could be named anything.

The Structure of `input-forms.xml`

The XML configuration file has a single top-level element, input-forms, which contains three elements in a specific order. The outline is as follows:

<input-forms>

  <-- Map of Collections to Form Sets -->
  <form-map>
    <name-map collection-handle="default" form-name="traditional" />
    ...
  </form-map>

  <-- Form Set Definitions -->
  <form-definitions>
    <form name="traditional">
    ...
  </form-definitions>

  <-- Name/Value Pairs used within Multiple Choice Widgets -->
  <form-value-pairs>
    <value-pairs value-pairs-name="common_iso_languages" dc-term="language_iso">
    ...
  </form-value-pairs>
</input-forms>

Adding a Collection Map

Each name-map element within form-map associates a collection with the name of a form set. Its collection-handle attribute is the Handle of the collection, and its form-name attribute is the form set name, which must match the name attribute of a form element.

For example, the following fragment shows how the collection with handle "12345.6789/42" is attached to the "TechRpt" form set:

  <form-map>
    <name-map collection-handle="12345.6789/42" form-name="TechRpt" />
    ...
  </form-map>

  <form-definitions>
    <form name="TechRept">
    ...
  </form-definitions>

It's a good idea to keep the definition of the default name-map from the example input-forms.xml so there is always a default for collections which do not have a custom form set.

Getting A Collection's Handle

You will need the handle of a collection in order to assign it a custom form set. To discover the handle, go to the "Communities & Collections" page under "Browse" in the left-hand menu on your DSpace home page. Then, find the link to your collection. It should look something like:

    http://myhost.my.edu/dspace/handle/12345.6789/42

The underlined part of the URL is the handle. It should look familiar to any DSpace administrator. That is what goes in the collection-handle attribute of your name-map element.

Adding a Form Set

You can add a new form set by creating a new form element within the form-definitions element. It has one attribute, name, which as seen above must match the value of the name-map for the collections it is to be used for.

Forms and Pages

The content of the form is a sequence of page elements. Each of these corresponds to a Web page of forms for entering metadata elements, presented in sequence between the initial "Describe" page and the final "Verify" page (which presents a summary of all the metadata collected).

A form must contain at least one and at most six pages. They are presented in the order they appear in the XML. Each page element must include a number attribute, that should be its sequence number, e.g.

<page number="1">

The page element, in turn, contains a sequence of field elements. Each field defines an interactive dialog where the submitter enters one of the Dublin Core metadata items.

Composition of a Field

Each field contains the following elements, in the order indicated. The required sub-elements are so marked:

dc-element (Required)

Name of the Dublin Core element entered in this field, e.g. contributor.

dc-qualifier

Qualifier of the Dublin Core element entered in this field, e.g. when the field is contributor.advisor the value of this element would be advisor. Leaving this out means the input is for an unqualified DC element.

repeatable

Value is true when multiple values of this field are allowed, false otherwise. When you mark a field repeatable, the UI servlet will add a control to let the user ask for more fields to enter additional values. Intended to be used for arbitrarily-repeating fields such as subject keywords, when it is impossible to know in advance how many input boxes to provide.

label (Required)

Text to display as the label of this field, describing what to enter, e.g. "Your Advisor's Name".

input-type (Required)

Defines the kind of interactive widget to put in the form to collect the Dublin Core value. Content must be one of the following keywords:

onebox -- A single text-entry box.
twobox -- A pair of simple text-entry boxes, used for repeatable values such as the DC subject item.
textarea -- Large block of text that can be entered on multiple lines, e.g. for an abstract.
name -- Personal name, with separate fields for family name and first name.
date -- Calendar date. when required, demands that at least the year be entered.
dropdown -- Choose value(s) from a "drop-down" menu list. Note: You must also include a value for the value-pairs-name attribute to specify a list of menu entries, from which to choose, for this item. Use this to make a choice from a restricted set of options, such as for the language item.
qualdrop_value -- Enter a "qualified value", which includes both a qualifier from a drop-down menu and a free-text value. Used to enter items like alternate identifers and codes for a submitted item, e.g. the DC identifier field. Note: As for the dropdown type, you must include the value-pairs-name attribute to specify a menu choice list.

hint (Required)

Content is the text that will appear as a "hint", or instructions, next to the input fields. Can be left empty, but it must be present.

required

When this element is included with any content, it marks the field as a required input. If the user tries to leave the page without entering a value for this field, that text is displayed as a warning message. For example,

<required>You must enter a title.</required>

    Note that leaving the

required element empty will not mark a field as required, e.g.:
<required></required>

Look at the example input-forms.xml and experiment with a a trial custom form to learn this specification language thoroughly. It is a very simple way to express the layout of data-entry forms, but the only way to learn all its subtleties is to use it.

Automatically Elided Fields

You may notice that some fields are automatically skipped when a custom form page is displayed, depending on the kind of item being submitted. This is because the DSpace user-interface engine skips Dublin Core fields which are not needed, according to the initial description of the item. For example, if the user indicates there are no alternate titles on the first "Describe" page (the one with a few checkboxes), the input for the title.alternative DC element is automatically elided, even on custom submission pages.

When a user initiates a submission, DSpace first displays what we'll call the "initial-questions page". By default, it contains three questions with check-boxes:

The item has more than one title, e.g. a translated title
Controls title.alternative field.
The item has been published or publicly distributed before
Controls DC fields:
- date.issued
- publisher
- identifier.citation
The item consists of more than one file
Does not affect any metadata input fields.

The answers to the first two questions control whether inputs for certain of the DC metadata fields will displayed, even if they are defined as fields in a custom page.

Conversely, if the metadata fields controlled by a checkbox are not mentioned in the custom form, the checkbox is elided from the initial page to avoid confusing or misleading the user.

The two relevant checkbox entries are "The item has more than one title, e.g. a translated title", and "The item has been published or publicly distributed before". The checkbox for multiple titles trigger the display of the field with dc-element equal to 'title' and dc-qualifier equal to 'alternative'. If the controlling collection's form set does not contain this field, then the multiple titles question will not appear on the initial questions page.

Adding `Value-Pairs`

Finally, your custom form description needs to define the "value pairs" for any fields with input types that refer to them. Do this by adding a value-pairs element to the contents of form-value-pairs. It has the following required attributes:

value-pairs-name -- Name by which an input-type refers to this list.
dc-term -- Qualified Dublin Core field for which this choice list is selecting a value.

Each value-pairs element contains a sequence of pair sub-elements, each of which in turn contains two elements:

displayed-value -- Name shown (on the web page) for the menu entry.
stored-value -- Value stored in the DC element when this entry is chosen.

Unlike the HTML select tag, there is no way to indicate one of the entries should be the default, so the first entry is always the default choice.

Example

Here is a menu of types of common identifiers:

   <value-pairs value-pairs-name="common_identifiers" dc-term="identifier">
     <pair>
       <displayed-value>Gov't Doc #</displayed-value>
       <stored-value>govdoc</stored-value>
     </pair>
     <pair>
       <displayed-value>URI</displayed-value>
       <stored-value>uri</stored-value>
     </pair>
     <pair>
       <displayed-value>ISBN</displayed-value>
       <stored-value>isbn</stored-value>
     </pair>
   </value-pairs>

It generates the following HTML, which results in the menu widget below. (Note that there is no way to indicate a default choice in the custom input XML, so it cannot generate the HTML SELECTED attribute to mark one of the options as a pre-selected default.)

<select name="identifier_qualifier_0">
<option VALUE="govdoc">Gov't Doc #</option>
<option VALUE="uri">URI</option>
<option VALUE="isbn">ISBN</option>
</select>

Deploying Your Custom Forms

The DSpace web application only reads your custom form definitions when it starts up, so it is important to remember:

You must always restart Tomcat (or whatever servlet container you are using) for changes made to the input-forms.xml file take effect.

Any mistake in the syntax or semantics of the form definitions, such as poorly formed XML or a reference to a nonexistent field name, will cause a fatal error in the DSpace UI. The exception message (at the top of the stack trace in the dspace.log file) usually has a concise and helpful explanation of what went wrong. Don't forget to stop and restart the servlet container before testing your fix to a bug.