Date: Thu, 28 Mar 2024 05:08:50 -0400 (EDT) Message-ID: <1859743639.27300.1711616930028@lyrasis1-roc-mp1> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_27299_1555174010.1711616930028" ------=_Part_27299_1555174010.1711616930028 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
This page explains various customization and configuration options that = are available within DSpace for the Item Submission user interface.
The [dspace]/config/item-submission.xml contains the submission= configurations for both the DSpace JSP user interface (JSPUI) or = the DSpace XML user interface (XMLUI or Manakin). This configuration file c= ontains detailed documentation within the file itself, which should help yo= u better understand how to best utilize it.
<ite= m-submission> =09<!-- Where submission processes are mapped to specific Collections --= > =09<submission-map> =09<name-map collection-handle=3D"default" submission-name=3D"traditiona= l" /> ... =09</submission-map> =09<!-- Where "steps" which are used across many submission processes ca= n be defined in a =09 single place. They can then be referred to by ID later. --> =09<step-definitions> =09<step id=3D"collection"> =09<processing-class>org.dspace.submit.step.SelectCollectionStep</= process;/processing-class> =09<workflow-editable>false</workflow-editable> =09</step> =09=09... =09</step-definitions> =09<!-- Where actual submission processes are defined and given names. E= ach <submission-process> has =09 many <step> nodes which are in the order that the steps should = be in.--> =09<submission-definitions> <submission-process name=3D"traditiona= l"> =09 ... =09<!-- Step definitions appear here! --> =09</submission-process> =09 ... =09</submission-definitions> =09</item-submission>
Because this file is in XML format, you should be familiar with XML befo= re editing this file. By default, this file contains the "traditional" Item= Submission Process for DSpace, which consists of the following Steps (in t= his order):
Select Collection -> Initial Questions -> Describe -> Uploa= d -> Verify -> License -> Complete
If you would like to customize the steps used or the ordering of the ste= ps, you can do so within the <submission-definition> section= of the item-submission.xml .
In addition, you may also specify different Submission Processes for dif= ferent DSpace Collections. This can be done in the <submission-map&g= t; section. The item-submission.xml file itself documents the= syntax required to perform these configuration changes.
This section describes how Steps of the Submission Process are defined w= ithin the item-submission.xml.
<step> definitions can appear in one of two places within= the item-submission.xml configuration file.
<ste= p-definitions> =09<step id=3D"custom-step"> =09 ... =09</step> =09 ... </step-definitions>
<sub= mission-process> =09<step> =09 ... =09</step> </submission-process>
The ordering of the <step> tags within a <submissi= on-process> definition directly corresponds to the order in which t= hose steps will appear!
For example, the following defines a Submission Process where the Li= cense 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> Definitio= n below):
<sub= mission-process> =09<!--Step 1 will be to Sign off on the License--> =09 <step> =09 <heading>submit.progressbar.license</heading> =09 <processing-class>org.dspace.submit.step.LicenseStep</proc= essing-classing-class> =09 <jspui-binding>org.dspace.app.webui.submit.step.JSPLicenseSte= p</jspui-binding> =09 <xmlui-binding>org.dspace.app.xmlui.aspect.submission.submit.= LicenseStenseStep</xmlui-binding> =09 <workflow-editable>false</workflow-editable> =09 </step> =09<!--Step 2 will be to Ask Initial Questions--> =09<step> =09 <heading>submit.progressbar.initial-questions</heading> =09 <processing-class>org.dspace.submit.step.InitialQuestionsSte= p</process;/processing-class> =09 <jspui-binding>org.dspace.app.webui.submit.step.JSPInitialQu= estionsSteonsStep</jspui-binding> =09 <xmlui-binding>org.dspace.app.xmlui.aspect.submission.submit= .InitialQutialQuestionsStep</xmlui-binding> =09 <workflow-editable>true</workflow-editable> =09 </step> =09 ...[other steps]... </submission-process>
The same <step> definition is used by both the DSpace JSP user int= erface (JSPUI) an the DSpace XML user interface (XMLUI or Manakin). Therefo= re, you will notice each <step> definition contains information speci= fic to each of these two interfaces.
The structure of the <step> Definition is as follows:
<ste= p> =09<heading>submit.progressbar.describe</heading> =09<processing-class>org.dspace.submit.step.DescribeStep</processi= ng-classing-class> =09<jspui-binding>org.dspace.app.webui.submit.step.JSPDescribeStep<= ;/jspuilt;/jspui-binding> =09<xmlui-binding>org.dspace.app.xmlui.aspect.submission.submit.Descr= ibeScribeStep</xmlui-binding> =09<workflow-editable>true</workflow-editable> </step>
Each step contains the following elements. The required element= s are so marked:
org.dspace.submit.AbstractProcessingStep
class (or a=
lternatively, extend one of the pre-existing step processing classes in org.dspace.app.webui.submit.=
JSPStep
class. This property need not be defined if you are usin=
g the XMLUI interface, or for steps which only perform automated processing=
, i.e. non-interactive steps.org.dspace.app.xml=
ui.submission.AbstractSubmissionStep
class. This property need n=
ot be defined if you are using the JSPUI interface, or for steps which only=
perform automated processing, i.e. non-interactive steps.The removal of existing steps and reordering of existing steps is a rela= tively easy process!
Reordering steps
Removing one or more steps
<!--
and -->=
code>) the <step>
tags which you want to remove from tha=
t <submission-process> tag. Be sure to comment out the e=
ntire {{<step>}}tag (i.e. everything between and including the openin=
g _<step> and closing </step> tags).=20
- Hint #1: You cannot remove the Select a Collection st=
ep, as an DSpace Item cannot exist without belonging to a Collection.
- Hint #2: If you decide to remove the <step> def=
ining the Initial Questions step, you should be aware that this ma=
y affect your Describe and Upload steps! The Initial =
Questions step asks questions which help to initialize these later ste=
ps. If you decide to remove the Initial Questions step you may wis=
h to create a custom, automated step which will provide default answers for=
the questions asked!
Assigning a custom submission process to a Collection in DSpace involves= working with the submission-map section of the item-submissio= n.xml. For a review of the structure of the item-submission.xml see the section above on Understanding the Submission Configuration File= .
Each name-map element within submission-map associates=
a collection with the name of a submission definition. Its collection-=
handle attribute is the Handle of the collection. Its submission-n=
ame attribute is the submission definition name, which must match the =
name attribute of a submission-process element (in the
For example, the following fragment shows how the collection with handle= "12345.6789/42" is assigned the "custom" submission process:
<sub= mission-map> <name-map collection-handle=3D" 12345.6789/42" submission-name=3D" =09custom" /> ... </submission-map> <submission-definitions> <submission-process name=3D" =09custom"> ... </submission-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.
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 & Col= lections" page under "Browse" in the left-hand menu on your DSpace home pag= e. Then, find the link to your collection. It should look something like:= p>
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= em> attribute of your name-map element.
This section explains how to customize the Web forms used by submitters = and editors to enter and modify the metadata for a new item. These metadata= web forms are controlled by the Describe step within the Submissi= on Process. However, they are also configurable via their own XML configura= tion file (input-forms.xml).
You can customize the "default" metadata forms used by all collections, = and also create alternate sets of metadata forms and assign them to specifi= c collections. In creating custom metadata forms, you can choose:
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 control= led by a single XML file, input-forms.xml, in the config = subdirectory under the DSpace home. DSpace comes with a sample configuratio= n that implements the traditional metadata-entry forms, which also serves a= s a well-documented example. The rest of this section explains how to creat= e your own sets of custom forms.
The description of a set of pages through which submitters enter their m= etadata 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 <= em>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 form= s, 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 b= ecause their names are mutable and not necessarily unique, while handles ar= e unique and persistent.
A special map entry, for the collection handle "default", defines the
The XML configuration file has a single top-level element, input-for= ms, which contains three elements in a specific order. The outline is = as follows:
<inp= ut-forms> <-- Map of Collections to Form Sets --> <form-map> <name-map collection-handle=3D"default" form-name=3D"traditional" =09/> ... </form-map> <-- Form Set Definitions --> <form-definitions> <form name=3D"traditional"> ... </form-definitions> <-- Name/Value Pairs used within Multiple Choice Widgets =09--> <form-value-pairs> <value-pairs value-pairs-name=3D"common_iso_languages" =09dc-term=3D"language_iso"> ... </form-value-pairs> </input-forms>
Each name-map element within form-map associates a col= lection with the name of a form set. Its collection-handle attribu= te is the Handle of the collection, and its form-name attribute is= the form set name, which must match the name attribute of a f= orm element.
For example, the following fragment shows how the collection with handle= "12345.6789/42" is attached to the "TechRpt" form set:
<f= orm-map> <name-map collection-handle=3D" 12345.6789/42" form-name=3D" TechRpt= "/> ... </form-map> <form-definitions> <form name=3D"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.
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 & Col= lections" page under "Browse" in the left-hand menu on you= r 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= em> attribute of your name-map element.
You can add a new form set by creating a new form element withi= n the form-definitions element. It has one attribute, name, which as seen above must match the value of the name-map for th= e collections it is to be used for.
The content of the form is a sequence of page elements= . Each of these corresponds to a Web page of forms for entering metadata el= ements, presented in sequence between the initial "Describe" page and the f= inal "Verify" page (which presents a summary of all the metadata collected)= .
A form must contain at least one and at most six pages. They ar= e presented in the order they appear in the XML. Each page element= must include a number attribute, that should be its sequence numb= er, e.g.
<pag= e number=3D"1">
The page element, in turn, contains a sequence of field elements. Each field defines an interactive dialog where the submitter en= ters one of the Dublin Core metadata items.
Each field contains the following elements, in the order indica= ted. The required sub-elements are so marked:
For the use of controlled vocabularies see the Configuring Controlled Vo= cabularies section.
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 exam= ple, if the user indicates there are no alternate titles on the first "Desc= ribe" page (the one with a few checkboxes), the input for the title.alt= ernative DC element is automatically elided, even on custom submis= sion pages.
When a user initiates a submission, DSpace first displays what we'll cal= l the "initial-questions page". By default, it contains three questions wit= h check-boxes:
The answers to the first two questions control whether inputs for certai= n of the DC metadata fields will displayed, even if they are defined as fie= lds in a custom page. Conversely, if the metadata fields controlled by a ch= eckbox are not mentioned in the custom form, the checkbox is elided from th= e 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 dis= tributed before". The checkbox for multiple titles trigger the display of t= he field with dc-element equal to 'title' and dc-qualifier equal to 'altern= ative'. If the controlling collection's form set does not contain this fiel= d, then the multiple titles question will not appear on the initial questio= ns page.
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:
Here is a menu of types of common identifiers:
<= value-pairs value-pairs-name=3D"common_identifiers" dc-term=3D"identifier"&= gt; <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 inpu= t XML, so it cannot generate the HTML SELECTED attribute to mark o= ne of the options as a pre-selected default.)
<sel= ect name=3D"identifier_qualifier_0"> <option VALUE=3D"govdoc">Gov't Doc #</option> <option VALUE=3D"uri">URI</option> <option VALUE=3D"isbn">ISBN</option> </select>
The DSpace web application only reads your custom form definitions when = it starts up, so it is important to remember:
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 stac= k 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 servle= t container before testing your fix to a bug.
The Upload step in the DSpace submission process has two config= uration options which can be set with your [dspace]/config/dspace.cfg= em> configuration file. They are as follows:
First, a brief warning: Creating a new Submission Step requires some= Java knowledge, and is therefore recommended to be undertaken by a Java pr= ogrammer whenever possible
That being said, at a higher level, creating a new Submission Step requi= res the following (in this relative order):
org.dspace.s=
ubmit.AbstractProcessingStep
class and implement all methods defined=
by that abstract class.org.dsp=
ace.app.webui.submit.JSPStep
and implement all methods defined there=
. It's recommended to use one of the classes in org.dspace.app.webui.=
submit.step.*
as a reference.org.dspace.app.webui.submit.JSPStepManager
classreview-=
[step].jsp
) in the JSP submit/
directory.org.dspace.app.xmlui.submission.AbstractSubmi=
ssionStep
org.dspace.app.xmlui.=
submission.submit.*
as referencesit=
em-submission.xml
configuration file.=20
item-submission.xml
.Non-interactive steps are ones that have no user interface and only perf= orm backend processing. You may find a need to create non-interactive steps= which perform further processing of previously entered information.
To create a non-interactive step, do the following:
<ste= p> <processing-class>org.dspace.submit.step.MyNonInteractiveStep</= processing-class>=20 <workflow-editable>false</workflow-editable> </step>
Note: Non-interactive steps will not appear in the Progress Bar! Therefo= re, your submitters will not even know they are there. However, because the= y are not visible to your users, you should make sure that your non-interac= tive step does not take a large amount of time to finish its processing and= return control to the next step (otherwise there will be a visible time de= lay in the user interface).