Difference between revisions of "API:EPrints/MetaField"

From EPrints Documentation
Jump to: navigation, search
(New page: <!-- Pod2Wiki=_preamble_ This page has been automatically generated from the EPrints source. Any wiki changes made between the 'Pod2Wiki=*' and 'End of Pod2Wiki' comments will be lost. -...)
 
 
(12 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
<!-- Pod2Wiki=_preamble_  
 
<!-- Pod2Wiki=_preamble_  
−
This page has been automatically generated from the EPrints source. Any wiki changes made between the 'Pod2Wiki=*' and 'End of Pod2Wiki' comments will be lost.
+
This page has been automatically generated from the EPrints 3.2 source. Any wiki changes made between the 'Pod2Wiki=*' and 'Edit below this comment' comments will be lost.
−
  -->{{Pod2Wiki}}{{API:Source|file=EPrints/MetaField.pm|package_name=EPrints::MetaField}}[[Category:API|MetaField]]<!-- End of Pod2Wiki -->
+
  -->{{API}}{{Pod2Wiki}}{{API:Source|file=perl_lib/EPrints/MetaField.pm|package_name=EPrints::MetaField}}[[Category:API|METAFIELD]][[Category:API:EPrints/MetaField|METAFIELD]]<div><!-- Edit below this comment -->
−
<!-- Pod2Wiki=head_name -->=NAME=
 
−
'''EPrints::MetaField''' - A single metadata field.
 
  
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=head_description -->=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".
+
<!-- Pod2Wiki=_private_ --><!-- Pod2Wiki=head_name -->
 +
==NAME==
 +
EPrints::MetaField - A single metadata field.
  
−
A full description of metadata types and properties is in the eprints documentation and will not be duplicated here.
+
<!-- Edit below this comment -->
  
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_new -->==new==
 
  
−
  $field = EPrints::MetaField-&gt;new( %properties )
+
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_synopsis -->
 +
==SYNOPSIS==
 +
<source lang="perl">my $field = $dataset->field( $fieldname );
 +
$dataset = $field->dataset;
 +
$repo = $field->repository;
 +
$field->set_property( $property, $value );
 +
$value = $field->property( $property );
 +
$name = $field->name;
 +
$type = $field->type;
 +
$xhtml = $field->render_name;
 +
$xhtml = $field->render_help;
 +
$xhtml = $field->render_value_label( $value );
 +
$values = $field->all_values( %opts );
 +
$sorted_list = $field->sort_values( $unsorted_list );</source>
  
−
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.
+
<!-- Edit below this comment -->
  
−
Some field types require certain properties to be explicitly set. See the main documentation.
 
  
−
<!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki= -->
−
<!-- Pod2Wiki=item_final -->==final==
+
<!-- Pod2Wiki=head_description -->
 +
==DESCRIPTION==
 +
This 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.
  
−
  $field-&gt;final
+
"type" is the most important property, it is the type of the metadata field. For example: "text", "name" or "date".
  
−
This method tells the metafield that it is now read only. Any call to set_property will produce a abort error.
+
A full description of metadata types and properties is in the eprints documentation and will not be duplicated here.
  
−
<!-- End of Pod2Wiki -->
+
<!-- Edit below this comment -->
−
<!-- Pod2Wiki=item_set_property -->==set_property==
 
  
−
  $field-&gt;set_property( $property, $value )
 
  
−
Set the named property to the given value.
+
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_properties -->
 +
==PROPERTIES==
 +
* replace_core =&gt; 0
 +
: Normally any attempt to define two fields with the same name will fail. However, you can replace a core system field by specifying the "replace_core" property. This should be used very carefully!
  
−
This should not be called on metafields unless they've been cloned first.
+
<!-- Edit below this comment -->
  
−
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.
+
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_rendering -->
 +
===Rendering===
 +
* render_value =&gt; CODEREF
 +
<pre>  sub my_render_method
 +
  {
 +
    my( $repo, $field, $value, $all_langs, $no_link, $object ) = @_;
 +
 
 +
    return $repo->xml->create_text_node( $value );
 +
  }</pre>
  
−
<!-- End of Pod2Wiki -->
+
: Override the default rendering of values with a custom method. Renders $value (which may be a multiple) and returns an XHTML fragment.
−
<!-- Pod2Wiki=item_clone -->==clone==
 
  
−
  $newfield = $field-&gt;clone
+
<!-- Edit below this comment -->
  
−
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.
 
  
−
<!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki= -->
−
<!-- Pod2Wiki=item_get_dataset -->==get_dataset==
+
<!-- Pod2Wiki=head_read_only_properties -->
 +
===Read-only Properties===
 +
* provenance =&gt; "core" or "config"
 +
: Indiciates where the field was initialised from. "core" fields are defined in {{API:PodLink|file=DataObj|package_name=DataObj|section=|text=DataObj}} classes while "config" fields are defined in cfg.d files.
  
−
  $dataset = $field-&gt;get_dataset
+
<!-- Edit below this comment -->
  
−
Return the dataset to which this field belongs, or undef.
 
  
−
<!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki= -->
−
<!-- Pod2Wiki=item_render_name -->==render_name==
+
<!-- Pod2Wiki=head_methods -->
 +
==METHODS==
 +
<!-- Pod2Wiki=head_set_property -->
 +
===set_property===
  
−
  $xhtml = $field-&gt;render_name( $session )
+
<source lang="perl">$field->set_property( $property, $value )
  
−
Render the name of this field as an XHTML object.
+
</source>
 +
Set the named property to the given value.
  
−
<!-- End of Pod2Wiki -->
+
This should not be called on metafields unless they've been cloned first.
−
<!-- Pod2Wiki=item_display_name -->==display_name==
 
  
−
  $label = $field-&gt;display_name( $session )
+
This method will cause an abort error if the metafield is read only.
  
−
DEPRECATED! Can't be removed because it's used in 2.2's default ArchiveRenderConfig.pm
+
In these cases a cloned version of the field should be used.
  
−
Return the UTF-8 encoded name of this field, in the language of the $session.
+
<!-- Edit below this comment -->
  
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_render_help -->==render_help==
 
  
−
  $xhtml = $field-&gt;render_help( $session )
+
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_repository -->
 +
===repository===
  
−
Return the help information for a user inputing some data for this field as an XHTML chunk.
+
<source lang="perl">$repository = $field->repository
  
−
<!-- End of Pod2Wiki -->
+
</source>
−
<!-- Pod2Wiki=item_render_input_field -->==render_input_field==
+
Return the [[API:EPrints/Repository|EPrints::Repository]] to which this field belongs.
  
−
  $xhtml = $field-&gt;render_input_field( $session, $value, [$dataset], [$staff], [$hidden_fields], $obj, [$basename] )
+
<!-- Edit below this comment -->
  
−
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.
+
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_dataset -->
 +
===dataset===
  
−
<!-- End of Pod2Wiki -->
+
<source lang="perl">$dataset = $field->dataset
−
<!-- Pod2Wiki=item_form_value -->==form_value==
 
  
−
  $value = $field-&gt;form_value( $session, $object, [$prefix] )
+
</source>
 +
Return the [[API:EPrints/DataSet|EPrints::DataSet]] to which this field belongs, or undef.
  
−
Get a value for this field from the CGI parameters, assuming that the form contained the input fields for this metadata field.
+
<!-- Edit below this comment -->
  
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_get_name -->==get_name==
 
  
−
  $name = $field-&gt;get_name
+
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_render_name -->
 +
===render_name===
  
−
Return the name of this field.
+
<source lang="perl">$xhtml = $field->render_name
  
−
<!-- End of Pod2Wiki -->
+
</source>
−
<!-- Pod2Wiki=item_get_type -->==get_type==
+
Render the name of this field as an XHTML object.
  
−
  $type = $field-&gt;get_type
+
<!-- Edit below this comment -->
  
−
Return the type of this field.
 
  
−
<!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki= -->
−
<!-- Pod2Wiki=item_get_property -->==get_property==
+
<!-- Pod2Wiki=head_render_help -->
 +
===render_help===
  
−
  $value = $field-&gt;get_property( $property )
+
<source lang="perl">$xhtml = $field->render_help
  
−
Return the value of the given property.
+
</source>
 +
Return the help information for a user inputing some data for this field as an XHTML chunk.
  
−
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.
+
<!-- Edit below this comment -->
  
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_is_type -->==is_type==
 
  
−
  $boolean = $field-&gt;is_type( @typenames )
+
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_name -->
 +
===name===
  
−
Return true if the type of this field is one of @typenames.
+
<source lang="perl">$name = $field->name
  
−
<!-- End of Pod2Wiki -->
+
</source>
−
<!-- Pod2Wiki=item_render_value -->==render_value==
+
Return the name of this field.
  
−
  $xhtml = $field-&gt;render_value( $session, $value, [$alllangs], [$nolink], $object )
+
<!-- Edit below this comment -->
  
−
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.
+
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_type -->
 +
===type===
  
−
<!-- End of Pod2Wiki -->
+
<source lang="perl">$type = $field->type
−
<!-- Pod2Wiki=item_render_value_no_multiple -->==render_value_no_multiple==
 
  
−
  $xhtml = $field-&gt;render_value_no_multiple( $session, $value, $alllangs, $nolink, $object )
+
</source>
 +
Return the type of this field.
  
−
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.
+
<!-- Edit below this comment -->
  
−
Usually just used internally.
 
  
−
<!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki= -->
−
<!-- Pod2Wiki=item_render_value_withopts -->==render_value_withopts==
+
<!-- Pod2Wiki=head_property -->
 +
===property===
  
−
  $xhtml = $field-&gt;render_value_withopts( $session, $value, $nolink, $object )
+
<source lang="perl">$value = $field->property( $property )
  
−
Render a single value but adding the render_opts features.
+
</source>
 +
Return the value of the given property.
  
−
This uses either the field specific render_single_value or, if one is configured, the render_single_value specified in the config.
+
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.
  
−
Usually just used internally.
+
<!-- Edit below this comment -->
  
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_sort_values -->==sort_values==
 
  
−
  $out_list = $field-&gt;sort_values( $session, $in_list )
+
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_sort_values -->
 +
===sort_values===
  
 +
<source lang="perl">$out_list = $field->sort_values( $in_list, $langid )
 +
 +
</source>
 
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.
 
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.
  
−
<!-- End of Pod2Wiki -->
+
<!-- Edit below this comment -->
−
<!-- Pod2Wiki=item_list_values -->==list_values==
 
−
 
 
−
  @values = $field-&gt;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.
 
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_most_local -->==most_local==
 
−
 
 
−
  $value = $field-&gt;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.
 
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_call_property -->==call_property==
 
−
 
 
−
  $value2 = $field-&gt;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.
 
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_value_from_sql_row -->==value_from_sql_row==
 
−
 
 
−
  $val = $field-&gt;value_from_sql_row( $session, $row )
 
−
 
 
−
Shift and return the value of this field from the database input $row.
 
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_sql_row_from_value -->==sql_row_from_value==
 
−
 
 
−
  @row = $field-&gt;sql_row_from_value( $session, $value )
 
−
 
 
−
Return a list of values to insert into the database based on $value.
 
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_get_sql_type -->==get_sql_type==
 
−
 
 
−
  $sql = $field-&gt;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.
 
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_get_sql_index -->==get_sql_index==
 
  
−
  $sql = $field-&gt;get_sql_index
 
  
−
Return the columns that an index should be created over.
+
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_all_values -->
 +
===all_values===
  
−
<!-- End of Pod2Wiki -->
+
<source lang="perl">$values = $field->all_values( %opts )
−
<!-- Pod2Wiki=item_render_single_value -->==render_single_value==
 
−
 
 
−
  $xhtml_dom = $field-&gt;render_single_value( $session, $value )
 
−
 
 
−
Returns the XHTML representation of the value. The value will be non-multiple. Just the  simple value.
 
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_render_input_field_actual -->==render_input_field_actual==
 
−
 
 
−
  $xhtml = $field-&gt;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.
 
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_get_sql_names -->==get_sql_names==
 
−
 
 
−
  @sqlnames = $field-&gt;get_sql_names
 
−
 
 
−
Return the names of this field's columns as they appear in a SQL table.
 
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_is_browsable -->==is_browsable==
 
−
 
 
−
  $boolean = $field-&gt;is_browsable
 
−
 
 
−
Return true if this field can be "browsed". ie. Used as a view.
 
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_get_values -->==get_values==
 
−
 
 
−
  $values = $field-&gt;get_values( $session, $dataset, %opts )
 
  
 +
</source>
 
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.
 
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.
+
Results are sorted according to the ordervalues of the current session.
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_get_id_from_value -->==get_id_from_value==
 
−
 
 
−
  $id = $field-&gt;get_id_from_value( $session, $value )
 
−
 
 
−
Returns a unique id for $value.
 
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_get_value_label -->==get_value_label==
 
−
 
 
−
  $xhtml = $field-&gt;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.
 
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_ordervalue -->==ordervalue==
 
−
 
 
−
  $ov = $field-&gt;ordervalue( $value, $session, $langid, $dataset )
 
−
 
 
−
Return a string representing this value which can be used to sort it into order by comparing it alphabetically.
 
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=head_undocumented_methods -->=UNDOCUMENTED METHODS=
 
−
{{API:Undocumented Methods}}<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_form_value_actual -->==form_value_actual==
 
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_form_value_basic -->==form_value_basic==
 
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_form_value_single -->==form_value_single==
 
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_from_search_form -->==from_search_form==
 
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_get_basic_input_elements -->==get_basic_input_elements==
 
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_get_basic_input_ids -->==get_basic_input_ids==
 
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_get_ids_by_value -->==get_ids_by_value==
 
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_get_index_codes -->==get_index_codes==
 
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_get_input_col_titles -->==get_input_col_titles==
 
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_get_input_elements -->==get_input_elements==
 
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_get_input_elements_single -->==get_input_elements_single==
 
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_get_max_input_size -->==get_max_input_size==
 
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_get_property_defaults -->==get_property_defaults==
 
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_get_search_conditions -->==get_search_conditions==
 
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_get_search_group -->==get_search_group==
 
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_get_sql_name -->==get_sql_name==
 
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_get_state_params -->==get_state_params==
 
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_get_unsorted_values -->==get_unsorted_values==
 
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_get_value -->==get_value==
 
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_get_xml_schema_type -->==get_xml_schema_type==
 
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_is_virtual -->==is_virtual==
 
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_ordervalue_basic -->==ordervalue_basic==
 
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_ordervalue_single -->==ordervalue_single==
 
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_render_search_description -->==render_search_description==
 
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_render_search_input -->==render_search_input==
 
−
 
 
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_render_search_value -->==render_search_value==
 
  
−
<!-- End of Pod2Wiki -->
+
<!-- Edit below this comment -->
−
<!-- Pod2Wiki=item_render_value_actual -->==render_value_actual==
 
  
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_render_xml_schema -->==render_xml_schema==
 
  
−
<!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki= -->
−
<!-- Pod2Wiki=item_render_xml_schema_type -->==render_xml_schema_type==
+
<!-- Edit below this comment -->
  
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_set_value -->==set_value==
 
  
−
<!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki= -->
−
<!-- Pod2Wiki=item_should_reverse_order -->==should_reverse_order==
+
<!-- Pod2Wiki=head_copyright -->
 +
==COPYRIGHT==
 +
Copyright 2000-2011 University of Southampton.
  
−
<!-- End of Pod2Wiki -->
+
This file is part of EPrints http://www.eprints.org/.
−
<!-- Pod2Wiki=item_split_search_value -->==split_search_value==
 
  
−
<!-- End of Pod2Wiki -->
+
EPrints is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
−
<!-- Pod2Wiki=item_to_xml -->==to_xml==
 
  
−
<!-- End of Pod2Wiki -->
+
EPrints is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
−
<!-- Pod2Wiki=item_to_xml_basic -->==to_xml_basic==
 
  
−
<!-- End of Pod2Wiki -->
+
You should have received a copy of the GNU Lesser General Public License along with EPrints.  If not, see http://www.gnu.org/licenses/.
−
<!-- Pod2Wiki=item_to_xml_old -->==to_xml_old==
 
  
−
<!-- End of Pod2Wiki -->
+
<!-- Edit below this comment -->
−
<!-- Pod2Wiki=item_to_xml_old_single -->==to_xml_old_single==
 
  
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_validate -->==validate==
 
  
−
<!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki= -->
−
<!-- Pod2Wiki=_postamble_ --><!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki=_postamble_ -->
 +
<!-- Edit below this comment -->

Latest revision as of 09:44, 11 May 2012

EPrints 3 Reference: Directory Structure - Metadata Fields - Repository Configuration - XML Config Files - XML Export Format - EPrints data structure - Core API - Data Objects

API: Core API

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


NAME

EPrints::MetaField - A single metadata field.


SYNOPSIS

my $field = $dataset->field( $fieldname );
$dataset = $field->dataset;
$repo = $field->repository;
$field->set_property( $property, $value );
$value = $field->property( $property );
$name = $field->name;
$type = $field->type;
$xhtml = $field->render_name;
$xhtml = $field->render_help;
$xhtml = $field->render_value_label( $value );
$values = $field->all_values( %opts );
$sorted_list = $field->sort_values( $unsorted_list );


DESCRIPTION

This 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.


PROPERTIES

  • replace_core => 0
Normally any attempt to define two fields with the same name will fail. However, you can replace a core system field by specifying the "replace_core" property. This should be used very carefully!


Rendering

  • render_value => CODEREF
  sub my_render_method
  {
    my( $repo, $field, $value, $all_langs, $no_link, $object ) = @_;
  
    return $repo->xml->create_text_node( $value );
  }
Override the default rendering of values with a custom method. Renders $value (which may be a multiple) and returns an XHTML fragment.


Read-only Properties

  • provenance => "core" or "config"
Indiciates where the field was initialised from. "core" fields are defined in DataObj classes while "config" fields are defined in cfg.d files.


METHODS

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.


repository

$repository = $field->repository

Return the EPrints::Repository to which this field belongs.


dataset

$dataset = $field->dataset

Return the EPrints::DataSet to which this field belongs, or undef.


render_name

$xhtml = $field->render_name

Render the name of this field as an XHTML object.


render_help

$xhtml = $field->render_help

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


name

$name = $field->name

Return the name of this field.


type

$type = $field->type

Return the type of this field.


property

$value = $field->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.


sort_values

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

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.


all_values

$values = $field->all_values( %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 current session.



COPYRIGHT

Copyright 2000-2011 University of Southampton.

This file is part of EPrints http://www.eprints.org/.

EPrints is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

EPrints is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with EPrints. If not, see http://www.gnu.org/licenses/.



Retrieved from ‘https://wiki.eprints.org/w/index.php?title=API:EPrints/MetaField&oldid=10488’