Category:EPrints Metadata Fields - Revision history

Drn@ecs.soton.ac.uk: Moved content to separated template so it can be transcluded.

2017-09-08T12:59:55Z

Moved content to separated template so it can be transcluded.

Show changes

Alan.stiles@open.ac.uk: /* Internal-use and Deprecated Field Types */ removed deprecation from ID field

2016-12-19T14:42:48Z

‎Internal-use and Deprecated Field Types: removed deprecation from ID field

Alan.stiles@open.ac.uk: /* Input and Validation Properties */

2015-03-25T16:49:39Z

‎Input and Validation Properties

Alan.stiles@open.ac.uk: /* Input and Validation Properties */ added small explanation to fromform

2015-03-25T16:46:37Z

‎Input and Validation Properties: added small explanation to fromform

Adb1a11@ecs.soton.ac.uk: Spelling and punctuation.

2012-06-27T09:37:12Z

Spelling and punctuation.

Pm705 at 13:16, 25 March 2010

2010-03-25T13:16:27Z

Pm705 at 19:07, 13 March 2010

2010-03-13T19:07:45Z

Pm705: Created page with '{{fieldtypes}} Category:EPrints Metadata Fields == Metadata Field Types == There are many different types of metadata field. The type controls how a field is rendered, index…'

2010-03-13T19:06:06Z

Created page with '{{fieldtypes}} Category:EPrints Metadata Fields == Metadata Field Types == There are many different types of metadata field. The type controls how a field is rendered, index…'

New page

{{fieldtypes}}
[[Category:EPrints Metadata Fields]]
== Metadata Field Types ==

There are many different types of metadata field. The type controls how a field is rendered, indexed, searched and so forth. A field always has a type and a name property, and usually has several more. Most properties are documented on this page, but some properties are only available to certain types of field, and they are listed on the page for that field.

Some of these subclasses provide very rich features, others very simple. For example the [[url field]] works just like the text field except that it's only valid if it looks like a url and when rendered it is a hyper-link.

A metadata field describes one field of data in one type of [[Data Object]]. For example the "title" field of an [[EPrint Object]] or the "email" field in a [[User Object]].

Every [[Data Object]] has system fields (which are set by the system, and not alterable), but the [[User Object]] and [[EPrint Object]] have additional fields which are configured on a per-repository basis.

These can be customised in the [[user_fields.pl]] and [[eprint_fields.pl]] files. Note that changing these files does not automatically modify the underlying database so should (generally) only be done before the database is created. Some metadata properties do not affect the database, and are marked as such.

If you add or remove fields, or modify a property which affects the database then you'll need to alter the database to match. In 3.0 this must be done by hand, but we have plans to build a tool to do this for you.

Default values marked *config indicate that the default value for the repository may be modified in the configuration file [[field_property_defaults.pl]]

== Inherritance ==

This is the list of ''useful'' field types. Under it is listed the other field types which are just included for completeness and are not intended to be used as part of the configuration.

Some field types inherrit the properties of another, and then modify them in some way. For example the [[namedset field]] works like a [[set field]] except that it gets its options from a namedsets file not from the options=>[] in the field properties.

* '''Basic metadata field''' - this is abstract, fields must be one of the types listed below...
** '''[[Boolean field|Boolean]]''' - TRUE or FALSE (or can be unset, of course)
** '''[[Compound field|Compound]]''' - virtual field, joins together several "multiple" fields. eg. author_name and author_email
*** '''[[Multilang field|Multilang]]''' - allows language variants of a field. eg. titles in French, German and/or English.
** '''[[Date field|Date]]''' - stores a date.
*** '''[[Time field|Time]]''' - stores a date and time.
** '''[[Float field|Float]]''' - stores a floating point value
** '''[[Int field|Int]]''' - a positive integer value
*** '''[[Itemref field|Itemref]]''' - a reference to another [[Data Object]] (eg. a user or other eprint)
*** '''[[Pagerange field|Pagerange]]''' - a pagerange, eg 122-130
** '''[[Search field|Search]]''' - a serialised search
** '''[[Set field|Set]]''' - a limited set of options
*** '''[[Namedset field|Namedset]]''' - like a normal set, but takes its options from a [[namedset]] configuration file.
*** '''[[Subject field|Subject]]''' - possible values are taken from the [[Subject]] heirarchy.
** '''[[Text field|Text]]''' - the basic text field. Maximum 255 bytes. nb. uft-8 means some chars take more than one byte.
*** '''[[Email field|Email]]''' - an email address
*** '''[[Longtext field|Longtext]]''' - like text but allows much longer text (65,000 bytes)
*** '''[[Name field|Name]]''' - Stores a persons name broken up into logical parts.
*** '''[[Url field|Url]]''' - stores a URL

