Versions Compared

Old Version 7

changes.mady.by.user Tim Donohue

Saved on

compared with

New Version 8

changes.mady.by.user Tim Donohue

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

The ordering of <step> definitions matters!

The ordering of the <step> tags within a <submission-process> definition directly corresponds to the order in which those steps will appear!

...

Each step contains the following elements. The required elements are so marked:

  • *heading*: Partial I18N key (defined in Messages.properties for JSPUI or messages.xml for XMLUI) which corresponds to the text that should be displayed in the submission Progress Bar for this step. This partial I18N key is prefixed within either the Messages.properties or messages.xml file, depending on the interface you are using. Therefore, to find the actual key, you will need to search for the partial key with the following prefix:
    • XMLUI: prefix is xmlui.Submission. (e.g. "xmlui.Submission.submit.progressbar.describe" for 'Describe' step)
    • JSPUI: prefix is jsp. (e.g. "jsp.submit.progressbar.describe" for 'Describe' step)The 'heading' need not be defined if the step should not appear in the progress bar (e.g. steps which perform automated processing, i.e. non-interactive, should not appear in the progress bar).
  • *processing-class (Required): Full Java path to the Processing Class for this Step. This Processing Class must perform the primary processing of any information gathered in this step, for both the XMLUI and JSPUI. All valid step processing classes must extend the abstract `org.dspace.submit.AbstractProcessingStep` class (or alternatively, extend one of the pre-existing step processing classes in org.dspace.submit.step.*)
  • *jspui-binding*: Full Java path of the JSPUI "binding" class for this Step. This "binding" class should initialize and call the appropriate JSPs to display the step's user interface. A valid JSPUI "binding" class must extend the abstract `org.dspace.app.webui.submit.JSPStep` class. This property need not be defined if you are using the XMLUI interface, or for steps which only perform automated processing, i.e. non-interactive steps.
  • *xmlui-binding*: Full Java path of the XMLUI "binding" class for this Step. This "binding" class should generate the Manakin XML (DRI document) necessary to generate the step's user interface. A valid XMLUI "binding" class must extend the abstract `org.dspace.app.xmlui.submission.AbstractSubmissionStep` class. This property need not be defined if you are using the JSPUI interface, or for steps which only perform automated processing, i.e. non-interactive steps.
  • *workflow-editable*: Defines whether or not this step can be edited during the Edit Metadata process with the DSpace approval/rejection workflow process. Possible values include true and false. If undefined, defaults to true (which means that workflow reviewers would be allowed to edit information gathered during that step).

...

  1. Locate the <submission-process> tag which defines the Submission Process that you are using. If you are unsure which Submission Process you are using, it's likely the one with name="traditional", since this is the traditional DSpace submission process.
  2. Reorder the <step> tags within that <submission-process> tag. Be sure to move the entire<step> tag (i.e. everything between and including the opening <step> and closing </step> tags).
    • Hint #1: The <step> defining the Review/Verify step only allows the user to review information from steps which appear before it. So, it's likely you'd want this to appear as one of your last few steps
    • Hint #2: If you are using it, the <step> defining the Initial Questions step should always appear before the Upload or Describe steps since it asks questions which help to set up those later steps.

Removing one or more steps

  1. Locate the <submission-process> tag which defines the Submission Process that you are using. If you are unsure which Submission Process you are using, it's likely the one with name="traditional", since this is the traditional DSpace submission process.
  2. Comment out (i.e. surround with <!-- and -->) the <step> tags which you want to remove from that <submission-process> tag. Be sure to comment out the entire {{<step>}}tag (i.e. everything between and including the opening _<step> and closing </step> tags).
    • Hint #1: You cannot remove the Select a Collection step, as an DSpace Item cannot exist without belonging to a Collection.
    • Hint #2: If you decide to remove the <step> defining the Initial Questions step, you should be aware that this may affect your Describe and Upload steps! The Initial Questions step asks questions which help to initialize these later steps. If you decide to remove the Initial Questions step you may wish to create a custom, automated step which will provide default answers for the questions asked!

...

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:

...

  • 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.*

NOTE: 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.

...

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.
  • *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.

...

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

...

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

*Identifiers:*Gov't Doc #URIISBN

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.

...