Difference between revisions of "API:EPrints/MetaField"

From EPrints Documentation
Jump to: navigation, search
 
Line 6: Line 6:
 
<!-- Pod2Wiki=_private_ --><!-- Pod2Wiki=head_name -->
 
<!-- Pod2Wiki=_private_ --><!-- Pod2Wiki=head_name -->
 
==NAME==
 
==NAME==
−
'''EPrints::MetaField''' - A single metadata field.
+
EPrints::MetaField - A single metadata field.
  
−
<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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
−
</div>
 
 
<!-- Pod2Wiki=head_synopsis -->
 
<!-- Pod2Wiki=head_synopsis -->
 
==SYNOPSIS==
 
==SYNOPSIS==
−
my $field = $dataset-&gt;field( $fieldname );
+
<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>
  
−
$dataset = $field-&gt;dataset;
+
<!-- Edit below this comment -->
  
−
$repo = $field-&gt;repository;
 
  
−
$field-&gt;set_property( $property, $value );
+
<!-- Pod2Wiki= -->
 +
<!-- 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.
  
−
$value = $field-&gt;property( $property );
+
"type" is the most important property, it is the type of the metadata field. For example: "text", "name" or "date".
  
−
$name = $field-&gt;name;
+
A full description of metadata types and properties is in the eprints documentation and will not be duplicated here.
  
−
$type = $field-&gt;type;
+
<!-- Edit below this comment -->
  
−
$xhtml = $field-&gt;render_name;
 
  
−
$xhtml = $field-&gt;render_help;
+
<!-- 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!
  
−
$xhtml = $field-&gt;render_value_label( $value );
+
<!-- Edit below this comment -->
  
−
$values = $field-&gt;all_values( %opts );
 
  
−
$sorted_list = $field-&gt;sort_values( $unsorted_list );
+
<!-- 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>
  
 +
: Override the default rendering of values with a custom method. Renders $value (which may be a multiple) and returns an XHTML fragment.
  
−
<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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
−
</div>
+
<!-- Pod2Wiki=head_read_only_properties -->
−
<!-- Pod2Wiki=head_description -->
+
===Read-only Properties===
−
==DESCRIPTION==
+
* provenance =&gt; "core" or "config"
−
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.
+
: 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.
−
 
 
−
"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: #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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
−
</div>
 
 
<!-- Pod2Wiki=head_methods -->
 
<!-- Pod2Wiki=head_methods -->
 
==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%; '>
+
<!-- Pod2Wiki=head_set_property -->
−
<span style='display:none'>User Comments</span>
+
===set_property===
−
<!-- Edit below this comment -->
 
−
 
 
  
−
<!-- Pod2Wiki= -->
+
<source lang="perl">$field->set_property( $property, $value )
−
</div>
 
−
<!-- Pod2Wiki=item_set_property -->
 
−
===set_property===
 
  
−
$field-&gt;set_property( $property, $value )
+
</source>
 
Set the named property to the given value.
 
Set the named property to the given value.
  
Line 85: Line 93:
 
In these cases a cloned version of the field should be used.
 
In these cases a cloned version of the field should be used.
  
−
<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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
−
</div>
+
<!-- Pod2Wiki=head_repository -->
−
<!-- Pod2Wiki=item_repository -->
 
 
===repository===
 
===repository===
  
−
$repository = $field-&gt;repository
+
<source lang="perl">$repository = $field->repository
 +
 
 +
</source>
 
Return the [[API:EPrints/Repository|EPrints::Repository]] to which this field belongs.
 
Return the [[API:EPrints/Repository|EPrints::Repository]] to which this field belongs.
  
−
<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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
−
</div>
+
<!-- Pod2Wiki=head_dataset -->
−
<!-- Pod2Wiki=item_dataset -->
 
 
===dataset===
 
===dataset===
  
−
$dataset = $field-&gt;dataset
+
<source lang="perl">$dataset = $field->dataset
 +
 
 +
</source>
 
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.
  
−
<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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
−
</div>
+
<!-- Pod2Wiki=head_render_name -->
−
<!-- Pod2Wiki=item_render_name -->
 
 
===render_name===
 
===render_name===
  
−
$xhtml = $field-&gt;render_name
+
<source lang="perl">$xhtml = $field->render_name
 +
 
 +
</source>
 
Render the name of this field as an XHTML object.
 
Render the name of this field as an XHTML object.
  
−
<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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
−
</div>
+
<!-- Pod2Wiki=head_render_help -->
−
<!-- Pod2Wiki=item_render_help -->
 
 
===render_help===
 
===render_help===
  
−
$xhtml = $field-&gt;render_help
+
<source lang="perl">$xhtml = $field->render_help
 +
 
 +
</source>
 
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.
  
−
<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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
−
</div>
+
<!-- Pod2Wiki=head_name -->
−
<!-- Pod2Wiki=item_name -->
 
 
===name===
 
===name===
  
−
$name = $field-&gt;name
+
<source lang="perl">$name = $field->name
 +
 
 +
</source>
 
Return the name of this field.
 
Return the name of this field.
  
−
<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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
−
</div>
+
<!-- Pod2Wiki=head_type -->
−
<!-- Pod2Wiki=item_type -->
 
 
===type===
 
===type===
  
−
$type = $field-&gt;type
+
<source lang="perl">$type = $field->type
 +
 
 +
</source>
 
Return the type of this field.
 
Return the type of this field.
  
−
<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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
−
</div>
+
<!-- Pod2Wiki=head_property -->
−
<!-- Pod2Wiki=item_property -->
 
 
===property===
 
===property===
  
−
$value = $field-&gt;property( $property )
+
<source lang="perl">$value = $field->property( $property )
 +
 
 +
</source>
 
Return the value of the given 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.
 
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.
  
−
<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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
−
</div>
+
<!-- Pod2Wiki=head_sort_values -->
−
<!-- Pod2Wiki=item_sort_values -->
 
 
===sort_values===
 
===sort_values===
  
−
$out_list = $field-&gt;sort_values( $in_list, $langid )
+
<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.
  
−
<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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
−
</div>
+
<!-- Pod2Wiki=head_all_values -->
−
<!-- Pod2Wiki=item_all_values -->
 
 
===all_values===
 
===all_values===
  
−
$values = $field-&gt;all_values( %opts )
+
<source lang="perl">$values = $field->all_values( %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 current session.
 
Results are sorted according to the ordervalues of the current session.
  
−
<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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
−
</div>
+
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki=head_copyright -->
 
<!-- Pod2Wiki=head_copyright -->
 
==COPYRIGHT==
 
==COPYRIGHT==
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
Copyright 2000-2011 University of Southampton.
−
<span style='display:none'>User Comments</span>
+
 
 +
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/.
 +
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
−
</div>
+
<!-- Pod2Wiki=_postamble_ -->
−
<!-- Pod2Wiki=_postamble_ --><!-- Edit below this comment -->
+
<!-- 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’