=== Internal-use and Deprecated Field Types ===

* '''Basic metadata field'''
** '''[[File field|File]]''' - virtual field represtenting the files in a document
** '''[[Id field|Id]]''' - deprecated (do not use)
** '''Int'''
*** '''[[Year field|Year]]''' - deprecated (do not use)
** '''[[Search field|Search]]''' - a serialised search
** '''Set'''
*** '''[[Arclanguage field|Arclanguage]]''' - as for set, but the options are the valid languages of this repository
*** '''[[Fields field|Fields]]''' - as for set, but the options are the fields in a dataset.
*** '''[[Langid field|Langid]]''' - used internally by [[multilang field]]s to store the language id.
** '''[[Subobject field|Subobject]]''' - a virtual field, similar to itemref, but representing an object or objects which are sub-parts of the current object (as oppose to just related in some way)
** '''Text'''
*** '''[[Fulltext field|Fulltext]]''' - virtual field used to represent to the full text of an eprint
*** '''[[Secret field|Secret]]''' - used to store passwords.

== 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 || description
|-
| '''name''' || n/a || '''This property is always required (except on sub-fields of compound fields). This property affects the database structure.''' This is the internal name of the field. It should only contain a-z 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. It must be unique within the object (so the [[EPrint Object]] can't have two fields called "email" but the eprint object and [[User Object]] could have a field each of the same name.
|-
| '''type''' || n/a || '''This property is always required. This property affects the database structure.''' This sets the type of the metafield, which in turn affects what other properties it may have. The value must be one of the metafield types listed above.
|-
| '''multiple''' || 0 || '''This property affects the database structure.''' This indicates if this field is a single value or a list of values. eg. "title" is only a single [[longtext field]] but "creators" is a multiple [[name field]]. 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.
|-
| '''sql_index''' || 1 || When the database is created this field indicates that an SQL index should be created to speed searching. Different field types override the default value with the sensible option for that type of field. It's not worth putting an sql index on a field that is only ever searched for words in it (like title or abstract) but it is worth indexing fields whoes values are explicitly searched for, or where ranges are searched - date fields, set fields etc. It's unlikely you'll need to set this by hand. You could change it after the database has been created; it won't break anything. In fact, it won't do anything at all.
|-
| '''sub_name''' || undef || '''This property affects the database structure.''' This is a special property which is required INSTEAD of the name field for the sub fields inside compound fields. The actual name of these fields is then forced to be parent field name+"_"+sub_name. For example in compound field "creators" is a sub field with sub_name "name". In this case the actual name of the name field in the system, database etc. is creators_name.
|}

=== 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 || description
|-
| '''browse_link''' || undef || This is the name of a [[view]] which values of this field should be linked to. For example if their was a browse by publishers view configured named "pubs", then adding browse_link=>"pubs" to the publisher field would cause it to be linked into the page for the named publisher whenever it is rendered.
|-
| '''render_quiet''' || 0 || Normally if a field is rendered an it isn't set, it is rendered as a big ugly "UNSPECIFIED". Setting render_quiet on a field means it just gets rendered as nothing if it's empty.
|-
| '''render_magicstop''' || 0 || If true then this renders 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 "World without Cheese?." affect you get when titles end in ? or !.
|-
| '''render_noreturn''' || 0 || If true then all CR and LF's are turned into normal spaces.
|-
| '''render_dont_link''' || 0 || Set this to true to stop this field hyperlinking itself when rendered. Currently only affects [[url field]]s and [[email field]]s.
|-
| '''render_order''' || "fg" || <b>Only for fields of type=>name.</b> The order the name is rendered. For example 'gf' is given name first then family name.
|-
| '''render_single_value''' || undef || The value of this property is the name of a subroutine to call to render 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: ( $session, $field, $value, $object). It should return an [[XHTML DOM]] object of the rendered value.
|-
| '''render_value''' || undef || As with render single value, but this gets passed the entire list of values (an array reference) if it's a multiple field. Parameters passed are: ( $session, $self, $value, $all_langs, $no_link, $object ). $all_langs indicates that all language variants should be shown - only really useful for multilang fields. $no_link being true is a request to place no hyperlinks in the resulting HTML. It should return an [[XHTML DOM]] object of the rendered value.
|}

