Difference between revisions of "API:EPrints/MetaField"

From EPrints Documentation
Jump to: navigation, search
Line 23: Line 23:
 
A full description of metadata types and properties is in the eprints documentation and will not be duplicated here.
 
A full description of metadata types and properties is in the eprints documentation and will not be duplicated here.
  
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 +
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=head_methods -->
 +
==METHODS==
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
<span style='display:none'>User Comments</span>
Line 31: Line 40:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_new -->
 
<!-- Pod2Wiki=item_new -->
−
===$field = EPrints::MetaField-&gt;new( %properties )===
+
===new===
  
 +
$field = EPrints::MetaField-&gt;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.
 
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.
  
Line 45: Line 55:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_final -->
 
<!-- Pod2Wiki=item_final -->
−
===$field-&gt;final===
+
===final===
  
 +
$field-&gt;final
 
This method tells the metafield that it is now read only. Any call to set_property will produce a abort error.
 
This method tells the metafield that it is now read only. Any call to set_property will produce a abort error.
  
Line 57: Line 68:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_set_property -->
 
<!-- Pod2Wiki=item_set_property -->
−
===$field-&gt;set_property( $property, $value )===
+
===set_property===
  
 +
$field-&gt;set_property( $property, $value )
 
Set the named property to the given value.
 
Set the named property to the given value.
  
Line 75: Line 87:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_clone -->
 
<!-- Pod2Wiki=item_clone -->
−
===$newfield = $field-&gt;clone===
+
===clone===
  
 +
$newfield = $field-&gt;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.
 
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.
  
Line 87: Line 100:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_repository -->
 
<!-- Pod2Wiki=item_repository -->
−
===$repository = $field-&gt;repository===
+
===repository===
  
 +
$repository = $field-&gt;repository
 
Return the [[API:EPrints/Repository|EPrints::Repository]] to which this field belongs.
 
Return the [[API:EPrints/Repository|EPrints::Repository]] to which this field belongs.
  
Line 99: Line 113:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_dataset -->
 
<!-- Pod2Wiki=item_dataset -->
−
===$dataset = $field-&gt;dataset===
+
===dataset===
  
 +
$dataset = $field-&gt;dataset
 
Return the [[API:EPrints/DataSet|EPrints::DataSet]] to which this field belongs, or undef.
 
Return the [[API:EPrints/DataSet|EPrints::DataSet]] to which this field belongs, or undef.
  
Line 111: Line 126:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_render_name -->
 
<!-- Pod2Wiki=item_render_name -->
−
===$xhtml = $field-&gt;render_name===
+
===render_name===
  
 +
$xhtml = $field-&gt;render_name
 
Render the name of this field as an XHTML object.
 
Render the name of this field as an XHTML object.
  
Line 123: Line 139:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_display_name -->
 
<!-- Pod2Wiki=item_display_name -->
−
===$label = $field-&gt;display_name( $session )===
+
===display_name===
  
 +
$label = $field-&gt;display_name( $session )
 
DEPRECATED! Can't be removed because it's used in 2.2's default ArchiveRenderConfig.pm
 
DEPRECATED! Can't be removed because it's used in 2.2's default ArchiveRenderConfig.pm
  
Line 137: Line 154:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_render_help -->
 
<!-- Pod2Wiki=item_render_help -->
−
===$xhtml = $field-&gt;render_help===
+
===render_help===
  
 +
$xhtml = $field-&gt;render_help
 
Return the help information for a user inputing some data for this field as an XHTML chunk.
 
Return the help information for a user inputing some data for this field as an XHTML chunk.
  
Line 149: Line 167:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_render_input_field -->
 
<!-- Pod2Wiki=item_render_input_field -->
−
===$xhtml = $field-&gt;render_input_field( $session, $value, [$dataset], [$staff], [$hidden_fields], $obj, [$basename] )===
+
===render_input_field===
  
 +
$xhtml = $field-&gt;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.
 
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.
  
Line 163: Line 182:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_form_value -->
 
