Difference between revisions of "API:EPrints/MetaField"

From EPrints Documentation
Jump to: navigation, search
Line 1: Line 1:
wef
+
<!-- Pod2Wiki=_preamble_
 +
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.
 +
-->
 +
__NOTOC__
 +
{{Pod2Wiki}}{{API:Source|file=EPrints/MetaField.pm|package_name=EPrints::MetaField}}[[Category:API|MetaField]]<div><!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki=head_name --></div>
 +
==NAME==
 +
'''EPrints::MetaField''' - A single metadata field.
 +
 
 +
<div style='background-color: #eef; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<h4><span style='display:none'>User Comments</span></h4>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki=head_synopsis --></div>
 +
==SYNOPSIS==
 +
  my $field = $dataset-&gt;get_field( $fieldname );
 +
 
 +
  # you must clone a field to modify any properties
 +
  $newfield = $field-&gt;clone;
 +
  $newfield-&gt;set_property( $property, $value );
 +
 
 +
  $name = $field-&gt;get_name;
 +
  $type = $field-&gt;get_type;
 +
  $value = $field-&gt;get_property( $property );
 +
  $boolean = $field-&gt;is_type( @typenames );
 +
  $results = $field-&gt;call_property( $property, @args );
 +
  # (results depend on what the property sub returns)
 +
 
 +
  $xhtml = $field-&gt;render_name( $handle );
 +
  $xhtml = $field-&gt;render_help( $handle );
 +
  $xhtml = $field-&gt;render_value( $handle, $value, $show_all_langs, $dont_include_links, $object );
 +
  $xhtml = $field-&gt;render_single_value( $handle, $value );
 +
  $xhtml = $field-&gt;get_value_label( $handle, $value );
 +
 
 +
  $values = $field-&gt;get_values( $handle, $dataset, %opts );
 +
 
 +
  $sorted_list = $field-&gt;sort_values( $handle, $unsorted_list );
 +
 
 +
<div style='background-color: #eef; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<h4><span style='display:none'>User Comments</span></h4>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki=head_description --></div>
 +
==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.
 +
 
 +
<div style='background-color: #eef; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<h4><span style='display:none'>User Comments</span></h4>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki=head_methods --></div>
 +
==METHODS==
 +
<div style='background-color: #eef; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<h4><span style='display:none'>User Comments</span></h4>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki=item_set_property --></div>
 +
===$field-&gt;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.
 +
 
 +
<div style='background-color: #eef; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<h4><span style='display:none'>User Comments</span></h4>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki=item_clone --></div>
 +
===$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.
 +
 
 +
<div style='background-color: #eef; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<h4><span style='display:none'>User Comments</span></h4>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki=item_get_dataset --></div>
 +
===$dataset = $field-&gt;get_dataset===
 +
 
 +
Return the dataset to which this field belongs, or undef.
 +
 
 +
<div style='background-color: #eef; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<h4><span style='display:none'>User Comments</span></h4>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki=item_render_name --></div>
 +
===$xhtml = $field-&gt;render_name( $handle )===
 +
 
 +
Render the name of this field as an XHTML object.
 +
 
 +
<div style='background-color: #eef; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<h4><span style='display:none'>User Comments</span></h4>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki=item_render_help --></div>
 +
===$xhtml = $field-&gt;render_help( $handle )===
 +
 
 +
Return the help information for a user inputing some data for this field as an XHTML chunk.
 +
 
 +
<div style='background-color: #eef; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<h4><span style='display:none'>User Comments</span></h4>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki=item_render_input_field --></div>
 +
===$xhtml = $field-&gt;render_input_field( $handle, $value, [$dataset], [$staff], [$hidden_fields], $obj, [$prefix] )===
 +
 
 +
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 options.
 +
 
 +
<div style='background-color: #eef; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<h4><span style='display:none'>User Comments</span></h4>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki=item_form_value --></div>
 +
===$value = $field-&gt;form_value( $handle, $object, [$prefix] )===
 +
 
 +
Get a value for this field from the CGI parameters, assuming that the form contained the input fields for this metadata field.
 +
 
 +
<div style='background-color: #eef; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<h4><span style='display:none'>User Comments</span></h4>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki=item_get_name --></div>
 +
===$name = $field-&gt;get_name===
 +
 
 +
Return the name of this field.
 +
 
 +
<div style='background-color: #eef; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<h4><span style='display:none'>User Comments</span></h4>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki=item_get_type --></div>
 +
===$type = $field-&gt;get_type===
 +
 
 +
Return the type of this field.
 +
 
 +