=== Input and Validation Properties ===

{| cellpadding="3" cellspacing="0" border="1"
| name || default || description
|-
| '''required''' || 0 || If this is set to true then the field is always marked as required, no matter what the workflow says.
|-
| '''input_add_boxes''' || 2 *config || The number of rows to add when clicking the "more rows" button in a multiple or multilang field.
|-
| '''input_boxes''' || 3 *config || The number of input rows to initially show in a multiple field.
|-
| '''input_cols''' || 60 *config || The number of columns in a text input field.
|-
| '''input_rows''' || 10 *config || For longtext input fields, the number of rows of input to show. For set fields this is the number of items to show in a select menu.
|-
| '''input_lookup_url''' || undef || 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_lookup_params''' || undef || Additional parameters to pass to the input_lookup_url. For example an indication of which autocomplete file to use.
|-
| '''input_ordered''' || 1 || This is true by default. In some multiple 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 multiple fields the order is not important in which case you can set this to zero to stop the arrows and numbers being shown.
|-
| '''render_input''' || undef || The name of a subroutine which will render the input for this field. This is a bit tricky to use as it must return the same CGI parameters as the default input form would have. It's easiest on simple fields. The subroutine is passed the following parameters ( $field, $session, $current_value, $dataset, $staff, $hidden_fields, $object, $basename ). It should return the [[XHTML DOM]] object of the chunk of HTML form.
|-
| '''maxlength''' || 255 || This is a limit to the maximum allowed size of a value. It may be useful, for example, as a very simple validation check. Also it may confuse users to be allowed to type in 255 characters in a "postcode/zipcode" field.
|-
| '''toform''' || undef || This function is allowed to modify the current value which appears in the form. For example, if your database stores userids in a field, but you want to allow people to edit them as usernames, then this function can be used to take the current value (a userid) and return the associated username. This value is what appears in the field in the search form. It is passed ( $value, $session, $object, $basename ) and returns the user-facing version of $value.
|-
| '''fromform''' || undef || The inverse of toform. This takes the value from the form and converts it into the value that will be stored in the database. It is passed the parameters ( $value, $session) when $value is the value entered on the web form, and the return value is the value to be stored in the database.
|-
| '''help_xhtml''' || undef || This can only be set via the [[Workflow Format]] configuration not via the metadata field directly. It is used to contain the XHTML to use as the help for this field. This is so that the workflow can conditionally change the help on a field.
|}

=== Ordering, Indexing and Searching ===

{| cellpadding="3" cellspacing="0" border="1"
| name || default || description
|-
| '''text_index''' || 0 || If set to true the the indexer considers this field for full text indexing. Otherwise not. Some types of metadata field have a default of true, for example text and longtext.
|-
| '''search_cols''' || 40 *config || How many columns (characters) wide the input field for searching this type of field. If one search field searches more than one field then the properties from the first listed field are used.
|-
| '''make_single_value_orderkey''' || undef || The orderkey is the (potentially language specific) string used to order by this field. This property allows you to define a method to override the default eprints orderkey generation. This property is passed each value from multiple fields, in turn. It is passed ($field, $value) and returns an ordervalue string.
|-
| '''make_value_orderkey''' || undef || As with make_single_value_orderkey but this is passed the array reference for a multiple field rather than just single values. It should return the orderkey string for the entire value. It is passed ( $field, $value, $session, $language_id ).
|}

=== Other Properties ===

{| cellpadding="3" cellspacing="0" border="1"
| name || default || description
|-
| '''can_clone''' || 1 || If this is set to false then this field is not copied when the object is
cloned. This is mostly used by system fields such as "dir" or "datestamp".
|-
| '''show_in_fieldlist''' || 1 || Set this to false to 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''' || 1 || If set to false then this field is not shown in the Details tab of the eprint control page. This is mostly used to hide confusing internal system fields like "dir".
|-
| '''export_as_xml''' || 1 || Set this to false to prevent the field being exported in the XML export. This is handy to supress either confidential or confusing fields, like the fileinfo system field.
|-
| '''import''' || 1 || If set to false then new eprints can't be created with this value. For example "eprintid", "dir" and so forth have this set to false. This can also prevent fields being set when import tools are used.
|}

