Workflow Format
EPrints 3 Reference: Directory Structure - Metadata Fields - Repository Configuration - XML Config Files - XML Export Format - EPrints data structure - Core API - Data Objects
XML Configuration: EPScript - Control Format (EPC) - Citation - Workflow - Phrase - Template - XPAGE (static pages)
The EPrints 3 workflow configuration files are stored in the repository's workflows directory, within folders identifying the Data Objects to which they apply (e.g. eprint or user). Multiple workflows may be defined in each folder, although typically only the default.xml file will be necessary.
Contents
Structure
At the centre of a workflow is a 'flow' description. This denotes the path through the workflow process from stage to stage. This may contain EPrints Control tags, allowing for the flow to vary depending on parameters of the data object (or other objects). For example, the flow may be different for users with certain roles. The flow is structured like so:
<flow> <stage ref="type"/> <stage ref="files"/> <stage ref="core"/> <stage ref="subjects"/> </flow>
The 'ref' attribute of the stage element refers to the individual stages. The stage elements describe the components within each screen of the process and, like flow, may contain EPrints Control tags. The 'name' attribute of the stage element is identical to that of the stage element in the 'flow' section.
<stage name="core"> <component><field ref="title" required="yes" /></component> <component><field ref="abstract"/></component> </stage>
Buttons
By default the "save" and "cancel" buttons appear at the top and bottom of each stage, but you can change this using the "action_buttons" attribute. Values are "top", "bottom" or "both".
<stage name="core" action_buttons="bottom" >
Components
An EPrints component is responsible for the rendering of a graphical element in a workflow. This may be a text-box for title entry, a collection of fields in an appropriate grouping, or just a piece of XHTML. Six components are provided by default and, as they are plugins, it is straightforward to drop in new components when necessary. The type attribute of the component element corresponds to the plugin to be used.
Field-Related Components
Field Element
The majority of field-related components in EPrints 3 make use of the field element in their configuration. This provides a reference to a metafield and any attributes which may be relevant to rendering or operation. Several attributes are available to the element:
| Attribute | Values | Description |
|---|---|---|
| ref | A string | (required) Refers to the name of the metafield this field represents |
| required | yes/no | (optional) Whether a value is required in this field before the workflow may complete |
| <help> (child-node) | An XHTML block | (optional) A block of XHTML to be rendered as help for the field |
| <title> (child-node) | An XHTML block | (optional) A block of XHTML to be rendered as the title for the field |
| input_lookup_url | A URL | (optional) The location of an auto-lookup URL for the field |
| input_lookup_params | A string | (optional) An &-separated list of parameters (e.g. sort=descending&number=3 |
| top | A string | (optional) Only useful on "subject" fields, this overrides the top node of the available subject tree. Useful to force certain records to only select from a sub tree. |
| options | A string (comma separated values) | (optional) On a set (or named set) field this overrides the default options. Useful if you want a certain option to appear or disappear based on other metadata) |
| input_boxes | An integer | (optional) Default number of rows to show by default in a multiple field. Overrides the field property. |
| input_add_boxes | An integer | (optional) Number of rows to add to a multiple field if the "more rows" button is pressed. Zero disables the option to add more rows. Overrides the field setting. |
| input_ordered | Boolean | (optional) 1 or 0. Overrides the field setting. If zero then a multiple field won't have the 1,2,3 on the left and reordering arrows on the right of the input, as ordering is considered irrelevant. |
Examples
Conditional Overriding of Field Name and Help
Example showing how to override the default 'keywords' field title with the string "Descriptive Labels" and the default help text for the keywords field with an entry from a phrase file for a specific item type.
N.B. the phrase ref can be any text but must match the entry in the phrase file.
<field ref="keywords">
<epc:if test="type='article'">
<title>Descriptive Labels</title>
<help><epc:phrase ref="eprint_fieldname_keywords.labels" /></help>
</epc:if>
</field>
Field Component
The default component, this renders the field title, an input box suitable for the field, a star if the field is required, and any help information. A single field element is required:
<component><field ref="title" required="yes" /></component>
Multiple Field Component
The multiple field component is able to render several fields in a group, such as all fields related to a publication or an event. A title element and a help element may be provided that describe the group itself. One or many field elements are also required.
<component type="Field::Multi"> <title>Event Details</title> <help>Enter information about your event here.</help> <field ref="event_title"/> <field ref="event_type" required="yes" /> <field ref="event_location"/> <field ref="event_dates"/> </component>
Subject Component
The subject component allows for the selection of one or more subjects from a subject tree. In this instance, the field element specifies the subject metafield.
<component type="Field::Subject"> <field ref="subjects" required="yes" /> </component>
Other Components
Upload Component
The upload component provides an interface for files to be uploaded to EPrints documents, and for new documents to be created/edited. It does not require any elements other than the component tag, but field elements to be rendered for each document may be added as in the example.
<component type="Upload"> <field ref="format" /> <field ref="formatdesc" /> <field ref="security" /> <field ref="license" /> <field ref="date_embargo" /> </component>
XHTML Component
This component inserts any contained nodes into the rendered document. As EPrints Control elements may be used, it is possible to insert phrases into the screen.
<component type="XHTML"> <epc:phrase ref="Plugin/InputForm/Component/Upload:help" /> </component>
NOTE: EPrints version up to 3.3.12 produce a <component> element in the html when using this. Please see https://github.com/eprints/eprints/issues/148
Other Component Options
A component normally is enclosed in a "default" surround, with a pop-up help icon, and a title bar with the contents in a tinted box. The behaviour of the page around the component can be tweaked in a few ways.
collapse
The collapse option to the component defaults to "no" but may be set to "yes. If yes, the entire component is shown, by default, as "rolled up" so it must be clicked to unroll it. This is a good way to indicate that the fields, are not something for most users to worry about. It allows you to make the form less intimidating, while still having many options available for advanced users.
<component collapse="yes"> ... </component>
show_help
The default value is "toggle" but it can be set to "always" or "never".
"always" will remove the option to show help, and just always show it. "never" removes the toggle but does not show the help.
<component show_help="always"> ... </component>
surround
This controls the InputForm::Surround plugin used to render the component. The default option paints the standard box. Other options are "None" and "Light".
None renders just the contents, and can be useful to combine with type="XHTML" to embed HTML directly into the page.
You may add your own Surround plugins if you wish.
<component surround="None" type="XHTML"> ... </component>
