Editing Template:EPrints Metadata Fields Content (section)

== Properties ==

Note that true/false properties use 1 and 0 to indicate their setting.

Some properties can be temporarily set or overridden by the [[Workflow Format]] and [[Citation Format]] files.

=== Core Properties ===

{| cellpadding="3" cellspacing="0" border="1"
! Name !! Default Value !! Required !! Description !! Notes
|-
| '''name''' || n/a || YES || This is the internal name of the field. It should only contain alphanumeric characters and underscores. It will be used to identify this field in scripts, other configuration files, in the database, and in the XML export/import system, etc. ||  This property is ''not'' required when defining sub-fields of [[Compound field]]s where <tt>sub_name</tt> should be used. This property affects the database structure.  It must be unique within the [[Data Object]] (so the [[EPrint Object]] cannot have two fields called <tt>email</tt> but the EPrint Object and [[User Object]] can each have a field with the same name.
|-
| '''type''' || n/a || YES || This sets the type of the metafield, which in turn affects what other properties it may have. || This property affects the database structure.  The value must be one of the metafield types listed above.
|-
| '''multiple''' || <tt>0</tt> || NO || This indicates if this field is a single value or a list of values. E.g. <tt>title</tt> is only a single [[Longtext field]] but <tt>creators</tt> is a multiple [[Compound field]]. || This property affects the database structure. In the database a non-multiple field is stored in one (or more) columns in the main object table, but a multiple field gets its own table.
|-
| '''readonly''' || <tt>0</tt> || NO || Whether to not make this field editable in the workflow. || This is useful if you want to display the pre-generated value(s) for this field for reference whilst other fields are being edited.
|-
| '''sql_index''' || <tt>1</tt> || NO || When the database is created this field indicates that an SQL index should be created to speed searching. || This property affects the database structure. Different field types override the default value with the sensible option for that type of field. It is not worth putting a SQL index on a field that is only ever searched for words in it (like title or abstract) but it is worth indexing fields who's values are explicitly searched for, or where ranges are searched (e.g. [[Date field]]s, [[Set field]]s etc.). It is unlikely you will need to set this by hand. You could change it after the database has been created but this will not update the database nor have any other effect.
|- 
| '''sub_name''' || <tt>undef</tt> || YES || This is a special property which is required ''instead'' of the <tt>name</tt> property for the sub-fields inside [[Compound field]]s.  || This property affects the database structure. The actual name of these fields is then forced to be parent field <tt>name + '_' + sub_name</tt>. E.g.  Compound field <tt>creators</tt> is a sub-field with <tt>sub_name => 'name'</tt>. In this case the actual name of the name field in the system, database etc. is <tt>creators_name/tt>.
|-
| '''virtual''' || <tt>0</tt> || NO || Whether this field calculates a value or stores in in the database. || [[Compound field]]s are virtual fields, whereas there sub-fields are not as they store values in the database.  Other types of virtual field will require a <tt>render_value</tt> to be specified, as with no value stored the default render method will have nothing to display.
|-
| '''volatile''' || <tt>0</tt> || NO || Whether the field is liable to change frequently. || Setting <code>volatile => 1</code> will prevent new revisions being create and avoid other post commit events from being triggered, such as re-indexing.
|}

=== Rendering Properties ===

These properties affect how values of the metadata in this field are rendered.

Certain of these properties can be turned on temporarily by the [[Citation Format]] files - render_magicstop for example.

{| cellpadding="3" cellspacing="0" border="1"
! Name !! Default Value !! Required !! Description !! Notes
|-
| '''as_list''' || <tt>undef</tt> || NO || Whether to display a collection sub-fields values as a table row or a separate list in the input form || This is only applicable for [[Compound field]]s that have <code>multiple => 1</code>.  It is useful where the length of the table row would exceed the width of a typical user's window.
|-
| '''browse_link''' || <tt>undef</tt> || NO || This is the name of a view which values of this field should be linked to. || E.g. if there was a <tt>Browse by Publishers</tt> view configured named <tt>pubs</tt>, then adding <code>browse_link => 'pubs'</tt> to the <tt>publisher</tt> field would cause it to be linked into the browse view page for the named publisher whenever it is rendered.
|-
| '''render_custom''' || <tt>undef</tt> || NO || Whether to use a pre-defined way of rendering the value for this field. || E.g. for [[Name field]]s by default the name will link to the creators browse view for that name.  This property can be re-used within bespoke render functions to specify whether some custom way of rendering this field' svalue (e.g. with a link) should be used.
|-
| '''render_dont_link''' || <tt>0</tt> || NO || Whether rendered field is not encapsulated in a hyperlink. || Currently only affects [[Url field]]s and [[Email field]]s.
|-
| '''render_dynamic''' || <tt>0</tt> || NO || Whether the rendering of this field can use JavaScript to make it dynamic. || [[limit_names_shown.pl]] uses this property to determine if the list of hidden creators/editors can be expanded to show all creators/editors.
|-
| '''render_limit''' || <tt>undef</tt> || NO || How many values for this field should be displayed. || [[limit_names_shown.pl]] uses this property to determine how many creators/editors to display.  If <code>undef</code> just render all values.
|-
| '''render_magicstop''' || <tt>0</tt> || NO || Whether to render a full stop at the end of this field, unless the last character is a dot, question mark or exclamation mark. || This helps avoid the ugly <tt>World without Cheese?.</tt> effect you get when titles end in <tt>?</tt> or <tt>!</tt>.
|-
| '''render_noreturn''' || <tt>0</tt> || NO || Whether CR (Carriage Return) and LF (Line Feed) characters are turned into normal spaces. ||
|-
| '''render_quiet''' || <tt>0</tt> || NO || Whether to prevent a big ugly <tt>UNSPECIFIED</tt> being rendered if field is unset. || E.g. setting <code>render_quiet => 1</code> on a field means it just gets rendered as nothing if it is unset.
|-
| '''render_single_value''' || <tt>undef</tt> || NO || The value of this property is the name of a function to call to render individual values from this field. || For a multiple field this is called once per value in the list of values. The function should take the following parameters: (<code>$session, $field, $value, $object</code>). It should return a [[XHTML DOM]] object of the rendered value.
|- 
| '''render_value''' || <tt>undef</tt> || NO || The value of this property is the name of a function to call to render the the field as a whole.  || As with <tt>render_single_value</tt>, but this gets passed the entire list of values (an array reference) if it is a multiple field. Parameters passed are: ( code>$session, $self, $value, $all_langs, $no_link, $object</code> ). <code>$all_langs</code> indicates that all language variants should be shown and is only really useful for [[Multilang field]]s. <code>$no_link</code> being true is a request to place no hyperlinks in the resulting HTML. The function should return an [[XHTML DOM]] object of the rendered value.
|}

=== Input and Validation Properties ===

{| cellpadding="3" cellspacing="0" border="1"
! Name !! Default Value !! Required !! Description !! Notes
|-
| '''default_value''' || <tt>undef</tt> || NO || The default value to set for this field. || This is mainly used for [[EPrints Glossary#System field|system fields]].  For custom fields it is better to use [[eprint_fields_default.pl]] or similar.
|-
| '''expanded_subjects''' || <tt>[]</tt> || NO || Subjects to show un-collapsed in the subject tree field in the workflow. || This is only applicable for [[Subject field]]s.  All the fields listed will have their paths in the subject tree expanded so they can be seen, making them easier to find.
|-
| '''false_first''' || <tt>0</tt> || NO || Display the false option before the true option in the input form. || This is only applicable to [[Boolean field]]s.  By default true option is always displayed before the false option.
|-
| '''fromform''' || <tt>undef</tt> || NO || The inverse of <tt>toform</tt>. This takes the value from the form and converts it into the value that will be stored in the database. || This function is passed the parameters: <tt>$value, $session, $object, $basename</tt> when <tt>$value</tt> is the value entered on the HTML form, and the return value is the value to be stored in the database. This function is not called when editing the eprint is cancelled.
|-
| '''get_item''' || <tt>undef</tt> || NO || A bespoke function for how to lookup the [[EPrints Glossary#Data object|Data object]] based on the stored value. || Only applicable to [[Itemref field]]s.
|- 
| '''help_xhtml''' || <tt>undef</tt> || NO || An [[XHTML DOM]] object to use for the help text for this field. || This can only be set via the [[Workflow Format]] configuration not via the metadata field directly. This is so that the workflow can conditionally change the help on a field.  If you need to change the help text based on the eprint type, then you can just create a bespoke phrase with the format <code>"eprint_fieldhelp_" + fieldname + "." + eprint_type</code> (e.g. <code>eprint_fieldhelp_id_number.article</code>).
|-
| '''input_add_boxes''' || <tt>2</tt> || NO || The number of rows to add when clicking the <tt>More input rows</tt> button for a field that sets <code>multiple => 1</code>. || The default value for this property is taken from <tt>cfg.d/[[field_property_defaults.pl]]</tt>.
|- 
| '''input_boxes''' || <tt>3</tt> || NO || The number of input rows to initially show for a field that sets <code>multiple => 1</code>. || The default value for this property is taken from <tt>cfg.d/[[field_property_defaults.pl]]</tt>.
|-
| '''input_cols''' || <tt>60</tt> || NO || The number of columns in an HTML form field. || The default value for this property is taken from <tt>cfg.d/[[field_property_defaults.pl]]</tt>.  This in combination with the <tt>maxlength</tt> property determines the value for <tt>size</tt> attribute for <code><input></code> HTML fields or the <tt>cols</tt> attribute for <code><textarea></code> HTML fields (used by [[Longtext field]]s).
|-
| '''input_lookup_params''' || <tt>undef</tt> || NO || Additional parameters to pass to the <tt>input_lookup_url</tt>. || E.g. an indication of which autocomplete file to use.
|-
| '''input_lookup_url''' || <tt>undef</tt> || NO || The URL to use for autocompletion. || This is generally set using the workflow configuration rather than directly in the field configuration. The URL must be on the same server hostname as the repository.
|-
| '''input_ordered''' || <tt>1</tt> || NO || Whether the ordering of values needs to be captured. || In some <code>multiple => 1</code> fields, such as creators, the order of the values is important and by default numbers are shown to the left of input rows and to the right are ''move up'' and ''move down'' arrows. However, with some <code>multiple => 1</code> fields the order is not important, in which case you can set this to <tt>0</tt> to stop the arrows and numbers being shown.
|-
| '''input_rows''' || <tt>10</tt> || NO || The number of rows in an HTML form field. || The default value for this property is taken from <tt>cfg.d/[[field_property_defaults.pl]]</tt>  This property determines the value for <tt>size</tt> attribute for <code><select></code> HTML fields (used by [[Set field]]s)  or the <tt>rows</tt> attribute for <code><textarea></code>  HTML fields (used by [[Longtext field]]s).
|-
| '''maxlength''' || <tt>255</tt> || NO || The maximum allowed length in characters for a value. || This can be a very simple validation check. Also, it may confuse users to be allowed to type in 255 characters in a field intended for something like a postcode/zipcode.
|-
| '''maxwords''' || <tt>undef</tt> || NO || The maximum number of words that should be entered for this field. || This field is only applicable to [[Longtext_counter field]]s.  It does not restrict the number of words, it just displays this limit next to a dynamic counter of the number of words already entered.
|-
| '''render_input''' || <tt>undef</tt> || NO || The name of a function which will render the input for this field. || This can be difficult to use as it must return the same CGI parameters as the default input form would have. It is easiest on simple fields. The subroutine is passed the following parameters: <code>$field, $session, $current_value, $dataset, $staff, $hidden_fields, $object, $basename</code> ). It should return the [[XHTML DOM]] object of the chunk of HTML form.
|-
| '''required''' || <tt>0</tt> || NO || Whether the field must have a value set. || If this is set to <tt>1</tt> then the field is always marked as required, no matter what the [[Workflow Format]] configuration says.
|-
| '''separator''' || <tt>undef</tt> || NO || What character to use to separate elements of the value for the field for purposes of search || Only used by default for [[Keywords field]]s.
|-
| '''show_help''' || <tt>undef</tt> || NO || How to display the help text for this field in the input form. ||  Can be one of three values: <tt>always</tt>, <tt>never</tt> or <tt>toggle</tt>.  Toggle (allow to expand or collapse) is used if not explicitly defined.  This can only be overridden in [[Workflow Format]] configuration.
|-
| '''title_xhtml''' || <tt>undef</tt> || NO || An [[XHTML DOM]] object to use for the title for this field. || This can only be set via the [[Workflow Format]] configuration not via the metadata field directly. This is so that the workflow can conditionally change the title of a field.  If you need to change the title based on the eprint type, then you can just create a bespoke phrase with the format <code>"eprint_fieldname_" + fieldname + "." + eprint_type</code> (e.g. <code>eprint_fieldname_id_number.article</code>).
|-
| '''toform''' || <tt>undef</tt> || NO || This function is allowed to modify the current value which appears in the form. || E.g. if your database stores <tt>userid</tt>s in a field, but you want to allow people to edit them as <tt>username</tt>s, then this function can be used to take the current value (a <tt>userid</tt>) and return the associated <tt>username</tt>. This value is what appears in the field in the search form. It is passed: <code>$value, $session, $object, $basename</code> and returns the user-facing version of <code>$value</code>.
|}

=== Ordering, Indexing and Searching ===

{| cellpadding="3" cellspacing="0" border="1"
! Name !! Default Value !! Required !! Description !! Notes
|-
| '''make_single_value_orderkey''' || <tt>undef</tt> || NO || The <tt>orderkey</tt> function (potentially language specific) used to order by this field. || This property allows you to define a function or refer to a predefined function to override the default EPrints' orderkey generation. This property is passed each value from multiple fields, in turn. It is passed: <code>$field, $value, $dataset</code> and returns an <tt>ordervalue</tt> string.
|-
| '''make_value_orderkey''' || <tt>undef</tt> || NO || Like <tt>make_single_value_orderkey</tt> but this is passed the array reference for a multiple field rather than just single values. || It should return the <tt>orderkey</tt> string for the entire value. It is passed: <code>$field, $value, $session, $langid, $dataset</code>.
|-
| '''match''' || <tt>EQ</tt> || NO || How to match the value(s) of this field against search terms. || This property can be <tt>EQ</tt>, <tt>EX</tt>, <tt>IN</tt> or <tt>SET</tt>.  Default <tt>EQ</tt> means treat the search term as a single string. Match only whole search term matches the field value (or one of its values if <code>multiple => 1</code>).  This can be modified for the [[API:EPrints/Search/Field|field in the search form configuration]].
|-
| '''merge''' || <tt>ALL</tt> || NO || Whether this field's values(s) has to match any or all of the search terms || This property can be <tt>ALL</tt> or <tt>ANY</tt>, Default <tt>ALL</tt> means all search terms have to match the values(s) in this field. This can be modified for the [[API:EPrints/Search/Field|field in the search form configuration]].  For certain values of <tt>match</tt> this can also be changed by the user in the search form itself.
|-
| '''text_index''' || <tt>0</tt> || NO || Whether the indexer considers this field for full-text indexing. || Some types of metadata field have a default of <tt>1</tt>, e.g. [[Text field]]s and [[Longtext field]]s.
|-
| '''search_cols''' || <tt>40</tt> || NO || How many characters (columns) wide the input field for searching this field. ||  The default value for this property is taken from <tt>cfg.d/[[field_property_defaults.pl]]</tt>.  If one search field searches more than one field, then the properties from the first field listed are used.
|}

=== Other Properties ===
{| cellpadding="3" cellspacing="0" border="1"
! Name !! Default Value !! Required !! Description !! Notes
|-
| '''allow_null''' || <tt>1</tt> || NO || Whether the value(s) stored in the database when no input is entered should be <tt>NULL</tt> or an appropriate default value based on its database field type. || This should generally never be set to <tt>0</tt> and certainly should not be changed to <tt>0</tt> after the field has been added to the database.  You are much better off configuring a default value using <tt>[[eprint_fields_default.pl]]</tt> or similar.
|-
This may be applicable to [[Text field|text]]  
| '''can_clone''' || <tt>1</tt> || NO || Whether the value(s) for this field should be cloned if a new record is created.  || This property is mostly used by system fields such as <tt>dir</tt> or <tt>datestamp</tt>.  It is applicable when an eprint is cloned using the <tt>Use as template</tt> or <tt>New version</tt> action buttons.
|-
| '''export_as_xml''' || <tt>1</tt> || NO || Whether the field value(s) should be exported in an XML export. || This is handy to suppress either confidential or confusing fields, like the <tt>fileinfo</file> [[EPrints Glossary#System_field|system field]].
|-
| '''import''' || <tt>1</tt> || NO || Whether new data objects create from an import can set values for the field.  || E.g. <tt>eprintid</tt>, <tt>dir<tt> are determined when the eprint record is created.  Imported metadata would not choose an appropriate value for such fields.
|-
| '''replace_core''' ||| <tt>0</tt> || NO || Whether the field configuration should replace the exisiting [[EPrints Glossary#Core_field|core (system) field]] with the same <tt>name</tt> || This is useful for particularly bespoke requirements.  It should be used with great care, as system fields are usually hard-coded because they should not be changed.
|-
| '''show_in_fieldlist''' || <tt>1</tt> || NO || Whether to allow this field to appear in fields lists.  || If set to <tt>0</tt> will prevent this field appearing in [[Fields field]] lists.  This is primarily to allow you to remove it from the list of fields in the user configuration which are used to control which fields appear as columns in the Items and Review screens.
|-
| '''show_in_html''' || <tt>1</tt> || NO || Whether this field is not shown in the [[EPrints Glossary#Details_tab|Details tab]] of the [[EPrints Glossary#EPrint_control_page|eprint control page]]. || This is mostly used to hide confusing internal [[EPrints Glossary#System_field|system field]]s like <tt>dir</tt>.
|}

=== Internal Properties ===

These are set by the system. Editing them by hand will do '''''strange things'''''.

{| cellpadding="3" cellspacing="0" border="1"
! Name !! Default Value !! Required !! Description !! Notes
|-
| '''confid''' || n/a || YES || The ID of the dataset to which this field belongs. || The value for this property is automatically set when the field is loaded.  It is used to work out what phrase ids etc. it uses.
|-
| '''join_path''' || <tt>undef</tt> || NO || How to join a field that references a different [[Data Object]]. || This should never be defined within a field's configuration.  This is built by search to support building a database query to perform a user's search.
|-
| '''parent''' || <tt>undef</tt> || NO || A reference to the actual parent [[Compound field]] object. || This is set automatically as a reference to the parent field object.
|-
| '''parent_name''' || <tt>undef</tt> || NO || The name of the parent [[Compound field]] to which a sub-field belongs. || This is set automatically to be the name of the parent field.
|-
| '''provenance''' || <tt>undef</tt> || NO || Where this field configuration was generated. || Typically any field configuration either defined within a [[Data Object|Data object]] or in a configuration file (in a <tt>cfg.d</tt> directory will leave this as <tt>undef</tt> by not specifying this property.  However, fields created using [[Admin/Config._Tools/Manage_Metadata_Fields|Manage Metadata Fields]] will set this to <tt>user</tt> so it is clear from where this field was created.
|}

=== Deprecated Properties ===

Do not use these!

{| cellpadding="3" cellspacing="0" border="1"
! Name !! Default Value !! Required !! Description !! Notes
|-
| '''input_advice_below''' || <tt>undef</tt> || NO || Help text to put directly below the form input field || Deprecated. Defined but no longer functional.
|-
| '''input_advice_right''' || <tt>undef</tt> || NO || Help text to put directly to the right of the form input field || Deprecated.  Defined but no longer functional.
|-
| '''input_assist''' || <tt>undef</tt> || NO || Provides input assistance. || Deprecated.  Defined but no longer functional.
|-
| '''requiredlangs''' || <tt>[]</tt> || NO || The natural languages that should be used in the value(s) for this field ||  Deprecated.  Defined but no longer functional.
|-
| '''sql_langid''' || <tt>undef</tt> || NO || The language ID for SQL. || Deprecated.  Defined but no longer functional.
|-
| '''sql_sorted''' || <tt>0</tt> || NO || Whether SQL should be sorted. || Deprecated.  Defined but no longer functional.
|}