=== Internal Properties ===

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

{| cellpadding="3" cellspacing="0" border="1"
| name || default || description
|-
| '''parent_name''' || undef || On subfields of compound fields this is set automatically to be the name of the parent field.
|-
| '''confid''' || *special || This is set to the id of the dataset that this field belongs to and is used to work out what phrase ids etc. it uses.
|}

=== Deprecated or Buggy Properties ===

Don't use these!

{| cellpadding="3" cellspacing="0" border="1"
| name || default || description
|-
| '''input_advice_right''' || undef || Do not use.
|-
| '''input_advice_right''' || undef || Do not use.
|-
| '''input_assist''' || undef || Do not use.
|-
| '''requiredlangs''' || [] || Do not use.
|-
| '''allow_null''' || 0 || Do not use. Planned for use with compound fields, but not implemented in 3.0.
|}

== Required Phrases ==

These are phrases which you need to define in the local repository phrases file to control how this field renders. Some types of field (eg. [[set field]]s) have additional phrases in addition to the ones listed below.

The actual name of the field, as it will appear to users is stored in

datasetid + "_fieldname_" + fieldname

The default help to display, when the field is being input, is stored in

datasetid + "_fieldhelp_" + fieldname

For example:

<epp:phrase id="eprint_fieldname_abstract">Abstract</epp:phrase>
<epp:phrase id="eprint_fieldhelp_abstract">A summary of the items content.
If the item has a formal abstract then that is what should be entered
here. No complicated text formatting is possible.</epp:phrase>

== Database ==

Most fields have a representation in the SQL database using one or more columns. The sub-pages for each field type give the details.

== API ==

When you request (or set) a value of a metadata field, it is usually handled as a perl scalar (which is a string or number).

ALL values passed around in the API should be encoded in utf-8 or BAD THINGS may happen.

For example,

$eprint->set_value( "title", "For Us, The Living" );

Sets the title to the given string.

my $foo = $eprint->get_value( "title" );

Sets $foo to the string of the title, eg. "For Us, The Living".

=== Multiple Fields ===

If a field is set to multiple, then instead of a single value, a reference to an array of values is used. Eg.

