Editing Workflow Format (section)

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

<table border="1" cellspacing='0'>
<tr><th>Attribute</th><th>Values</th><th>Description</th></tr> 
<tr><td>ref</td><td>A string</td><td>(required) Refers to the name of the metafield this field represents</td></tr>
<tr><td>required</td><td>yes/no</td><td>(optional) Whether a value is required in this field before the workflow may complete</td></tr>
<tr><td>&lt;help&gt; (child-node)</td><td>An XHTML block</td><td>(optional) A block of XHTML to be rendered as help for the field</td></tr>
<tr><td>&lt;title&gt; (child-node)</td><td>An XHTML block</td><td>(optional) A block of XHTML to be rendered as the title for the field</td></tr>
<tr><td>input_lookup_url</td><td>A URL</td><td>(optional) The location of an auto-lookup URL for the field</td></tr>
<tr><td>input_lookup_params</td><td>A string</td><td>(optional) An &-separated list of parameters (e.g. sort=descending&number=3</td></tr>
<tr><td>top</td><td>A string</td><td>(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.</td></tr>
<tr><td>options</td><td>A string (comma separated values)</td><td>(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)</td></tr>
<tr><td>input_boxes</td><td>An integer</td><td>(optional) Default number of rows to show by default in a multiple field. Overrides the field property.</td></tr>
<tr><td>input_add_boxes</td><td>An integer</td><td>(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.</td></tr>
<tr><td>input_ordered</td><td>Boolean</td><td>(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.</td></tr>

</table>

==== 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_Format|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>