<!-- Pod2Wiki=item_form_value -->
−
===$value = $field-&gt;form_value( $session, $object, [$prefix] )===
+
===form_value===
  
 +
$value = $field-&gt;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 a value for this field from the CGI parameters, assuming that the form contained the input fields for this metadata field.
  
Line 175: Line 195:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_name -->
 
<!-- Pod2Wiki=item_name -->
−
===$name = $field-&gt;name===
+
===name===
  
 +
$name = $field-&gt;name
 
Return the name of this field.
 
Return the name of this field.
  
Line 187: Line 208:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_type -->
 
<!-- Pod2Wiki=item_type -->
−
===$type = $field-&gt;type===
+
===type===
  
 +
$type = $field-&gt;type
 
Return the type of this field.
 
Return the type of this field.
  
Line 199: Line 221:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_property -->
 
<!-- Pod2Wiki=item_property -->
−
===$value = $field-&gt;property( $property )===
+
===property===
  
 +
$value = $field-&gt;property( $property )
 
Return the value of the given property.
 
Return the value of the given property.
  
Line 213: Line 236:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_is_type -->
 
<!-- Pod2Wiki=item_is_type -->
−
===$boolean = $field-&gt;is_type( @typenames )===
+
===is_type===
  
 +
$boolean = $field-&gt;is_type( @typenames )
 
Return true if the type of this field is one of @typenames.
 
Return true if the type of this field is one of @typenames.
  
Line 225: Line 249:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_render_value -->
 
<!-- Pod2Wiki=item_render_value -->
−
===$xhtml = $field-&gt;render_value( $session, $value, [$alllangs], [$nolink], $object )===
+
===render_value===
  
 +
$xhtml = $field-&gt;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.
 
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.
  
Line 239: Line 264:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_render_value_no_multiple -->
 
<!-- Pod2Wiki=item_render_value_no_multiple -->
−
===$xhtml = $field-&gt;render_value_no_multiple( $session, $value, $alllangs, $nolink, $object )===
+
===render_value_no_multiple===
  
 +
$xhtml = $field-&gt;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.
 
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.
  
Line 253: Line 279:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_render_value_withopts -->
 
<!-- Pod2Wiki=item_render_value_withopts -->
−
===$xhtml = $field-&gt;render_value_withopts( $session, $value, $nolink, $object )===
+
===render_value_withopts===
  
 +
$xhtml = $field-&gt;render_value_withopts( $session, $value, $nolink, $object )
 
Render a single value but adding the render_opts features.
 
Render a single value but adding the render_opts features.
  
Line 269: Line 296:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_sort_values -->
 
<!-- Pod2Wiki=item_sort_values -->
−
===$out_list = $field-&gt;sort_values( $session, $in_list )===
+
===sort_values===
  
 +
$out_list = $field-&gt;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.
 
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.
  
Line 281: Line 309:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_list_values -->
 
<!-- Pod2Wiki=item_list_values -->
−
===@values = $field-&gt;list_values( $value )===
+
===list_values===
  
 +
@values = $field-&gt;list_values( $value )
 
Return a list of every distinct value in this field.  
 
Return a list of every distinct value in this field.  
  
Line 298: Line 327:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_most_local -->
 
<!-- Pod2Wiki=item_most_local -->
−
===$value = $field-&gt;most_local( $session, $value )===
+
===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.
 
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.
  
Line 310: Line 340:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_call_property -->
 
<!-- Pod2Wiki=item_call_property -->
−
===$value2 = $field-&gt;call_property( $property, @args )===
+
===call_property===
  
 +
$value2 = $field-&gt;call_property( $property, @args )
 
Call the method described by $property. Pass it the arguments and return the result.
 
Call the method described by $property. Pass it the arguments and return the result.
  
Line 324: Line 355:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_value_from_sql_row -->
 
