API:EPrints/MetaField

Latest Source Code (3.4, 3.3) | Revision Log | Before editing this page please read Pod2Wiki

NAME

EPrints::MetaField - A single metadata field.

DESCRIPTION

Theis object represents a single metadata field, not the value of that field. A field belongs (usually) to a dataset and has a large number of properties. Optional and required properties vary between types.

"type" is the most important property, it is the type of the metadata field. For example: "text", "name" or "date".

A full description of metadata types and properties is in the eprints documentation and will not be duplicated here.

new

 $field = EPrints::MetaField->new( %properties )

Create a new metafield. %properties is a hash of the properties of the field, with the addition of "dataset", or if "dataset" is not set then "confid" and "repository" must be provided instead.

Some field types require certain properties to be explicitly set. See the main documentation.

final

 $field->final

This method tells the metafield that it is now read only. Any call to set_property will produce a abort error.

set_property

 $field->set_property( $property, $value )

Set the named property to the given value.

This should not be called on metafields unless they've been cloned first.

This method will cause an abort error if the metafield is read only.

In these cases a cloned version of the field should be used.

clone

 $newfield = $field->clone

Clone the field, so the clone can be edited without affecting the original. Does not deep copy properties which are references - these should be set to new values, rather than the contents altered. Eg. don't push to a cloned options list, replace it.

get_dataset

 $dataset = $field->get_dataset

Return the dataset to which this field belongs, or undef.

render_name

 $xhtml = $field->render_name( $session )

Render the name of this field as an XHTML object.

display_name

 $label = $field->display_name( $session )

DEPRECATED! Can't be removed because it's used in 2.2's default ArchiveRenderConfig.pm

Return the UTF-8 encoded name of this field, in the language of the $session.

render_help

 $xhtml = $field->render_help( $session )

Return the help information for a user inputing some data for this field as an XHTML chunk.

render_input_field

 $xhtml = $field->render_input_field( $session, $value, [$dataset], [$staff], [$hidden_fields], $obj, [$basename] )

Return the XHTML of the fields for an form which will allow a user to input metadata to this field. $value is the default value for this field.

The actual function called may be overridden from the config.

form_value

 $value = $field->form_value( $session, $object, [$prefix] )

Get a value for this field from the CGI parameters, assuming that the form contained the input fields for this metadata field.

get_name

 $name = $field->get_name

Return the name of this field.

get_type

 $type = $field->get_type

Return the type of this field.

get_property

 $value = $field->get_property( $property )

Return the value of the given property.

Special note about "required" property: It only indicates if the field is always required. You must query the dataset to check if it is required for a specific type.

is_type

 $boolean = $field->is_type( @typenames )

Return true if the type of this field is one of @typenames.

render_value

 $xhtml = $field->render_value( $session, $value, [$alllangs], [$nolink], $object )

Render the given value of this given string as XHTML DOM. If $alllangs is true and this is a multilang field then render all language versions, not just the current language (for editorial checking). If $nolink is true then don't make this field a link, for example subject fields might otherwise link to the subject view page.

If render_value or render_single_value properties are set then these control the rendering instead.

render_value_no_multiple

 $xhtml = $field->render_value_no_multiple( $session, $value, $alllangs, $nolink, $object )

Render the XHTML for a non-multiple value. Can be either a from a non-multiple field, or a single value from a multiple field.

Usually just used internally.

render_value_withopts

 $xhtml = $field->render_value_withopts( $session, $value, $nolink, $object )

Render a single value but adding the render_opts features.

This uses either the field specific render_single_value or, if one is configured, the render_single_value specified in the config.

Usually just used internally.

sort_values

 $out_list = $field->sort_values( $session, $in_list )

Sorts the in_list into order, based on the "order values" of the values in the in_list. Assumes that the values are not a list of multiple values. [ [], [], [] ], but rather a list of single values.

list_values

 @values = $field->list_values( $value )

Return a list of every distinct value in this field.

- for simple fields: return ( $value )
- for multiple fields: return @{$value}
 

This function is used by the item_matches method in Search.

most_local

 $value = $field->most_local( $session, $value )

If this field is a multilang field then return the version of the value most useful for the language of the session. In order of preference: The language of the session, the default language for the repository, any language at all. If it is not a multilang field then just return $value.

call_property

 $value2 = $field->call_property( $property, @args )

Call the method described by $property. Pass it the arguments and return the result.

The property may contain either a code reference, or the scalar name of a method.

value_from_sql_row

 $val = $field->value_from_sql_row( $session, $row )

Shift and return the value of this field from the database input $row.

sql_row_from_value

 @row = $field->sql_row_from_value( $session, $value )

Return a list of values to insert into the database based on $value.

get_sql_type

 $sql = $field->get_sql_type( $session, $notnull )

Return the SQL type of this field, used for creating tables. $notnull being true indicates that this column may not be null.

get_sql_index

 $sql = $field->get_sql_index

Return the columns that an index should be created over.

render_single_value

 $xhtml_dom = $field->render_single_value( $session, $value )

Returns the XHTML representation of the value. The value will be non-multiple. Just the simple value.

render_input_field_actual

 $xhtml = $field->render_input_field_actual( $session, $value, [$dataset], [$staff], [$hidden_fields], [$obj], [$basename] )

Return the XHTML of the fields for an form which will allow a user to input metadata to this field. $value is the default value for this field.

Unlike render_input_field, this function does not use the render_input property, even if it's set.

The $obj is the current state of the object this field is associated with, if any.

get_sql_names

 @sqlnames = $field->get_sql_names

Return the names of this field's columns as they appear in a SQL table.

is_browsable

 $boolean = $field->is_browsable

Return true if this field can be "browsed". ie. Used as a view.

get_values

 $values = $field->get_values( $session, $dataset, %opts )

Return a reference to an array of all the values of this field. For fields like "subject" or "set" it returns all the variations. For fields like "text" return all the distinct values from the database.

Results are sorted according to the ordervalues of the $session.

get_id_from_value

 $id = $field->get_id_from_value( $session, $value )

Returns a unique id for $value.

get_value_label

 $xhtml = $field->get_value_label( $session, $value )

Return an XHTML DOM object describing the given value. Normally this is just the value, but in the case of something like a "set" field this returns the name of the option in the current language.

ordervalue

 $ov = $field->ordervalue( $value, $session, $langid, $dataset )

Return a string representing this value which can be used to sort it into order by comparing it alphabetically.

UNDOCUMENTED METHODS

These methods were found in the source code but didn't have any POD associated with them. This may be because we haven't got around to documenting them yet or it could be because they are internal to the API and not intended for use by other parts of EPrints.