Page History

...

...

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 follows:

<input-forms>

    <--  Form Set Definitions

<input-forms>

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

    <--  Name/Value Pairs used within Multiple Choice Widgets -->
    <form-value-pairs>definitions>
        <value-pairs value-pairs-<form name="common_iso_languages" dc-term="language_iso">
  traditionalpageone">
             ...
        </value-pairs>form>
        ...
    </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):

...

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>

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

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

...

1. "item-submission.xml"

...

1. , a <submission-process> must be created/updated to use that newly defined "step".
2. 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

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.

...

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

Modifying metadata form presented for Bitstreams

After uploading a file (bitstream) in the Submission UI, you can optionally edit that bitstream's metadata.  The form displayed on that edit screen is built by the "bitstream-metadata" form defined in submission-forms.xml.  You can modify that form to change the fields captured for a Bitstream.  However, the "dc.title" field is REQUIRED in order to store the name of the file.

<form-definitions>
    <!-- Form used for entering in Bitstream/File metadata after uploading a file -->
    <form name="bitstream-metadata">
        ...
    </form>
</form-definitions>

Modifying access conditions (embargo, etc) presented for Bitstreams

After uploading a file (bitstream) in the Submission UI, you can optionally edit that bitstream's access conditions.  This allows you to embargo a bitstream, lease it, or limit it to Administrators only.

These access conditions are defined in a new Spring Bean configuration file [dspace]/config/spring/api/access-conditions.xml

• The "uploadConfigurationDefault" bean defines the list of options which are present on the "bitstream-metadata" form by default.  You can comment out one of these options, to disable it, or add more (requires adding a corresponding bean with that "id").
• Any number of "AccessConditionOption" beans may be added for different scenarios. These beans are easy to add/update, and just require the following
  • ID: Each defined bean MUST have a unique "id" and have "class=org.dspace.submit.model.AccessConditionOption"
  • groupName: Optionally, define a DSpace Group which this Access Condition relates to
  • name: Give a name for this Access Condition
  • hasStartDate: If the access condition is time-based, you can enable/disable whether a start date is required. (true = required start date, false = disabled/not required)
  • startDateLimit: If the access condition is time-based, you can optionally set an start date limit (e.g. +36MONTHS). This is used for validation & means the start date cannot be later (in the future) than this limit.
  • hasEndDate: If the access condition is time-based, you can enable/disable whether an end date is required. (true = required end date, false = disabled/not required)
  • endDateLimit: If the access condition is time-based, you can optionally set an end date limit (e.g. +6MONTHS). This is used for validation & means the end date cannot be later (in the future) than this limit.
• By default, DSpace comes with three out-of-the-box Access Conditions (which you can configure based on local needs)
  • "administrator" - access restricts the bitstream to the Administrator group immediately (after submission completes)
  • "openAccess" - makes the bitstream immediately accessible to Anonymous group (after submission completes)
  • "embargo" - embargoes the bitstream for a period of time (maximum of 3 years, as defined in startDateLimit default setting), after which it becomes anonymously accessible.
  • "lease" - makes the bitstream anonymously accessible immediately (after submission completes), but that access expires  after a period of time (maximum of 6 months, as defined in endDateLimit default setting). After that date it is no longer accessible (except to Administrators)

Deploying Your Custom Forms

...