<!-- Pod2Wiki=item_value_from_sql_row -->
−
===$val = $field-&gt;value_from_sql_row( $session, $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.
 
Shift and return the value of this field from the database input $row.
  
Line 336: Line 368:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_sql_row_from_value -->
 
<!-- Pod2Wiki=item_sql_row_from_value -->
−
===@row = $field-&gt;sql_row_from_value( $session, $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.
 
Return a list of values to insert into the database based on $value.
  
Line 358: Line 391:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_get_sql_properties -->
 
<!-- Pod2Wiki=item_get_sql_properties -->
−
===%opts = $field-&gt;get_sql_properties( $session )===
+
===get_sql_properties===
  
 +
%opts = $field-&gt;get_sql_properties( $session )
 
Map the relevant SQL properties for this field to options passed to [[API:EPrints/Database|EPrints::Database]]::get_column_type().
 
Map the relevant SQL properties for this field to options passed to [[API:EPrints/Database|EPrints::Database]]::get_column_type().
  
Line 370: Line 404:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_get_sql_type -->
 
<!-- Pod2Wiki=item_get_sql_type -->
−
===@types = $field-&gt;get_sql_type( $session )===
+
===get_sql_type===
  
 +
@types = $field-&gt;get_sql_type( $session )
 
Return the SQL column types of this field, used for creating tables.
 
Return the SQL column types of this field, used for creating tables.
  
Line 382: Line 417:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_create_ordervalues_field -->
 
<!-- Pod2Wiki=item_create_ordervalues_field -->
−
===$field = $field-&gt;create_ordervalues_field( $session [, $langid ] )===
+
===create_ordervalues_field===
  
 +
$field = $field-&gt;create_ordervalues_field( $session [, $langid ] )
 
Return a new field object that this field can use to store order values, optionally for language $langid.
 
Return a new field object that this field can use to store order values, optionally for language $langid.
  
Line 394: Line 430:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_get_sql_index -->
 
<!-- Pod2Wiki=item_get_sql_index -->
−
===$sql = $field-&gt;get_sql_index===
+
===get_sql_index===
  
 +
$sql = $field-&gt;get_sql_index
 
Return the columns that an index should be created over.
 
Return the columns that an index should be created over.
  
Line 406: Line 443:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_render_single_value -->
 
<!-- Pod2Wiki=item_render_single_value -->
−
===$xhtml_dom = $field-&gt;render_single_value( $session, $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.
 
Returns the XHTML representation of the value. The value will be non-multiple. Just the  simple value.
  
Line 418: Line 456:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_render_input_field_actual -->
 
<!-- Pod2Wiki=item_render_input_field_actual -->
−
===$xhtml = $field-&gt;render_input_field_actual( $session, $value, [$dataset], [$staff], [$hidden_fields], [$obj], [$basename] )===
+
===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.
 
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.
  
Line 434: Line 473:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_get_sql_names -->
 
<!-- Pod2Wiki=item_get_sql_names -->
−
===@sqlnames = $field-&gt;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.
 
Return the names of this field's columns as they appear in a SQL table.
  
Line 446: Line 486:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_is_browsable -->
 
<!-- Pod2Wiki=item_is_browsable -->
−
===$boolean = $field-&gt;is_browsable===
+
===is_browsable===
  
 +
$boolean = $field-&gt;is_browsable
 
Return true if this field can be "browsed". ie. Used as a view.
 
Return true if this field can be "browsed". ie. Used as a view.
  
Line 458: Line 499:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_all_values -->
 
<!-- Pod2Wiki=item_all_values -->
−
===$values = $field-&gt;all_values( %opts )===
+
===all_values===
  
 +
$values = $field-&gt;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.
 
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.
  
Line 472: Line 514:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_get_id_from_value -->
 
<!-- Pod2Wiki=item_get_id_from_value -->
−
===$id = $field-&gt;get_id_from_value( $session, $value )===
+
===get_id_from_value===
  
 +
$id = $field-&gt;get_id_from_value( $session, $value )
 
Returns a unique id for $value or "NULL" if $value is undefined.
 
Returns a unique id for $value or "NULL" if $value is undefined.
  
Line 484: Line 527:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_get_value_from_id -->
 
<!-- Pod2Wiki=item_get_value_from_id -->
−
===$value = $field-&gt;get_value_from_id( $session, $id )===
+
===get_value_from_id===
  
 +
$value = $field-&gt;get_value_from_id( $session, $id )
 
Returns the value from $id or undef if $id is "NULL".
 
Returns the value from $id or undef if $id is "NULL".
  
Line 496: Line 540:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_render_value_label -->
 
<!-- Pod2Wiki=item_render_value_label -->
−
===$xhtml = $field-&gt;render_value_label( $value )===
+
===render_value_label===
  
 +
$xhtml = $field-&gt;render_value_label( $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.
 
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.
  
Line 508: Line 553:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_ordervalue -->
 
<!-- Pod2Wiki=item_ordervalue -->
−
===$ov = $field-&gt;ordervalue( $value, $session, $langid, $dataset )===
+
===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.
 
Return a string representing this value which can be used to sort it into order by comparing it alphabetically.
  
Line 520: Line 566:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_xml_to_epdata -->
 
<!-- Pod2Wiki=item_xml_to_epdata -->
−
===$epdata = $field-&gt;xml_to_epdata( $session, $xml, %opts )===
+
===xml_to_epdata===
  
 +
$epdata = $field-&gt;xml_to_epdata( $session, $xml, %opts )
 
Populates $epdata based on $xml.
 
Populates $epdata based on $xml.
  
Line 532: Line 579:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_get_default_value -->
 
<!-- Pod2Wiki=item_get_default_value -->
−
===$value = $field-&gt;get_default_value( $session )===
+
===get_default_value===
  
 +
$value = $field-&gt;get_default_value( $session )
 
Return the default value for this field. This is only applicable to very simple cases such as timestamps, auto-incremented values etc.
 
Return the default value for this field. This is only applicable to very simple cases such as timestamps, auto-incremented values etc.
  
Line 546: Line 594:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_get_index_codes -->
 
<!-- Pod2Wiki=item_get_index_codes -->
−
===( $terms, $grep_terms, $ignored ) = $field-&gt;get_index_codes( $session, $value )===
+
===get_index_codes===
  
 +
( $terms, $grep_terms, $ignored ) = $field-&gt;get_index_codes( $session, $value )
 
Get indexable terms from $value. $terms is a reference to an array of strings to index. $grep_terms is a reference to an array of terms to add to the grep index. $ignored is a reference to an array of terms that should be ignored (e.g. stop words in a free-text field).
 
Get indexable terms from $value. $terms is a reference to an array of strings to index. $grep_terms is a reference to an array of terms to add to the grep index. $ignored is a reference to an array of terms that should be ignored (e.g. stop words in a free-text field).
  
Line 558: Line 607:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_split_search_value -->
 
<!-- Pod2Wiki=item_split_search_value -->
−
===@terms = $field-&gt;split_search_value( $session, $value )===
+
===split_search_value===
  
 +
@terms = $field-&gt;split_search_value( $session, $value )
 
Split $value into terms that can be used to search against this field.
 
Split $value into terms that can be used to search against this field.
  
Line 570: Line 620:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_get_search_conditions -->
 
<!-- Pod2Wiki=item_get_search_conditions -->
−
===$cond = $field-&gt;get_search_conditions( $session, $dataset, $value, $match, $merge, $mode )===
+
===get_search_conditions===
  
 +
$cond = $field-&gt;get_search_conditions( $session, $dataset, $value, $match, $merge, $mode )
 
Return a {{API:PodLink|file=Search/Condition|package_name=Search::Condition|section=|text=Search::Condition}} for $value based on this field.
 
Return a {{API:PodLink|file=Search/Condition|package_name=Search::Condition|section=|text=Search::Condition}} for $value based on this field.
  
Line 582: Line 633:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_get_search_conditions_not_ex -->
 
<!-- Pod2Wiki=item_get_search_conditions_not_ex -->
−
===$cond = $field-&gt;get_search_conditions_not_ex( $session, $dataset, $value, $match, $merge, $mode )===
+
===get_search_conditions_not_ex===
  
 +
$cond = $field-&gt;get_search_conditions_not_ex( $session, $dataset, $value, $match, $merge, $mode )
 
Return the search condition for a search which is not-exact ($match ne "EX").
 
Return the search condition for a search which is not-exact ($match ne "EX").
  

Revision as of 14:56, 25 February 2010

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.

User Comments


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.

User Comments


METHODS

User Comments


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.

User Comments


final

$field->final

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

User Comments


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.

User Comments


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.

User Comments


repository

$repository = $field->repository

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

User Comments


dataset

$dataset = $field->dataset

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

User Comments


render_name

$xhtml = $field->render_name

Render the name of this field as an XHTML object.

User Comments


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.

User Comments


render_help

$xhtml = $field->render_help

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

User Comments


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.

User Comments


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.

User Comments


name

$name = $field->name

Return the name of this field.

User Comments


type

$type = $field->type

Return the type of this field.

User Comments


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.

User Comments


is_type

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

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

User Comments


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.

User Comments


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.

User Comments


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.

User Comments


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.

User Comments


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.

User Comments


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.

User Comments


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.

User Comments


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.

User Comments


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.

The values will normally be passed to DBI/bind_param: 

 $sth->bind_param( $idx, $row[0] )

If the value is an array ref it gets expanded: 

 $sth->bind_param( $idx, @{$row[0]} )

This is necessary to support binding LOB data under various databases.

User Comments


get_sql_properties

%opts = $field->get_sql_properties( $session )

Map the relevant SQL properties for this field to options passed to EPrints::Database::get_column_type().

User Comments


get_sql_type

@types = $field->get_sql_type( $session )

Return the SQL column types of this field, used for creating tables.

User Comments


create_ordervalues_field

$field = $field->create_ordervalues_field( $session [, $langid ] )

Return a new field object that this field can use to store order values, optionally for language $langid.

User Comments


get_sql_index

$sql = $field->get_sql_index

Return the columns that an index should be created over.

User Comments


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.

User Comments


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.

User Comments


get_sql_names

@sqlnames = $field->get_sql_names

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

User Comments


is_browsable

$boolean = $field->is_browsable

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

User Comments


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.

User Comments


get_id_from_value

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

Returns a unique id for $value or "NULL" if $value is undefined.

User Comments


get_value_from_id

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

Returns the value from $id or undef if $id is "NULL".

User Comments


render_value_label

$xhtml = $field->render_value_label( $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.

User Comments


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.

User Comments


xml_to_epdata

$epdata = $field->xml_to_epdata( $session, $xml, %opts )

Populates $epdata based on $xml.

User Comments


get_default_value

$value = $field->get_default_value( $session )

Return the default value for this field. This is only applicable to very simple cases such as timestamps, auto-incremented values etc.

Any complex initialisation should be done in the "set_eprint_automatic_fields" callback (or the equivalent for the given object).

User Comments


get_index_codes

( $terms, $grep_terms, $ignored ) = $field->get_index_codes( $session, $value )

Get indexable terms from $value. $terms is a reference to an array of strings to index. $grep_terms is a reference to an array of terms to add to the grep index. $ignored is a reference to an array of terms that should be ignored (e.g. stop words in a free-text field).

User Comments


split_search_value

@terms = $field->split_search_value( $session, $value )

Split $value into terms that can be used to search against this field.

User Comments


get_search_conditions

$cond = $field->get_search_conditions( $session, $dataset, $value, $match, $merge, $mode )

Return a Search::Condition for $value based on this field.

User Comments


get_search_conditions_not_ex

$cond = $field->get_search_conditions_not_ex( $session, $dataset, $value, $match, $merge, $mode )

Return the search condition for a search which is not-exact ($match ne "EX").

User Comments


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