Page History

...

All of the custom metadata-entry forms for a DSpace instance are controlled by a single XML file, submission-forms.xml, in the config subdirectory under the DSpace home, [dspace]/config/submission-forms.xml. DSpace comes with a number of sample forms which implement the traditional metadata-entry forms, and also serves as a well-documented example.  Some default forms include:

...

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 fields through which submitters enter their metadata is called a form (although it is actually a set of forms, in the HTML sense of the termin the UI, each "form" is displayed in a separate collapsible section). 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>
        ...
    </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">
            ...
        </value-pairs>
        ...
    </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.

rows of fields. This allows you to place smaller fields side-by-side in a single, horizontal row, or alternatively decide to display one field per row.

The Structure of submission-forms.xml

The XML configuration file has a single top-level element, input-forms, which contains two elements in a specific order. The outline is as followsFor example, the following fragment shows how the collection with handle "12345.6789/42" is attached to the "TechRpt" form set:

<input-forms>

    <--  Form Set Definitions <form--map>>
    <form-definitions>
    <name-map collection-handle=" 12345.6789/42" form-    <form name=" TechRpttraditionalpageone"/>
            ...
        </form-map>form>
        ...
    <form</form-definitions>

    <--  Name/Value Pairs used <form name="TechRept"within Multiple Choice Widgets -->
    <form-value-pairs>
    ...
    </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-schema (Required) : Name of metadata schema employed, e.g. dc for Dublin Core. This value must match the value of the schema element defined in dublin-core-types.xml
• 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.
• language: If set to true a drop down menu will be shown, containing languages. The selected language will be used as language tag of the metadata field. This feature is currently supported by JSPUI only and only valid for fields of input-type onebox, twobox or textarea. A compulsory argument value-pairs-name must be given containing the name of the value pair that contains all the languages: e.g. <language value-pairs-name="common_iso_languages">true</language>. If the submission configuration contains a language element and the XMLUI is used, no language is stored, even not the default one.
• 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. Note: The 'twobox' input type is rendered the same as a 'onebox' in the XML-UI, but both allow for ease of adding multiple values.
  • 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. When saved they are appended in the format 'LastName, FirstName'
  • date – Calendar date. When required, demands that at least the year be entered.
  • series – Series/Report name and number. Separate fields are provided for series name and series number, but they are appended (with a semicolon between) when saved.
  • 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. 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 identifiers 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.
  • list – Choose value(s) from a checkbox or radio button list. If the repeatable attribute is set to true, a list of checkboxes is displayed. If the repeatable attribute is set to false, a list of radio buttons is displayed. Note: You must also include a value for the value-pairs-name attribute to specify a list of values from which to choose.
• 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>
• visibility: When this optional element is included with a value, it restricts the visibility of the field to the scope defined by that value. If the element is missing or empty, the field is visible in all scopes. Currently supported scopes are:
  
  • workflow : the field will only be visible in the workflow stages of submission. This is good for hiding difficult fields for users, such as subject classifications, thereby easing the use of the submission system.
  • submit : the field will only be visible in the initial submission, and not in the workflow stages. In addition, you can decide which type of restriction apply: read-only or full hidden the field (default behaviour) using the otherwise attribute of the visibility XML element. For example:<visibility otherwise="readonly">workflow</visibility> Note that it is considered a configuration error to limit a field's scope while also requiring it - an exception will be generated when this combination is detected.
    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.

For the use of controlled vocabularies see the Configuring Controlled Vocabularies section.

Item type Based Metadata Collection

This feature is available for use with the XMLUI since DSpace 3.0 and with JSPUI since 3.1. A field can be made visible depending on the value of dc.type. A new field element, <type-bind>, has been introduced to facilitate this. In this example the field will only be visible if a value of "thesis" or "ebook" has been entered into dc.type on an earlier page:

<field>
    <dc-schema>dc</dc-schema>
    <dc-element>identifier</dc-element>
    <dc-qualifier>isbn</dc-qualifier>
    <label>ISBN</label>
    <type-bind>thesis,ebook</type-bind>
</field>

Automatically Omitted 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 omitted, 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:

1. The item has more than one title, e.g. a translated title Controls title.alternative field.
2. The item has been published or publicly distributed before Controls DC fields:
   • date.issued
   • publisher
   • identifier.citation
3. 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 omitted from the initial page to avoid confusing or misleading the user.

...

<value-pairs value-pairs-name="common_iso_languages" dc-term="language_iso">
            ...
        </value-pairs>
        ...
    </form-value-pairs>
</input-forms>

Using a form in a submission process for a Collection

