The Structure of item-submission.xml
<item-submission> <!-- Where submission processes are mapped to specific Collections --> <submission-map> <name-map collection-handle="default" submission-name="traditional" /> ... </submission-map> <!-- Where "steps" which are used across many submission processes can be defined in a single place. They can then be referred to by ID later. --> <step-definitions> <step id="collection"> <processing-class>org.dspace.submit.step.SelectCollectionStep</process;/processing-class> <workflow-editable>false</workflow-editable> </step> ... </step-definitions> <!-- Where actual submission processes are defined and given names. Each <submission-process> has many <step> nodes which are in the order that the steps should be in.--> <submission-definitions> <submission-process name="traditional"> ... <!-- Step definitions appear here! --> </submission-process> ... </submission-definitions> </item-submission>
- Within the <step-definitions>section
- This is for globally defined <step> definitions (i.e. steps which are used in multiple <submission-process> definitions). Steps defined in this section must define a unique id which can be used to reference this step.
Code Block language html/xml
<step-definitions> <step id="custom-step"> ... </step> ... </step-definitions>
- The above step definition could then be referenced from within a <submission-process> as simply <step id="custom-step"/>
- Within a specific <submission-process>definition
- This is for steps which are specific to a single <submission-process> definition.
Code Block language html/xml
<submission-process> <step> ... </step> </submission-process>
For example, the following defines a Submission Process where the License step directly precedes the Initial Questions step (more information about the structure of the information under each <step> tag can be found in the section on Structure of the <step> Definition below):
<submission-process> <!--Step 1 will be to Sign off on the License--> <step> <heading>submit.progressbar.license</heading> <processing-class>org.dspace.submit.step.LicenseStep</processing-classing-class> <jspui-binding>org.dspace.app.webui.submit.step.JSPLicenseStep</jspui-binding> <xmlui-binding>org.dspace.app.xmlui.aspect.submission.submit.LicenseStenseStep</xmlui-binding> <workflow-editable>false</workflow-editable> </step> <!--Step 2 will be to Ask Initial Questions--> <step> <heading>submit.progressbar.initial-questions</heading> <processing-class>org.dspace.submit.step.InitialQuestionsStep</process;/processing-class> <jspui-binding>org.dspace.app.webui.submit.step.JSPInitialQuestionsSteonsStep</jspui-binding> <xmlui-binding>org.dspace.app.xmlui.aspect.submission.submit.InitialQutialQuestionsStep</xmlui-binding> <workflow-editable>true</workflow-editable> </step> ...[other steps]... </submission-process>
The structure of the <step> Definition is as follows:
<step> <heading>submit.progressbar.describe</heading> <processing-class>org.dspace.submit.step.DescribeStep</processing-classing-class> <jspui-binding>org.dspace.app.webui.submit.step.JSPDescribeStep</jspuilt;/jspui-binding> <xmlui-binding>org.dspace.app.xmlui.aspect.submission.submit.DescribeScribeStep</xmlui-binding> <workflow-editable>true</workflow-editable> </step>
For example, the following fragment shows how the collection with handle "12345.6789/42" is assigned the "custom" submission process:
<submission-map> <name-map collection-handle=" 12345.6789/42" submission-name=" custom" /> ... </submission-map> <submission-definitions> <submission-process name=" custom"> ... </submission-definitions>
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>
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>
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.
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.
- 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.
- 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.
This feature is currently only available for use with the XMLUI. 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 'theses' or 'ebook' "thesis" or "ebook" has been entered for into dc.type on an earlier page:-
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 elidedomitted, even on custom submission pages.
- The item has more than one title, e.g. a translated title Controls title.alternative field.
- The item has been published or publicly distributed beforebefore Controls DC fields:
- 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 omitted 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.