$eprint->set_value( "corp_creators", [ "Jims Research", "Jones Research ] );

=== Other Exceptions ===

See the specific page for the full details.

* [[name field]]s are represented as a hash of the parts.

* [[compound field]]s do something a bit clever.

@@ Line 133: / Line 133: @@
 | '''maxlength''' || 255 || This is a limit to the maximum allowed size of a value. It may be useful, for example, as a very simple validation check. Also it may confuse users to be allowed to type in 255 characters in a "postcode/zipcode" field.
 |-
-| '''toform''' || undef || This function is allowed to modify the current value which appears in the form. For example, if your database stores userids in a field, but you want to allow people to edit them as usernames, then this function can be used to take the current value (a userid) and return the associated username. This value is what appears in the field in the search form. It is passed ( $value, $session, $object, $basename ) and returns the user-facing version of $value.
+| '''toform''' || undef || This function is allowed to modify the current value which appears in the form. For example, if your database stores userids in a field, but you want to allow people to edit them as usernames, then this function can be used to take the current value (a userid) and return the associated username. This value is what appears in the field in the search form. It is passed ( $value, $session, $object, $basename ) and returns the user-facing version of $value. **As of version 3.3.13 this only gets passed $value and $session in Metafield.pm**
 |-
 | '''fromform''' || undef || The inverse of toform. This takes the value from the form and converts it into the value that will be stored in the database. It is passed the parameters ( $value, $session) when $value is the value entered on the web 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.

← Older revision		Revision as of 19:07, 13 March 2010
Line 1:		Line 1:
		+	[[Category:EPrints 3 Reference]]
	{{fieldtypes}}		{{fieldtypes}}
−	~~[[Category:EPrints Metadata Fields]]~~
	== Metadata Field Types ==		== Metadata Field Types ==

@@ Line 48: / Line 48: @@
 * '''Basic metadata field'''
 ** '''[[File field|File]]''' - virtual field represtenting the files in a document
-** '''[[Id field|Id]]''' - deprecated (do not use)
+** '''[[Id field|Id]]'''
 ** '''Int'''
 *** '''[[Year field|Year]]''' - deprecated (do not use)

@@ Line 18: / Line 18: @@
-== Inherritance ==
+== Inheritance ==
 This is the list of ''useful'' field types. Under it is listed the other field types which are just included for completeness and are not intended to be used as part of the configuration.
-Some field types inherrit the properties of another, and then modify them in some way. For example the [[namedset field]] works like a  [[set field]] except that it gets its options from a namedsets file not from the options=>[] in the field properties.
+Some field types inherit the properties of another, and then modify them in some way. For example the [[namedset field]] works like a [[set field]] except that it gets its options from a namedsets file not from the options=>[] in the field properties.
 * '''Basic metadata field''' - this is abstract, fields must be one of the types listed below...
 ** '''[[Boolean field|Boolean]]''' - TRUE or FALSE (or can be unset, of course)
-** '''[[Compound field|Compound]]''' - virtual field, joins together several "multiple" fields. eg. author_name and author_email
+** '''[[Compound field|Compound]]''' - virtual field, joins together several "multiple" fields, e.g. author_name and author_email
-*** '''[[Multilang field|Multilang]]''' - allows language variants of a field. eg. titles in French, German and/or English.
+*** '''[[Multilang field|Multilang]]''' - allows language variants of a field, e.g. titles in French, German and/or English.
-** '''[[Date field|Date]]''' - stores a date.
+** '''[[Date field|Date]]''' - stores a date
-*** '''[[Time field|Time]]''' - stores a date and time.
+*** '''[[Time field|Time]]''' - stores a date and time
-** '''[[Float field|Float]]''' - stores a floating point value
+** '''[[Float field|Float]]''' - stores a floating-point value
 ** '''[[Int field|Int]]''' - a positive integer value
-*** '''[[Itemref field|Itemref]]''' - a reference to another [[Data Object]] (eg. a user or other eprint)
+*** '''[[Itemref field|Itemref]]''' - a reference to another [[Data Object]] (e.g. a user or other eprint)
-*** '''[[Pagerange field|Pagerange]]''' - a pagerange, eg 122-130
+*** '''[[Pagerange field|Pagerange]]''' - a pagerange, e.g. 122-130
 ** '''[[Search field|Search]]''' - a serialised search
 ** '''[[Set field|Set]]''' - a limited set of options
@@ Line 41: / Line 41: @@
 *** '''[[Email field|Email]]''' - an email address
 *** '''[[Longtext field|Longtext]]''' - like text but allows much longer text (65,000 bytes)
-*** '''[[Name field|Name]]''' - Stores a persons name broken up into logical parts.
+*** '''[[Name field|Name]]''' - Stores a person's name broken up into logical parts.
 *** '''[[Url field|Url]]''' - stores a URL
@@ Line 58: / Line 58: @@
 ** '''[[Subobject field|Subobject]]''' - a virtual field, similar to itemref, but representing an object or objects which are sub-parts of the current object (as oppose to just related in some way)
 ** '''Text'''
-*** '''[[Fulltext field|Fulltext]]''' - virtual field used to represent to the full text of an eprint
+*** '''[[Fulltext field|Fulltext]]''' - virtual field used to represent the full text of an eprint
-*** '''[[Secret field|Secret]]''' - used to store passwords.
+*** '''[[Secret field|Secret]]''' - used to store passwords
 == Properties ==

@@ Line 105: / Line 105: @@
 | '''render_dont_link''' || 0 || Set this to true to stop this field hyperlinking itself when rendered. Currently only affects [[url field]]s and [[email field]]s.
 |-
 | '''render_single_value''' || undef || The value of this property is the name of a subroutine to call to render 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: ( $session, $field, $value, $object). It should return an [[XHTML DOM]] object of the rendered value.
 |-