Keep in mind, the "submission-forms.xml" only defines forms and value-pairs (used for specific fields like selectboxes).  To enable a form requires also updating the "item-submission.xml" configuration to use that form (see also above):

1. In "item-submission.xml",  a <step-definition> of type "submission-form" must be created, with an "id" matching the name of the form  (see above for more details on step-definition)
2. In "item-submission.xml", a <submission-process> must be created/updated to use that newly defined "step".
3. Finally, also in "item-submission.xml", a Collection must be setup to use that submission process in the <submission-map> section.

So, if you modify submission-forms.xml, you may need to double check your changes will be used in your item-submission.xml.

Adding a Form

You can add a new form by creating a new form element within the form-definitions element. It has one attribute, name, which as described above must match the "id" of a <step-definition> in "item-submission.xml".

Forms and Pages

The content of the form is a sequence of row elements. Each of these corresponds to a single, horizontal row, containing metadata input fields. The rows are presented in sequence, with the first row displayed at the top of the form.  A form is displayed as a section (or step) within the submission process.

A form may contain any number of rows. A row generally only contains one or two input fields (including more than one input field may require the "style" setting, see below). 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-schema (Required) : Name of metadata schema employed, e.g. dc for Dublin Core. This value must match the value of the schema element defined in dublin-core-types.xml
• 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.
• language:  If set to true a drop down menu will be shown, containing languages. The selected language will be used as language tag of the metadata field. A compulsory argument value-pairs-name must be given containing the name of the value pair that contains all the languages: e.g. <language value-pairs-name="common_iso_languages">true</language>. 
• repeatable: Value is true when multiple values of this field are allowed, false otherwise. When you mark a field repeatable, the UI will add an "Add more" control to the field, allowing the user to 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.  Repeatable fields also support reordering of values.
• 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 (i.e. a normal input textbox)
  • twobox – A pair of simple text-entry boxes, used for repeatable values. (By default, this input type is unused.)
  • 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. When saved they are appended in the format 'LastName, FirstName'.  (By default, this input type is unused. Author fields now use the "onebox" type to support different types of names.)
  • date – Calendar date. When required, demands that at least the year be entered.
  • series – Series/Report name and number. Separate fields are provided for series name and series number, but they are appended (with a semicolon between) when saved.
  • 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. 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 identifiers 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.
  • list – Choose value(s) from a checkbox or radio button list. If the repeatable attribute is set to true, a list of checkboxes is displayed. If the repeatable attribute is set to false, a list of radio buttons is displayed. Note: You must also include a value for the value-pairs-name attribute to specify a list of values from which to choose. (By default, this input type is unused.)
  • tag - A free-text field which allows you to add multiple labels/tags as values. An example is the "Subject Keywords" field. Note: A tag field MUST be marked as repeatable.
• hint (Required): Content is the text that will appear as a "hint", or instructions, below the input field. Can be left empty, but the tag must be present.
• required: When this element is included with any content, it marks the field as a required input. If the user saves the form 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>
• vocabulary: When specified, this field uses a controlled vocabulary defined in [dspace]/config/controlled-vocabularies/[name].xml. This setting may be used to provide auto-complete functionality, for example in the "Subject Keywords" field (which uses the "tag" input type).  See also the "Configuring Controlled Vocabularies" section below.
• regex: When specified, this field will be validated against the Regular Expression, and only successfully validating values will be saved.  An example is commented out in the default "Author" field.
• style: When specified, this provides a CSS style recommendation to the UI for how to style that field. This is primarily used when displaying multiple fields per row, so that you can tell the UI how many columns each field should use in that row.  Keep in mind, these styles should follow the Bootstrap Grid System, where the number of columns adds up to 12.  An example can be see in the default "Date of Issue" and "Publisher" fields, which are configured to use 4 (col-sm-4) and 8 (col-sm-8) columns respectively.

Item type Based Metadata Collection

A field can be made visible depending on the value of dc.type. A new field element, <type-bind>, has been introduced to facilitate this. In this example the field will only be visible if a value of "thesis" or "ebook" has been entered into dc.type on an earlier page:

<field>
    <dc-schema>dc</dc-schema>
    <dc-element>identifier</dc-element>
    <dc-qualifier>isbn</dc-qualifier>
    <label>ISBN</label>
    <type-bind>thesis,ebook</type-bind>
</field>

Configuring Controlled Vocabularies

DSpace now supports controlled vocabularies to confine the set of keywords that users can use while describing items.  The The need for a limited set of keywords is important since it eliminates the ambiguity of a free description system, consequently simplifying the task of finding specific items of information. The controlled vocabulary allows the user to choose from a defined set of keywords organised organized in an tree (taxonomy) and then use these keywords to describe items while they are being submitted.

...