<div style='background-color: #eef; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<h4><span style='display:none'>User Comments</span></h4>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki=item_get_property --></div>
 +
===$value = $field-&gt;get_property( $property )===
 +
 
 +
Return the value of the given property.
 +
 
 +
Special note about "required" property, the workflow may in some situations return a field which is 'required' which isn't if you get it via $dataset.
 +
 
 +
There's about 50 in total, with additional extras for some subtypes of MetaField! However the most useful ones are:
 +
 
 +
  if( $field-&gt;get_property( "multiple" ) ) { ... }
 +
  if( $field-&gt;get_property( "required" ) ) { ... }
 +
 
 +
<div style='background-color: #eef; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<h4><span style='display:none'>User Comments</span></h4>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki=item_is_type --></div>
 +
===$boolean = $field-&gt;is_type( @typenames )===
 +
 
 +
Return true if the type of this field is one of @typenames.
 +
 
 +
<div style='background-color: #eef; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<h4><span style='display:none'>User Comments</span></h4>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki=item_render_value --></div>
 +
===$xhtml = $field-&gt;render_value( $handle, $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.
 +
 
 +
<div style='background-color: #eef; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<h4><span style='display:none'>User Comments</span></h4>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki=item_sort_values --></div>
 +
===$out_list = $field-&gt;sort_values( $handle, $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.
 +
 
 +
<div style='background-color: #eef; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<h4><span style='display:none'>User Comments</span></h4>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki=item_call_property --></div>
 +
===$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.
 +
 
 +
<div style='background-color: #eef; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<h4><span style='display:none'>User Comments</span></h4>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki=item_render_single_value --></div>
 +
===$xhtml_dom = $field-&gt;render_single_value( $handle, $value )===
 +
 
 +
Returns the XHTML representation of the value. If the field is multiple then $value should be a single item from the values, not the list.
 +
 
 +
<div style='background-color: #eef; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<h4><span style='display:none'>User Comments</span></h4>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki=item_get_values --></div>
 +
===$values = $field-&gt;get_values( $handle, $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 $handle.
 +
 
 +
<div style='background-color: #eef; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<h4><span style='display:none'>User Comments</span></h4>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki=item_get_value_label --></div>
 +
===$xhtml = $field-&gt;get_value_label( $handle, $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.
 +
 
 +
<div style='background-color: #eef; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<h4><span style='display:none'>User Comments</span></h4>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki=_postamble_ --><!-- Edit below this comment -->

Revision as of 16:01, 19 August 2009


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


NAME

EPrints::MetaField - A single metadata field.

User Comments


SYNOPSIS

 my $field = $dataset->get_field( $fieldname );
 
 # you must clone a field to modify any properties
 $newfield = $field->clone;
 $newfield->set_property( $property, $value );
 
 $name = $field->get_name;
 $type = $field->get_type;
 $value = $field->get_property( $property );
 $boolean = $field->is_type( @typenames );
 $results = $field->call_property( $property, @args ); 
 # (results depend on what the property sub returns)
 
 $xhtml = $field->render_name( $handle );
 $xhtml = $field->render_help( $handle );
 $xhtml = $field->render_value( $handle, $value, $show_all_langs, $dont_include_links, $object );
 $xhtml = $field->render_single_value( $handle, $value );
 $xhtml = $field->get_value_label( $handle, $value );
 
 $values = $field->get_values( $handle, $dataset, %opts );
 
 $sorted_list = $field->sort_values( $handle, $unsorted_list );
 

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


$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


$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


$dataset = $field->get_dataset

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

User Comments


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

Render the name of this field as an XHTML object.

User Comments


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

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

User Comments


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

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

User Comments


$value = $field->form_value( $handle, $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 = $field->get_name

Return the name of this field.

User Comments


$type = $field->get_type

Return the type of this field.

User Comments


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

Return the value of the given property.

Special note about "required" property, the workflow may in some situations return a field which is 'required' which isn't if you get it via $dataset.

There's about 50 in total, with additional extras for some subtypes of MetaField! However the most useful ones are:

 if( $field->get_property( "multiple" ) ) { ... }
 if( $field->get_property( "required" ) ) { ... }
 

User Comments


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

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

User Comments


$xhtml = $field->render_value( $handle, $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


$out_list = $field->sort_values( $handle, $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


$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


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

Returns the XHTML representation of the value. If the field is multiple then $value should be a single item from the values, not the list.

User Comments


$values = $field->get_values( $handle, $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 $handle.

User Comments


$xhtml = $field->get_value_label( $handle, $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