Difference between revisions of "API:EPrints/DataObj"

From EPrints Documentation
Jump to: navigation, search
 
(36 intermediate revisions by 5 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.4 source. Any wiki changes made between the 'Pod2Wiki=*' and 'Edit below this comment' comments will be lost.
  -->[[Category:API|DataObj]]<!-- End of Pod2Wiki -->
+
  -->{{API}}{{Pod2Wiki}}{{API:Source|file=EPrints/DataObj.pm|package_name=EPrints::DataObj}}[[Category:API|DATAOBJ]][[Category:API:EPrints/DataObj|DATAOBJ]]<div><!-- Edit below this comment -->
<!-- Pod2Wiki=head_name -->'''EPrints::DataObj''' - Base class for records in EPrints.
 
__TOC__
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=head_description -->=DESCRIPTION=
 
This module is a base class which is inherited by [[API:EPrints/DataObj/EPrint|EPrints::DataObj::EPrint]],[[API:EPrints/User|EPrints::User]], [[API:EPrints/DataObj/Subject|EPrints::DataObj::Subject]] and[[API:EPrints/DataObj/Document|EPrints::DataObj::Document]] and several other classes.
 
It is ABSTRACT - its methods should not be called directly.
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_system_field_info -->==get_system_field_info==
 
  
  $sys_fields = EPrints::DataObj-&gt;get_system_field_info
 
  
Return an array describing the system metadata of the this dataset.
+
<!-- Pod2Wiki=_private_ --><!-- Pod2Wiki=head_name -->
<!-- End of Pod2Wiki -->
+
==NAME==
<!-- Pod2Wiki=item_new -->==new==
+
'''EPrints::DataObj''' - Base class for records in EPrints.
  
  $dataobj = EPrints::DataObj-&gt;new( $session, $id [, $dataset] )
+
<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_description -->
 +
==DESCRIPTION==
 +
This is a base class that is inherited by [[API:EPrints/DataObj/EPrint|EPrints::DataObj::EPrint]], [[API:EPrints/DataObj/User|EPrints::DataObj::User]], [[API:EPrints/DataObj/Subject|EPrints::DataObj::Subject]] and [[API:EPrints/DataObj/Document|EPrints::DataObj::Document]] and various other classes representing data objects.
 +
 +
This class is abstract and its methods should not be called directly.
 +
 +
<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_synopsis -->
 +
===Synopsis===
 +
$dataobj = $dataset-&gt;dataobj( $id );
 +
$dataobj-&gt;delete;
 +
$dataobj-&gt;commit( $force );
 +
$dataset = $dataobj-&gt;dataset;
 +
$repo = $dataobj-&gt;repository;
 +
$id = $dataobj-&gt;id;
 +
$dataobj-&gt;set_value( $fieldname, $value );
 +
$value = $dataobj-&gt;value( $fieldname );
 +
\@value = $dataobj-&gt;value( $fieldname ); # multiple
 +
$boolean = $dataobj-&gt;is_set( $fieldname );
 +
$xhtml = $dataobj-&gt;render_value( $fieldname );
 +
$xhtml = $dataobj-&gt;render_citation( $style, %opts );
 +
$uri = $dataobj-&gt;uri;
 +
$string = $dataobj-&gt;export( $plugin_id, %opts );
 +
$dataobj = $dataobj-&gt;create_subobject( $fieldname, $epdata );
 +
 
 +
<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_core_metadata_fields -->
 +
==CORE METADATA FIELDS==
 +
None. This is an abstract class from which real data objects  inherit and then add their metadata fields.
 +
 +
<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_references_and_related_objects -->
 +
==REFERENCES AND RELATED OBJECTS==
 +
None. This is an abstract class from which real data objects inherit and then add their references and related objects.
 +
 +
<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_instance_variables -->
 +
==INSTANCE VARIABLES==
 +
<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=item_$self->{changed} -->
 +
===$self-&gt;{changed}===
 +
 +
A reference to a hash containing the old values of metadata that has changed since his the data object was last committed.
 +
 +
<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=item_$self->{data} -->
 +
===$self-&gt;{data}===
 +
 +
A reference to a hash containing the metadata of this record.
 +
 +
<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=item_$self->{dataset} -->
 +
===$self-&gt;{dataset}===
 +
 +
The [[API:EPrints/DataSet|EPrints::DataSet]] to which this record 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 -->
 +
 +
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_$self->{non_volatile_change} -->
 +
===$self-&gt;{non_volatile_change}===
 +
 +
A boolean signifying whether the current changes include at least one change to a non-volatile 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 -->
 +
 +
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_$self->{session} -->
 +
===$self-&gt;{session}===
 +
 +
The current [[API:EPrints/Repository|EPrints::Repository]]. This use to be [[API:EPrints/Session|EPrints::Session]] but was replaced in later versions. See [[API:EPrints/BackCompatibility|EPrints::BackCompatibility]].
 +
 +
<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=item_$self->{under_construction} -->
 +
===$self-&gt;{under_construction}===
 +
 +
A boolean signifying if the data object is currently under construction and therefore know house-keeping should be carried out on the data object whilst set.
 +
 +
<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%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 +
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=head_constructor_methods -->
 +
===Constructor Methods===
 +
<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=item_new -->
 +
====new====
 +
 +
$dataobj = EPrints::DataObj-&gt;new( $session, $id, [ $dataset ] )
 
Return new data object, created by loading it from the database.
 
Return new data object, created by loading it from the database.
If $dataset is not defined uses the default dataset for this object.
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_new_from_data -->==new_from_data==
 
  
  $dataobj = EPrints::DataObj-&gt;new_from_data( $session, $data [, $dataset ] )
+
If <tt>$dataset</tt> is not defined uses the default dataset for this 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 -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_new_from_data -->
 +
====new_from_data====
 +
 
 +
$dataobj = EPrints::DataObj-&gt;new_from_data( $session, $data, [ $dataset ] )
 +
Construct and and returns a new data object based on the <tt>$data</tt> hash reference of metadata.
 +
 
 +
This is usually called by [[API:EPrints/DataObj#create_from_data|create_from_data]] to ensure default values are set for those field values not initially included in <tt>$data</tt> before this method constructs the data object.
 +
 
 +
<tt>$dataset</tt> is determined from the class if not provided.
 +
 
 +
<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=item_create -->
 +
====create====
 +
 
 +
$dataobj = EPrints::DataObj::create( $session, @default_data )
 +
ABSTRACT
 +
 
 +
Create a new object of this type in the database.
 +
 
 +
The syntax for <tt>@default_data</tt> depends on the type of data 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 -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_create_from_data -->
 +
====create_from_data====
 +
 
 +
$dataobj = EPrints::DataObj-&gt;create_from_data( $session, $data, [ $dataset ] )
 +
Creates and returns a new data object of this type in the database.
 +
 
 +
<tt>$data</tt> is a structured hash reference with multiple dimensions to encompass compound, multiple and sub-object field values.
 +
 
 +
<tt>$dataset</tt> is the dataset to which the new data object will belong. If this is not defined, it is determined from the class.
 +
 
 +
This will pull in defaults for unset field values in <tt>$data</tt> before calling [[API:EPrints/DataObj#new_from_data|new_from_data]]. It will also create any sub-objects as well as the main object.
 +
 
 +
Call this via:
 +
 
 +
$dataset-&gt;create_object( $session, $data )
 +
 
 +
<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_class_methods -->
 +
===Class Methods===
 +
<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=item_get_system_field_info -->
 +
====get_system_field_info====
 +
 
 +
$sys_fields = EPrints::DataObj-&gt;get_system_field_info
 +
Return an array describing the system metadata of the this  dataset.
 +
 
 +
<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=item_get_defaults -->
 +
====get_defaults====
 +
 
 +
$defaults = EPrints::DataObj-&gt;get_defaults( $session, $data, [ $dataset ] )
 +
Return default values for this object based on the starting <tt>$data</tt>. Uses the data object class to determine dataset if <tt>$dataset</tt> not set.
 +
 
 +
Should be subclassed.
 +
 
 +
<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=item_get_dataset_id -->
 +
====get_dataset_id====
 +
 
 +
$dataset = EPrints::DataObj-&gt;get_dataset_id
 +
Returns the ID of the [[API:EPrints/DataSet|EPrints::DataSet]] object to which this record 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 -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_xml_to_epdata -->
 +
====xml_to_epdata====
 +
 
 +
$epdata = EPrints::DataObj-&gt;xml_to_epdata( $session, $xml, %opts )
 +
Populates <tt>$epdata</tt> based on <tt>$xml</tt> using options in <tt>%opts</tt>. This is the inverse of [[API:EPrints/DataObj#to_xml|to_xml]] but doesn't create a new 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 -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_export_fieldlist -->
 +
====export_fieldlist====
 +
 
 +
EPrints::DataObj-&gt;export_fieldlist
 +
Returns fields to be exported by plugins that do not have pre-defined fields to export, (e.g. {{API:PodLink|file=Export/XML|package_name=Export::XML|section=|text=Export::XML}}).
 +
 
 +
<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=item_in_export_fieldlist -->
 +
====in_export_fieldlist====
 +
 
 +
EPrints::DataObj-&gt;in_export_fieldlist
 +
Returns whether a field is in the export fieldlist for a particular data object.  Returns <tt>true</tt> if there is no fieldlist restriction.
 +
 
 +
<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=item_start_element -->
 +
====start_element====
 +
 
 +
EPrints::DataObj-&gt;start_element( $data, $epdata, $state )
 +
Consumes a SAX event.
 +
 
 +
<tt>$data</tt> is the SAX node data.
 +
 
 +
<tt>$epdata</tt> is an EPrints data structure to write values to.
 +
 
 +
<tt>$state</tt> maintains state between SAX calls but must contain at least:
 +
 
 +
    dataset - the dataset the class belongs to
 +
 
 +
<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=item_end_element -->
 +
====end_element====
 +
 
 +
EPrints::DataObj-&gt;end_element( $data, $epdata, $state )
 +
Ends element from [[API:EPrints/DataObj#start_element|start_element]].
 +
 
 +
<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=item_characters -->
 +
====characters====
 +
 
 +
EPrints::DataObj-&gt;characters( $data, $epdata, $state )
 +
Consumes characters within [[API:EPrints/DataObj#start_element|start_element]].
 +
 
 +
<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_object_methods -->
 +
===Object Methods===
 +
<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=item_clone -->
 +
====clone====
 +
 
 +
$clone = $dataobj-&gt;clone
 +
Clone the current data object, by creating a new data object of the same type and metadata but a new ID.
 +
 
 +
<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=item_create_subdataobj -->
 +
====create_subdataobj====
 +
 
 +
$subdataobj = $dataobj-&gt;create_subdataobj( $fieldname, $epdata )
 +
Creates and returns a new data object that is a sub-object of this  object in field <tt>$fieldname</tt> with initial data <tt>$epdata</tt>.
 +
 
 +
Clears the sub-object cache for this <tt>$fieldname</tt> which is equivalent  to:
 +
 
 +
$dataobj-&gt;set_value( $fieldname, 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 -->
 +
 
  
Construct a new EPrints::DataObj object based on the $data hash reference of metadata.
+
<!-- Pod2Wiki= -->
Used to create an object from the data retrieved from the database.
+
</div>
<!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki=item_local_path -->
<!-- Pod2Wiki=item_get_defaults -->==get_defaults==
+
====local_path====
  
  $defaults = EPrints::User-&gt;get_defaults( $session, $data, $dataset )
+
$local_path = $dataobj-&gt;local_path
 +
Return local_path string for the history of the data object.
  
Return default values for this object based on the starting data.
 
 
Should be subclassed.
 
Should be subclassed.
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_remove -->==remove==
 
  
  $success = $dataobj-&gt;remove
+
<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=item_update_triggers -->
 +
====update_triggers====
 +
 
 +
$dataobj-&gt;update_triggers
 +
Update all the stuff that needs to be updated before the data object  is written to the database.
 +
 
 +
<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=item_delete -->
 +
====delete====
 +
 
 +
$success = $dataobj-&gt;delete
 +
Delete this data object from the database and any sub-objects or  related files.
 +
 
 +
Alias for:
 +
 +
$dataobj-&gt;remove
 +
 
 +
Return <tt>true</tt> if successful.
 +
 
 +
<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=item_empty -->
 +
====empty====
 +
 
 +
$dataobj-&gt;empty
 +
Remove all of this object's values that may be imported.
 +
 
 +
<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=item_update -->
 +
====update====
 +
 
 +
$dataobj-&gt;update( $epdata [, %opts ] )
 +
Update this object's values from $epdata. Ignores any values that do not exist in the dataset or do not have the 'import' property set.
 +
 
 +
  include_subdataobjs - replace sub-dataobjs if given
 +
 
 +
  # replaces all documents in $dataobj
 +
  $dataobj-&gt;update( {
 +
    title =&gt; "Wombats on Fire",
 +
    documents =&gt; [{
 +
      main =&gt; "wombat.pdf",
 +
      ...
 +
    }],
 +
  }, include_subdataobjs =&gt; 1 );
 +
 
 +
<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=item_set_under_construction -->
 +
====set_under_construction====
  
Remove this data object from the database and any sub-objects or related files.  
+
$dataobj-&gt;set_under_construction( $boolean )
Return true if successful.
+
Set a flag to indicate this object is being constructed and any house  keeping will be handled by the method constructing it so don't do it  elsewhere.
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_clear_changed -->==clear_changed==
 
  
  $dataobj-&gt;clear_changed( )
+
<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 -->
  
Clear any changed fields, which will result in them not being committed unlessforce is used.
 
This method is used by the Database to avoid unnecessary commits.
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_commit -->==commit==
 
  
  $success = $dataobj-&gt;commit( [$force] )
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_under_construction -->
 +
====under_construction====
  
 +
$boolean = $dataobj-&gt;under_construction
 +
Returns c&lt;true&gt; if this object is part way through being constructed.
 +
 +
<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=item_clear_changed -->
 +
====clear_changed====
 +
 +
$dataobj-&gt;clear_changed
 +
Clear any changed fields, which will result in them not being  committed unless force is used.
 +
 +
This method is used by the [[API:EPrints/Database|EPrints::Database]] to avoid unnecessary  commits.
 +
 +
<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=item_clear_citationcaches -->
 +
====clear_citationcaches====
 +
 +
$dataobj-&gt;clear_citationcaches
 +
Clear any [[API:EPrints/DataObj/CitationCache|EPrints::DataObj::CitationCache]] objects associated with  the data 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 -->
 +
 +
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_commit -->
 +
====commit====
 +
 +
$success = $dataobj-&gt;commit( [ $force ] )
 
Write this object to the database and reset the changed fields.
 
Write this object to the database and reset the changed fields.
If $force isn't true then it only actually modifies the databaseif one or more fields have been changed.
 
Commit may also queue indexer jobs or log changes, depending on the object.
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_value -->==get_value==
 
  
  $value = $dataobj-&gt;get_value( $fieldname )
+
If <tt>$force</tt> isn't true then it only actually modifies the database if  one or more fields have been changed.
  
Get a the value of a metadata field. If the field is not set then it returnsundef unless the field has the property multiple set, in which case it returns [] (a reference to an empty array).
+
Commit may also queue indexer jobs or log changes, depending on the object.
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_set_value -->==set_value==
 
  
  $dataobj-&gt;set_value( $fieldname, $value )
+
<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 -->
  
Set the value of the named metadata field in this record.
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_values -->==get_values==
 
  
  @values = $dataobj-&gt;get_values( $fieldnames )
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_value -->
 +
====value====
  
Returns a list of all the values in this record of all the fields specifiedby $fieldnames. $fieldnames should be in the format used by browse views - slashseperated fieldnames with an optional .id suffix to indicate the id part ratherthan the main part.
+
$value = $dataobj-&gt;value( $fieldname )
For example "author.id/editor.id" would return a list of all author and editorids from this record.
+
Get a the value of a metadata field with <tt>$fieldname</tt>. If the field  is not set then it returns undef unless the field has the property  multiple set, in which case it returns [] (a reference to an empty a rray).
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_session -->==get_session==
 
  
  $session = $dataobj-&gt;get_session
+
Alias for:
  
Returns the EPrints::Session object to which this record belongs.
+
$dataobj-&gt;get_value( $fieldname )
<!-- End of Pod2Wiki -->
+
 
<!-- Pod2Wiki=item_get_data -->==get_data==
+
<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 -->
  
  $data = $dataobj-&gt;get_data
 
  
Returns a reference to the hash table of all the metadata for this record keyed by fieldname.
+
<!-- Pod2Wiki= -->
<!-- End of Pod2Wiki -->
+
</div>
<!-- Pod2Wiki=item_get_dataset_id -->==get_dataset_id==
+
<!-- Pod2Wiki=item_set_value -->
 +
====set_value====
  
  $dataset = EPrints::DataObj-&gt;get_dataset_id
+
$dataobj-&gt;set_value( $fieldname, $value )
 +
Set the <tt>$value</tt> of the named metadata field <tt>$fieldname</tt> for this data object.
  
Returns the id of the [[API:EPrints/DataSet|EPrints::DataSet]] object to which this record belongs.
+
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<!-- End of Pod2Wiki -->
+
<span style='display:none'>User Comments</span>
<!-- Pod2Wiki=item_get_dataset -->==get_dataset==
+
<!-- Edit below this comment -->
  
  $dataset = $dataobj-&gt;get_dataset
 
  
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_set_value_raw -->
 +
====set_value_raw====
 +
 +
$dataobj-&gt;set_value_raw( $fieldname, $value )
 +
Set the <tt>$value</tt> of the named metadata field <tt>$fieldname</tt> for this data object by directly modifying its <tt>data</tt> hash reference. Use  with care!
 +
 +
<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=item_get_values -->
 +
====get_values====
 +
 +
@values = $dataobj-&gt;get_values( $fieldnames )
 +
Returns a list of all the values in this record of all the $fields  specified by <tt>$fieldnames</tt>. These should be in the format used by  browse views, using <tt>/</tt> to seperate individual field names with an  optional <tt>.id</tt> suffix to indicate the ID part rather than the main  part.
 +
 +
E.g. <tt>author.id/editor.id</tt> would return a list of all author and  editor IDs from this record.
 +
 +
<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=item_repository -->
 +
====repository====
 +
 +
$session = $dataobj-&gt;repository
 +
Returns the [[API:EPrints/Repository|EPrints::Repository]] object to which this record  belongs.
 +
 +
Alias for:
 +
 +
$dataobj-&gt;get_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 -->
 +
 +
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_get_data -->
 +
====get_data====
 +
 +
$data = $dataobj-&gt;get_data
 +
Returns a reference to the hash of all the metadata for this record  keyed by fieldname.
 +
 +
<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=item_get_dataset -->
 +
====get_dataset====
 +
 +
$dataset = $dataobj-&gt;get_dataset
 
Returns the [[API:EPrints/DataSet|EPrints::DataSet]] object to which this record belongs.
 
Returns the [[API:EPrints/DataSet|EPrints::DataSet]] object to which this record belongs.
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_is_set -->==is_set==
 
  
  $bool = $dataobj-&gt;is_set( $fieldname )
+
<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=item_is_set -->
 +
====is_set====
 +
 
 +
$boolean = $dataobj-&gt;is_set( $fieldname )
 +
Returns <tt>true</tt> if the field with <tt>$fieldname</tt> is set in this record,  otherwise <tt>false</tt>.
 +
 
 +
Warns if the field with <tt>$fieldname</tt> does not exist.
 +
 
 +
<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 -->
 +
 
  
Returns true if the named field is set in this record, otherwise false.
+
<!-- Pod2Wiki= -->
Warns if the field does not exist.
+
</div>
<!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki=item_exists_and_set -->
<!-- Pod2Wiki=item_exists_and_set -->==exists_and_set==
+
====exists_and_set====
  
  $bool = $dataobj-&gt;exists_and_set( $fieldname )
+
$boolean = $dataobj-&gt;exists_and_set( $fieldname )
 +
Returns <tt>true</tt> if the field with <tt>$fieldname</tt> is set in this record,  otherwise <tt>false</tt>.
  
Returns true if the named field is set in this record, otherwise false.
+
If the field does not exist, just return <tt>false</tt>.
If the field does not exist, just return false.
 
This method is useful for plugins which may operate on multiple repositories, and the fact a field does not exist is not an issue.
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_id -->==get_id==
 
  
  $id = $dataobj-&gt;get_id
+
This method is useful for plugins which may operate on multiple  repositories, when field not existing is not an issue for a particular repository.
  
 +
<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=item_id -->
 +
====id====
 +
 +
$id = $dataobj-&gt;id
 
Returns the value of the primary key of this record.
 
Returns the value of the primary key of this record.
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_gid -->==get_gid==
 
  
  $id = $dataobj-&gt;get_gid
+
Alias for:
  
DEPRECATED (see uri())
+
$dataobj-&gt;get_id
Returns the globally referential fully-qualified identifier for this object orundef if this object can not be externally referenced.
+
 
<!-- End of Pod2Wiki -->
+
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<!-- Pod2Wiki=item_get_datestamp -->==get_datestamp==
+
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
  
  $datestamp = $dataobj-&gt;get_datestamp
 
  
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_get_gid -->
 +
====get_gid====
 +
 +
$gid = $dataobj-&gt;get_gid
 +
DEPRECATED (see [[API:EPrints/DataObj#uri|uri]])
 +
 +
Returns the globally referential fully-qualified identifier for this  data object or <tt>undef</tt> if this object can not be externally  referenced.
 +
 +
<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=item_get_datestamp -->
 +
====get_datestamp====
 +
 +
$datestamp = $dataobj-&gt;get_datestamp
 
Returns the datestamp of this object in "YYYY-MM-DD hh:mm:ss" format.
 
Returns the datestamp of this object in "YYYY-MM-DD hh:mm:ss" format.
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_value -->==render_value==
 
  
  $xhtml = $dataobj-&gt;render_value( $fieldname, [$showall] )
+
<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=item_render_value -->
 +
====render_value====
 +
 
 +
$xhtml = $dataobj-&gt;render_value( $fieldname, [ $showall ] )
 +
Returns the rendered version of the value of the given <tt>$fieldname</tt>  as appropriate for the current session. If <tt>$showall</tt> is <tt>true</tt> then  all values are rendered - this is usually used for staff viewing data.
 +
 
 +
<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=item_render_citation -->
 +
====render_citation====
 +
 
 +
$xhtml = $dataobj-&gt;render_citation( [ $style, %params ] )
 +
Renders the record as a citation. If $style is set then it uses that  citation style from the citations config file. Otherwise <tt>$style</tt> defaults to the type of this record. If <tt>$params{url}</tt> is set then  the citation will link to the specified URL.
 +
 
 +
If <tt>$style</tt> is unset then use <tt>default</tt>.
 +
 
 +
<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=item_render_citation_link -->
 +
====render_citation_link====
 +
 
 +
$xhtml = $dataobj-&gt;render_citation_link( [ $style, %params ] )
 +
Renders a citation as like [[API:EPrints/DataObj#render_citation|render_citation]] but as a link to the  URL for this item. E.g. the abstract page of an eprint.
 +
 
 +
<tt>$params{url}</tt> is set to data object's URL if not set.
 +
 
 +
<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=item_render_citation_link -->
 +
====render_citation_link====
 +
 
 +
$xhtml = $dataobj-&gt;render_citation_link( [ $style, %params ] )
 +
Renders a citation as like [[API:EPrints/DataObj#render_citation|render_citation]] but as a link to the control URL for this item. E.g. for items that are not yet in the live archive.
 +
 
 +
<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=item_render_description -->
 +
====render_description====
 +
 
 +
$xhtml = $dataobj-&gt;render_description
 +
Returns a short description of this object using the <tt>brief</tt> citation  style for this dataset or the <tt>default</tt> citation style of the former does not exist.
 +
 
 +
<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=item_render -->
 +
====render====
 +
 
 +
( $xhtml, $title ) = $dataobj-&gt;render
 +
Return a chunk of XHTML DOM describing this object in the normal way. This is the public view of the record, not the staff view.
 +
 
 +
<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=item_render_full -->
 +
====render_full====
 +
 
 +
$xhtml = $dataobj-&gt;render_full
 +
Return an XHTML table in DOM describing this record. All values of all fields are listed. This is the staff view.
  
Returns the rendered version of the value of the given field, as appropriatefor the current session. If $showall is true then all values are rendered - this is usually used for staff viewing data.
+
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<!-- End of Pod2Wiki -->
+
<span style='display:none'>User Comments</span>
<!-- Pod2Wiki=item_render_citation -->==render_citation==
+
<!-- Edit below this comment -->
  
  $xhtml = $dataobj-&gt;render_citation( [$style], [%params] )
 
  
Renders the record as a citation. If $style is set then it uses that citationstyle from the citations config file. Otherwise $style defaults to the typeof this record. If $params{url} is set then the citiation will link to the specifiedURL.
+
<!-- Pod2Wiki= -->
<!-- End of Pod2Wiki -->
+
</div>
<!-- Pod2Wiki=item_render_citation_link -->==render_citation_link==
+
<!-- Pod2Wiki=item_render_export_links -->
 +
====render_export_links====
  
  $xhtml = $dataobj-&gt;render_citation_link( [$style], %params )
+
$xhtml_ul_list = $dataobj-&gt;render_export_links( [ $staff ] )
 +
Return a <tt>&lt;ul&gt;</tt> list containing links to all the formats this  eprint is available in.
  
Renders a citation (as above) but as a link to the URL for this item. Forexample - the abstract page of an eprint.  
+
If <tt>$staff</tt> is <tt>true</tt> then show all formats available to staff and  link to the staff export URL.
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_description -->==render_description==
 
  
  $xhtml = $dataobj-&gt;render_description
+
<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 -->
  
Returns a short description of this object using the default citation stylefor this dataset.
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render -->==render==
 
  
  ($xhtml, $title ) = $dataobj-&gt;render
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_render_export_bar -->
 +
====render_export_bar====
  
Return a chunk of XHTML DOM describing this object in the normal way.This is the public view of the record, not the staff view.
+
$xhtml = $dataobj-&gt;render_export_bar( [ $staff ] )
<!-- End of Pod2Wiki -->
+
Returns a rendered drop-down list of exports. 
<!-- Pod2Wiki=item_render_full -->==render_full==
 
  
  ($xhtml, $title ) = $dataobj-&gt;render_full
+
If <tt>$staff</tt> is <tt>true</tt> then include both public and staff visible  export options.
  
Return an XHTML table in DOM describing this record. All values ofall fields are listed. This is the staff view.
+
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<!-- End of Pod2Wiki -->
+
<span style='display:none'>User Comments</span>
<!-- Pod2Wiki=item_uri -->==uri==
+
<!-- Edit below this comment -->
  
  $url = $dataobj-&gt;uri
 
  
Returns a unique URI for this object. Not certain to resolve as a URL.
+
<!-- Pod2Wiki= -->
If $c-&gt;{dataobj_uri}-&gt;{eprint} is a function, call that to work it out.
+
</div>
<!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki=item_uri -->
<!-- Pod2Wiki=item_internal_uri -->==internal_uri==
+
====uri====
  
  $uri = $dataobj-&gt;internal_uri()
+
$url = $dataobj-&gt;uri
 +
Returns a unique URI for this object. Not certain to resolve as a  URL.
  
 +
If <tt>$c-</tt>{dataobj_uri}-&gt;{eprint}&gt; is a function, call that to work  it out.
 +
 +
<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=item_internal_uri -->
 +
====internal_uri====
 +
 +
$uri = $dataobj-&gt;internal_uri
 
Return an internal URI for this object (independent of repository hostname).
 
Return an internal URI for this object (independent of repository hostname).
To retrieve an object by internal URI use [[API:EPrints/DataSet|EPrints::DataSet]]::get_object_from_uri().
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_url -->==get_url==
 
  
  $url = $dataobj-&gt;get_url
+
To retrieve an object by internal URI use  [[API:EPrints/DataSet|EPrints::DataSet]]::get_object_from_uri().
  
Returns the URL for this record, for example the URL of the abstract pageof an eprint.
+
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<!-- End of Pod2Wiki -->
+
<span style='display:none'>User Comments</span>
<!-- Pod2Wiki=item_get_control_url -->==get_control_url==
+
<!-- Edit below this comment -->
  
  $url = $dataobj-&gt;get_control_url
 
  
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_path -->
 +
====path====
 +
 +
$path = $dataobj-&gt;path
 +
Returns the relative path to this object from the repository's base  URL, if the object has a URL.
 +
 +
Does not include any leading slash.
 +
 +
<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=item_url -->
 +
====url====
 +
 +
$url = $dataobj-&gt;url
 +
Returns the URL for this record, e.g.the URL of the abstract page of  an eprint.
 +
 +
Alias for:
 +
 +
$dataobj-&gt;get_url
 +
 
 +
<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=item_get_control_url -->
 +
====get_control_url====
 +
 +
$url = $dataobj-&gt;get_control_url
 
Returns the URL for the control page for this object.  
 
Returns the URL for the control page for this object.  
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_type -->==get_type==
 
  
  $type = $dataobj-&gt;get_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 -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_get_type -->
 +
====get_type====
 +
 
 +
$type = $dataobj-&gt;get_type
 +
ABSTRACT.
 +
 
 +
Returns the type of this data object. This not the dataset it belongs to but the specific type within the dataset (e.g. c&lt;user&gt; could be <tt>editor</tt>, <tt>admin</tt>, etc.).
  
Returns the type of this record - type of user, type of eprint etc.
+
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<!-- End of Pod2Wiki -->
+
<span style='display:none'>User Comments</span>
<!-- Pod2Wiki=item_to_xml -->==to_xml==
+
<!-- Edit below this comment -->
  
  $xmlfragment = $dataobj-&gt;to_xml( %opts )
 
  
Convert this object into an XML fragment.
+
<!-- Pod2Wiki= -->
%opts are:
+
</div>
no_xmlns=&gt;1 : do not include a xmlns attribute in the outer element. (This assumes this chunk appears in a larger tree where the xmlns is already set correctly.
+
<!-- Pod2Wiki=item_to_xml -->
showempty=&gt;1 : fields with no value are shown.
+
====to_xml====
version=&gt;"code" : pick what version of the EPrints XML formatto use "1" or "2"
 
embed=&gt;1 : include the data of a file, not just it's URL.
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_xml_to_epdata -->==xml_to_epdata==
 
  
  $epdata = EPrints::DataObj-&gt;xml_to_epdata( $session, $xml, %opts )
+
$xmlfragment = $dataobj-&gt;to_xml( %opts )
 +
Convert this object into an XML fragment using options <tt>%opts</tt>.
  
Populates $epdata based on $xml. This is the inverse of to_xml() but doesn't create a new object.
+
Options:
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_export -->==export==
 
  
   $plugin_output = $detaobj-&gt;export( $plugin_id, %params )
+
no_xmlns - Do not include a xmlns attribute in the outer element.
 +
(This assumes this chunk appears in a larger tree where the xmlns is
 +
already set correctly.
 +
showempty - Fields with no value are shown.
 +
embed - Include the data of a file, not just it's URL.
 +
    
 +
<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 -->
  
Apply an output plugin to this items. Return the results.
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_queue_changes -->==queue_changes==
 
  
  $dataobj-&gt;queue_changes
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_to_sax -->
 +
====to_sax====
  
 +
$dataobj-&gt;to_sax( %opts )
 +
Stream this object to a SAX handler using the options in <tt>$opts</tt>.
 +
 +
Options:
 +
Handler - the SAX handler to build the output.
 +
revision_generation - Generate XML for revision files rather than
 +
export.
 +
 +
This does not output any document-level events.
 +
 +
<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=item_export -->
 +
====export====
 +
 +
$plugin_output = $dataobj-&gt;export( $plugin_id, %params )
 +
Apply an export plugin with <tt>$plugin_id</tt> to this data object, using  the parameters provided by <tt>%params</tt> and supplying them to the <tt>output_dataobj</tt> method of the [[API:EPrints/Plugin:Export|EPrints::Plugin:Export]] plugin.
 +
 +
Return the output of the export plugin.
 +
 +
<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=item_queue_changes -->
 +
====queue_changes====
 +
 +
$dataobj-&gt;queue_changes
 
Add all the changed fields into the indexers todo queue.
 
Add all the changed fields into the indexers todo queue.
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_queue_all -->==queue_all==
 
  
  $dataobj-&gt;queue_all
+
<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=item_queue_all -->
 +
====queue_all====
  
 +
$dataobj-&gt;queue_all
 
Add all the fields into the indexers todo queue.
 
Add all the fields into the indexers todo queue.
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_queue_fulltext -->==queue_fulltext==
 
  
  $dataobj-&gt;queue_fulltext
+
<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=item_queue_fulltext -->
 +
====queue_fulltext====
 +
 +
$dataobj-&gt;queue_fulltext
 
Add a fulltext index into the indexers todo queue.
 
Add a fulltext index into the indexers todo queue.
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_has_owner -->==has_owner==
 
  
  $boolean = $dataobj-&gt;has_owner( $user )
+
<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=item_queue_removed -->
 +
====queue_removed====
 +
 
 +
$dataobj-&gt;queue_removed
 +
Add an index removed event to the indexer's queue.
 +
 
 +
<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 -->
  
Return true if $user owns this record. Normally this means they created it, but a group of users could count as owners of the samerecord if you wanted.
 
It's false on most dataobjs, except those which override this method.
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_in_editorial_scope_of -->==in_editorial_scope_of==
 
  
  $boolean = $dataobj-&gt;in_editorial_scope_of( $user )
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_has_owner -->
 +
====has_owner====
  
As for has_owner, but if the user is identified as someone with aneditorial scope which includes this record.
+
$boolean = $dataobj-&gt;has_owner( $user )
Defaults to true. Which doesn't mean that they have the right to edit it, just that their scope matches. You also need editor rightsto use this. It's currently used just to filter eprint editors sothat only ones with a scope AND a priv can edit.
+
Return <tt>true</tt> if <tt>$user</tt> owns this record. Normally this means they created it, but a group of users could count as owners of the same record if you wanted.
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_validate -->==validate==
 
  
   $problems = $dataobj-&gt;validate( [ $for_archive ], $workflow_id )
+
It's <tt>false</tt> on most data objects, except those which override this  method.
 +
 
 +
<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=item_permit -->
 +
====permit====
 +
 
 +
$rc = $dataobj-&gt;permit( $priv, [ $user ] )
 +
  # current user can edit via editorial role
 +
  if( $dataobj-&gt;permit( "xxx/edit", $user ) &amp; 8 )
 +
  {
 +
    ...
 +
  }
 +
  # anyone can view this object
 +
  if( $dataobj-&gt;permit( "xxx/view" ) )
 +
  {
 +
  }
 +
 
 +
Returns <tt>true</tt> if the specified <tt>$user</tt> (or 'anybody') can perform  this action.
 +
 
 +
Returns a bit mask where:
 +
 
 +
  0 - not permitted
 +
  1 - anybody
 +
  2 - logged in user
 +
  4 - user as owner
 +
  8 - user as editor
 +
    
 +
See also [[API:EPrints/Repository#allow_anybody|EPrints::Repository/allow_anybody]] and  [[API:EPrints/DataObj/User#allow|EPrints::DataObj::User/allow]].
 +
 
 +
<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=item_in_editorial_scope_of -->
 +
====in_editorial_scope_of====
 +
 
 +
$boolean = $dataobj-&gt;in_editorial_scope_of( $user )
 +
As for [[API:EPrints/DataObj#has_owner|has_owner]], but if the <tt>$user</tt> is identified as someone  with an editorial scope which includes this record.
 +
 
 +
Defaults to <tt>true</tt>. Which doesn't mean that they have the right to  edit it, just that their scope matches. You also need editor rights to use this. It's currently used just to filter eprint editors so that only ones with appropriate scope and privilege can edit.
 +
 
 +
<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=item_validate -->
 +
====validate====
 +
 
 +
$problems = $dataobj-&gt;validate( $for_archive )
 +
Validate this data object. Not used on all sub-classed. <tt>$for_archive</tt>  being <tt>true</tt> indicates that the item is beting validated to go live.
 +
 
 +
Returns a reference to an array of XHTML DOM objects describing validation problems with the entire data object for the supplied  <tt>$for_archive</tt> archive ID.
  
Return a reference to an array of XHTML DOM objects describingvalidation problems with the entire $dataobj based on $workflow_id.
 
If $workflow_id is undefined defaults to "default".
 
 
A reference to an empty array indicates no problems.
 
A reference to an empty array indicates no problems.
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_warnings -->==get_warnings==
 
  
  $warnings = $dataobj-&gt;get_warnings( )
+
<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=item_get_warnings -->
 +
====get_warnings====
 +
 
 +
$warnings = $dataobj-&gt;get_warnings
 +
Returns a reference to an array of XHTML DOM objects describing problems with the entire data object.
  
Return a reference to an array of XHTML DOM objects describingproblems with the entire $dataobj.
 
 
A reference to an empty array indicates no problems.
 
A reference to an empty array indicates no problems.
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_add_stored_file -->==add_stored_file==
 
  
  $file = $dataobj-&gt;add_stored_file( $filename, $filehandle [, $filesize ] )
+
<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=item_validate_field -->
 +
====validate_field====
 +
 
 +
@problems = $dataobj-&gt;validate_field( $fieldname )
 +
Check if a field named <tt>$fieldname</tt> is valid.
 +
 
 +
Returns a reference to an array of XHTML problems. 
 +
 
 +
A reference to an empty array indicates no problems.
 +
 
 +
<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=item_tidy -->
 +
====tidy====
 +
 
 +
$dataobj-&gt;tidy
 +
Cleans up any multiple fields with gaps.
 +
 
 +
<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=item_add_stored_file -->
 +
====add_stored_file====
 +
 
 +
$file = $dataobj-&gt;add_stored_file( $filename, $filehandle, $filesize )
 +
Convenience method to add (or replace) the file record for  <tt>$filename</tt> to this object. Reads <tt>$filesize</tt> bytes from  <tt>$filehandle</tt>.
 +
 
 +
Returns the file object or <tt>undef</tt> if the storage failed.
 +
 
 +
<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=item_stored_file -->
 +
====stored_file====
 +
 
 +
$file = $dataobj-&gt;stored_file( $filename )
 +
Get the file object for <tt>$filename</tt>.
 +
 
 +
Returns the file object or <tt>undef</tt> if the file doesn't exist.
 +
 
 +
Has alias:
 +
 
 +
$dataobj-&gt;get_stored_file( $filename )
 +
 
 +
<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=item_add_dataobj_relations -->
 +
====add_dataobj_relations====
 +
 
 +
$dataobj-&gt;add_dataobj_relations( $target, %relations )
 +
Add a relation from this data object to the <tt>$target</tt> data object  using predicates defined in the keys of the <tt>%relations</tt> hash. If  values are defined in the hash reciprocal relationships from the  <tt>$target</tt> data object to this data object are also.
 +
 
 +
You must commit <tt>$target</tt> data object after calling this method.
 +
 
 +
Has alias:
 +
 
 +
$dataobj-&gt;add_object_relations( $target, %relations )
 +
 
 +
<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=item_has_dataobj_relations -->
 +
====has_dataobj_relations====
 +
 
 +
$boolean = $dataobj-&gt;has_dataobj_relations( $target, @required )
 +
Returns <tt>true</tt> if this object is related to <tt>$target</tt> by all  <tt>@required</tt>.
  
Convenience method to add the file record for $filename to this object. Reads data from $filehandle. If $filesize is defined it may used to determine where the file should be stored.
+
If <tt>@required</tt> is empty will return <tt>true</tt> if any relationships  exist.
Returns the file object or undef if the storage failed.
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_stored_file -->==get_stored_file==
 
  
  $file = $dataobj-&gt;get_stored_file( $filename )
+
Has alias:
  
Get the file object for $filename.
+
$dataobj-&gt;has_object_relations( $target, @required )
Returns the file object or undef if the file doesn't exist.
+
 
<!-- End of Pod2Wiki -->
+
<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_related_objects -->==Related Objects==
+
<span style='display:none'>User Comments</span>
<!-- End of Pod2Wiki -->
+
<!-- Edit below this comment -->
<!-- Pod2Wiki=item_add_object_relations -->===add_object_relations===
 
  
  $dataobj-&gt;add_object_relations( $target, $has =&gt; $is [, $has =&gt; $is ] )
 
  
Add a relation between this object and $target of type $has. If $is is defined will also add the reciprocal relationship $is from $target to this object. May be repeated to add multiple relationships.
+
<!-- Pod2Wiki= -->
You must commit $target after calling this method.
+
</div>
<!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki=item_has_related_dataobjs -->
<!-- Pod2Wiki=item_has_object_relations -->===has_object_relations===
+
====has_related_dataobjs====
  
  $bool = $dataobj-&gt;has_object_relations( $target, @types )
+
$boolean = $dataobj-&gt;has_related_dataobjs( @required )
 +
Returns <tt>true</tt> if [[API:EPrints/DataObj#related_dataobjs|related_dataobjs]] would return some objects but  without actually retrieving the related objects from the database.
  
Returns true if this object is related to $target by all @types.
+
Has alias:
If @types is empty will return true if any relationships exist.
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_has_related_objects -->===has_related_objects===
 
  
  $bool = $dataobj-&gt;has_related_objects( @types )
+
$dataobj-&gt;has_related_objects( @required )
 +
 
 +
<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 -->
  
Returns true if get_related_objects() would return some objects, but without actually retrieving the related objects from the database.
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_related_objects -->===get_related_objects===
 
  
  $dataobjs = $dataobj-&gt;get_related_objects( @types )
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_related_dataobjs -->
 +
====related_dataobjs====
  
Returns a list of objects related to this object by @types.
+
@dataobjs = $dataobj-&gt;related_dataobjs( @required )
<!-- End of Pod2Wiki -->
+
Returns a list of objects related to this data object by a relation in <tt>@required</tt>.
<!-- Pod2Wiki=item_remove_object_relations -->===remove_object_relations===
 
  
  $dataobj-&gt;remove_object_relations( $target [, $has =&gt; $is [, $has =&gt; $is ] )
+
Has alias:
  
Remove relations between this object and $target. If $has =&gt; $is pairs are defined will only remove those relationships given.
+
$dataobj-&gt;get_related_objects( @required )
You must commit $target after calling this method.
+
 
<!-- End of Pod2Wiki -->
+
<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_undocumented_methods -->=UNDOCUMENTED METHODS=
+
<span style='display:none'>User Comments</span>
{{API:Undocumented Methods}}<!-- End of Pod2Wiki -->
+
<!-- Edit below this comment -->
<!-- Pod2Wiki=item_clone -->==clone==
 
  
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_create -->==create==
 
  
<!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki= -->
<!-- Pod2Wiki=item_create_from_data -->==create_from_data==
+
</div>
 +
<!-- Pod2Wiki=item_remove_dataobj_relations -->
 +
====remove_dataobj_relations====
  
<!-- End of Pod2Wiki -->
+
$dataobj-&gt;remove_dataobj_relations( $target, %relations )
<!-- Pod2Wiki=item_get_value_raw -->==get_value_raw==
+
Remove relations between this data object and the <tt>$target</tt> data  object. If <tt>%relations</tt> is not empty only remove those relationships which are keys in this hash.
  
<!-- End of Pod2Wiki -->
+
You must [[API:EPrints/DataObj#commit|commit]] this object and <tt>$target</tt> to write the changes.
<!-- Pod2Wiki=item_render_citation_link_staff -->==render_citation_link_staff==
 
  
<!-- End of Pod2Wiki -->
+
Has alias:
<!-- Pod2Wiki=item_set_under_construction -->==set_under_construction==
+
$dataobj-&gt;remove_object_relations( $target, %relations )
  
<!-- End of Pod2Wiki -->
+
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<!-- Pod2Wiki=item_set_value_raw -->==set_value_raw==
+
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
  
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_tidy -->==tidy==
 
  
<!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki= -->
<!-- Pod2Wiki=item_under_construction -->==under_construction==
+
</div>
 +
<!-- Pod2Wiki=head_see_also -->
 +
==SEE ALSO==
 +
[[API:EPrints/DataSet|EPrints::DataSet]]
  
<!-- End of Pod2Wiki -->
+
<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 -->
  
$boolean = $dataobj->set_under_construction()
 
  
Returns true if this dataobj is under construction i.e. don't perform expensive maintenance processes on this object yet.
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=head_copyright -->
 +
==COPYRIGHT==
 +
{{API:Copyright}}
 +
<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=item_validate_field -->==validate_field==
 
  
<!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki= -->
<!-- Pod2Wiki=_postamble_ --><!-- End of Pod2Wiki -->
+
</div>
 +
<!-- Pod2Wiki=_postamble_ --><!-- Edit below this comment -->

Latest revision as of 16:41, 10 January 2022

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


Contents

NAME

EPrints::DataObj - Base class for records in EPrints.

User Comments


DESCRIPTION

This is a base class that is inherited by EPrints::DataObj::EPrint, EPrints::DataObj::User, EPrints::DataObj::Subject and EPrints::DataObj::Document and various other classes representing data objects.

This class is abstract and its methods should not be called directly.

User Comments


Synopsis

$dataobj = $dataset->dataobj( $id );
$dataobj->delete;
$dataobj->commit( $force );
$dataset = $dataobj->dataset;
$repo = $dataobj->repository;
$id = $dataobj->id;
$dataobj->set_value( $fieldname, $value );
$value = $dataobj->value( $fieldname );
\@value = $dataobj->value( $fieldname ); # multiple
$boolean = $dataobj->is_set( $fieldname );
$xhtml = $dataobj->render_value( $fieldname );
$xhtml = $dataobj->render_citation( $style, %opts );
$uri = $dataobj->uri;
$string = $dataobj->export( $plugin_id, %opts );
$dataobj = $dataobj->create_subobject( $fieldname, $epdata );
 

User Comments


CORE METADATA FIELDS

None. This is an abstract class from which real data objects inherit and then add their metadata fields.

User Comments


REFERENCES AND RELATED OBJECTS

None. This is an abstract class from which real data objects inherit and then add their references and related objects.

User Comments


INSTANCE VARIABLES

User Comments


$self->{changed}

A reference to a hash containing the old values of metadata that has changed since his the data object was last committed.

User Comments


$self->{data}

A reference to a hash containing the metadata of this record.

User Comments


$self->{dataset}

The EPrints::DataSet to which this record belongs.

User Comments


$self->{non_volatile_change}

A boolean signifying whether the current changes include at least one change to a non-volatile field.

User Comments


$self->{session}

The current EPrints::Repository. This use to be EPrints::Session but was replaced in later versions. See EPrints::BackCompatibility.

User Comments


$self->{under_construction}

A boolean signifying if the data object is currently under construction and therefore know house-keeping should be carried out on the data object whilst set.

User Comments


METHODS

User Comments


Constructor Methods

User Comments


new

$dataobj = EPrints::DataObj->new( $session, $id, [ $dataset ] )

Return new data object, created by loading it from the database.

If $dataset is not defined uses the default dataset for this object.

User Comments


new_from_data

$dataobj = EPrints::DataObj->new_from_data( $session, $data, [ $dataset ] )

Construct and and returns a new data object based on the $data hash reference of metadata.

This is usually called by create_from_data to ensure default values are set for those field values not initially included in $data before this method constructs the data object.

$dataset is determined from the class if not provided.

User Comments


create

$dataobj = EPrints::DataObj::create( $session, @default_data )

ABSTRACT

Create a new object of this type in the database.

The syntax for @default_data depends on the type of data object.

User Comments


create_from_data

$dataobj = EPrints::DataObj->create_from_data( $session, $data, [ $dataset ] )

Creates and returns a new data object of this type in the database.

$data is a structured hash reference with multiple dimensions to encompass compound, multiple and sub-object field values.

$dataset is the dataset to which the new data object will belong. If this is not defined, it is determined from the class.

This will pull in defaults for unset field values in $data before calling new_from_data. It will also create any sub-objects as well as the main object.

Call this via:

$dataset->create_object( $session, $data )
 

User Comments


Class Methods

User Comments


get_system_field_info

$sys_fields = EPrints::DataObj->get_system_field_info

Return an array describing the system metadata of the this dataset.

User Comments


get_defaults

$defaults = EPrints::DataObj->get_defaults( $session, $data, [ $dataset ] )

Return default values for this object based on the starting $data. Uses the data object class to determine dataset if $dataset not set.

Should be subclassed.

User Comments


get_dataset_id

$dataset = EPrints::DataObj->get_dataset_id

Returns the ID of the EPrints::DataSet object to which this record belongs.

User Comments


xml_to_epdata

$epdata = EPrints::DataObj->xml_to_epdata( $session, $xml, %opts )

Populates $epdata based on $xml using options in %opts. This is the inverse of to_xml but doesn't create a new object.

User Comments


export_fieldlist

EPrints::DataObj->export_fieldlist

Returns fields to be exported by plugins that do not have pre-defined fields to export, (e.g. Export::XML).

User Comments


in_export_fieldlist

EPrints::DataObj->in_export_fieldlist

Returns whether a field is in the export fieldlist for a particular data object. Returns true if there is no fieldlist restriction.

User Comments


start_element

EPrints::DataObj->start_element( $data, $epdata, $state )

Consumes a SAX event.

$data is the SAX node data.

$epdata is an EPrints data structure to write values to.

$state maintains state between SAX calls but must contain at least:

   dataset - the dataset the class belongs to
 

User Comments


end_element

EPrints::DataObj->end_element( $data, $epdata, $state )

Ends element from start_element.

User Comments


characters

EPrints::DataObj->characters( $data, $epdata, $state )

Consumes characters within start_element.

User Comments


Object Methods

User Comments


clone

$clone = $dataobj->clone

Clone the current data object, by creating a new data object of the same type and metadata but a new ID.

User Comments


create_subdataobj

$subdataobj = $dataobj->create_subdataobj( $fieldname, $epdata )

Creates and returns a new data object that is a sub-object of this object in field $fieldname with initial data $epdata.

Clears the sub-object cache for this $fieldname which is equivalent to:

$dataobj->set_value( $fieldname, undef );
 

User Comments


local_path

$local_path = $dataobj->local_path

Return local_path string for the history of the data object.

Should be subclassed.

User Comments


update_triggers

$dataobj->update_triggers

Update all the stuff that needs to be updated before the data object is written to the database.

User Comments


delete

$success = $dataobj->delete

Delete this data object from the database and any sub-objects or related files.

Alias for:

$dataobj->remove
 

Return true if successful.

User Comments


empty

$dataobj->empty

Remove all of this object's values that may be imported.

User Comments


update

$dataobj->update( $epdata [, %opts ] )

Update this object's values from $epdata. Ignores any values that do not exist in the dataset or do not have the 'import' property set.

 include_subdataobjs - replace sub-dataobjs if given
 
 # replaces all documents in $dataobj
 $dataobj->update( {
   title => "Wombats on Fire",
   documents => [{
     main => "wombat.pdf",
     ...
   }],
 }, include_subdataobjs => 1 );
 

User Comments


set_under_construction

$dataobj->set_under_construction( $boolean )

Set a flag to indicate this object is being constructed and any house keeping will be handled by the method constructing it so don't do it elsewhere.

User Comments


under_construction

$boolean = $dataobj->under_construction 

Returns c<true> if this object is part way through being constructed.

User Comments


clear_changed

$dataobj->clear_changed

Clear any changed fields, which will result in them not being committed unless force is used.

This method is used by the EPrints::Database to avoid unnecessary commits.

User Comments


clear_citationcaches

$dataobj->clear_citationcaches

Clear any EPrints::DataObj::CitationCache objects associated with the data object.

User Comments


commit

$success = $dataobj->commit( [ $force ] )

Write this object to the database and reset the changed fields.

If $force isn't true then it only actually modifies the database if one or more fields have been changed.

Commit may also queue indexer jobs or log changes, depending on the object.

User Comments


value

$value = $dataobj->value( $fieldname )

Get a the value of a metadata field with $fieldname. If the field is not set then it returns undef unless the field has the property multiple set, in which case it returns [] (a reference to an empty a rray).

Alias for:

$dataobj->get_value( $fieldname )
 

User Comments


set_value

$dataobj->set_value( $fieldname, $value )

Set the $value of the named metadata field $fieldname for this data object.

User Comments


set_value_raw

$dataobj->set_value_raw( $fieldname, $value )

Set the $value of the named metadata field $fieldname for this data object by directly modifying its data hash reference. Use with care!

User Comments


get_values

@values = $dataobj->get_values( $fieldnames )

Returns a list of all the values in this record of all the $fields specified by $fieldnames. These should be in the format used by browse views, using / to seperate individual field names with an optional .id suffix to indicate the ID part rather than the main part.

E.g. author.id/editor.id would return a list of all author and editor IDs from this record.

User Comments


repository

$session = $dataobj->repository

Returns the EPrints::Repository object to which this record belongs.

Alias for:

$dataobj->get_session
 

User Comments


get_data

$data = $dataobj->get_data

Returns a reference to the hash of all the metadata for this record keyed by fieldname.

User Comments


get_dataset

$dataset = $dataobj->get_dataset

Returns the EPrints::DataSet object to which this record belongs.

User Comments


is_set

$boolean = $dataobj->is_set( $fieldname )

Returns true if the field with $fieldname is set in this record, otherwise false.

Warns if the field with $fieldname does not exist.

User Comments


exists_and_set

$boolean = $dataobj->exists_and_set( $fieldname )

Returns true if the field with $fieldname is set in this record, otherwise false.

If the field does not exist, just return false.

This method is useful for plugins which may operate on multiple repositories, when field not existing is not an issue for a particular repository.

User Comments


id

$id = $dataobj->id

Returns the value of the primary key of this record.

Alias for:

$dataobj->get_id
 

User Comments


get_gid

$gid = $dataobj->get_gid

DEPRECATED (see uri)

Returns the globally referential fully-qualified identifier for this data object or undef if this object can not be externally referenced.

User Comments


get_datestamp

$datestamp = $dataobj->get_datestamp

Returns the datestamp of this object in "YYYY-MM-DD hh:mm:ss" format.

User Comments


render_value

$xhtml = $dataobj->render_value( $fieldname, [ $showall ] )

Returns the rendered version of the value of the given $fieldname as appropriate for the current session. If $showall is true then all values are rendered - this is usually used for staff viewing data.

User Comments


render_citation

$xhtml = $dataobj->render_citation( [ $style, %params ] )

Renders the record as a citation. If $style is set then it uses that citation style from the citations config file. Otherwise $style defaults to the type of this record. If $params{url} is set then the citation will link to the specified URL.

If $style is unset then use default.

User Comments


render_citation_link

$xhtml = $dataobj->render_citation_link( [ $style, %params ] )

Renders a citation as like render_citation but as a link to the URL for this item. E.g. the abstract page of an eprint.

$params{url} is set to data object's URL if not set.

User Comments


render_citation_link

$xhtml = $dataobj->render_citation_link( [ $style, %params ] )

Renders a citation as like render_citation but as a link to the control URL for this item. E.g. for items that are not yet in the live archive.

User Comments


render_description

$xhtml = $dataobj->render_description

Returns a short description of this object using the brief citation style for this dataset or the default citation style of the former does not exist.

User Comments


render

( $xhtml, $title ) = $dataobj->render

Return a chunk of XHTML DOM describing this object in the normal way. This is the public view of the record, not the staff view.

User Comments


render_full

$xhtml = $dataobj->render_full

Return an XHTML table in DOM describing this record. All values of all fields are listed. This is the staff view.

User Comments


render_export_links

$xhtml_ul_list = $dataobj->render_export_links( [ $staff ] )

Return a <ul> list containing links to all the formats this eprint is available in.

If $staff is true then show all formats available to staff and link to the staff export URL.

User Comments


render_export_bar

$xhtml = $dataobj->render_export_bar( [ $staff ] )

Returns a rendered drop-down list of exports.

If $staff is true then include both public and staff visible export options.

User Comments


uri

$url = $dataobj->uri

Returns a unique URI for this object. Not certain to resolve as a URL.

If $c-{dataobj_uri}->{eprint}> is a function, call that to work it out.

User Comments


internal_uri

$uri = $dataobj->internal_uri

Return an internal URI for this object (independent of repository hostname).

To retrieve an object by internal URI use EPrints::DataSet::get_object_from_uri().

User Comments


path

$path = $dataobj->path

Returns the relative path to this object from the repository's base URL, if the object has a URL.

Does not include any leading slash.

User Comments


url

$url = $dataobj->url

Returns the URL for this record, e.g.the URL of the abstract page of an eprint.

Alias for:

$dataobj->get_url
 

User Comments


get_control_url

$url = $dataobj->get_control_url

Returns the URL for the control page for this object.

User Comments


get_type

$type = $dataobj->get_type

ABSTRACT.

Returns the type of this data object. This not the dataset it belongs to but the specific type within the dataset (e.g. c<user> could be editor, admin, etc.).

User Comments


to_xml

$xmlfragment = $dataobj->to_xml( %opts )

Convert this object into an XML fragment using options %opts.

Options:

no_xmlns - Do not include a xmlns attribute in the outer element. 
(This assumes this chunk appears in a larger tree where the xmlns is 
already set correctly.
showempty - Fields with no value are shown.
embed - Include the data of a file, not just it's URL.
 

User Comments


to_sax

$dataobj->to_sax( %opts )

Stream this object to a SAX handler using the options in $opts.

Options:

Handler - the SAX handler to build the output.
revision_generation - Generate XML for revision files rather than 
export.

This does not output any document-level events.

User Comments


export

$plugin_output = $dataobj->export( $plugin_id, %params )

Apply an export plugin with $plugin_id to this data object, using the parameters provided by %params and supplying them to the output_dataobj method of the EPrints::Plugin:Export plugin.

Return the output of the export plugin.

User Comments


queue_changes

$dataobj->queue_changes

Add all the changed fields into the indexers todo queue.

User Comments


queue_all

$dataobj->queue_all

Add all the fields into the indexers todo queue.

User Comments


queue_fulltext

$dataobj->queue_fulltext

Add a fulltext index into the indexers todo queue.

User Comments


queue_removed

$dataobj->queue_removed

Add an index removed event to the indexer's queue.

User Comments


has_owner

$boolean = $dataobj->has_owner( $user )

Return true if $user owns this record. Normally this means they created it, but a group of users could count as owners of the same record if you wanted.

It's false on most data objects, except those which override this method.

User Comments


permit

$rc = $dataobj->permit( $priv, [ $user ] )
 # current user can edit via editorial role
 if( $dataobj->permit( "xxx/edit", $user ) & 8 )
 {
   ...
 }
 # anyone can view this object
 if( $dataobj->permit( "xxx/view" ) )
 {
 }
 

Returns true if the specified $user (or 'anybody') can perform this action.

Returns a bit mask where:

 0 - not permitted
 1 - anybody
 2 - logged in user
 4 - user as owner
 8 - user as editor
 

See also EPrints::Repository/allow_anybody and EPrints::DataObj::User/allow.

User Comments


in_editorial_scope_of

$boolean = $dataobj->in_editorial_scope_of( $user )

As for has_owner, but if the $user is identified as someone with an editorial scope which includes this record.

Defaults to true. Which doesn't mean that they have the right to edit it, just that their scope matches. You also need editor rights to use this. It's currently used just to filter eprint editors so that only ones with appropriate scope and privilege can edit.

User Comments


validate

$problems = $dataobj->validate( $for_archive )

Validate this data object. Not used on all sub-classed. $for_archive being true indicates that the item is beting validated to go live.

Returns a reference to an array of XHTML DOM objects describing validation problems with the entire data object for the supplied $for_archive archive ID.

A reference to an empty array indicates no problems.

User Comments


get_warnings

$warnings = $dataobj->get_warnings

Returns a reference to an array of XHTML DOM objects describing problems with the entire data object.

A reference to an empty array indicates no problems.

User Comments


validate_field

@problems = $dataobj->validate_field( $fieldname )

Check if a field named $fieldname is valid.

Returns a reference to an array of XHTML problems.

A reference to an empty array indicates no problems.

User Comments


tidy

$dataobj->tidy

Cleans up any multiple fields with gaps.

User Comments


add_stored_file

$file = $dataobj->add_stored_file( $filename, $filehandle, $filesize )

Convenience method to add (or replace) the file record for $filename to this object. Reads $filesize bytes from $filehandle.

Returns the file object or undef if the storage failed.

User Comments


stored_file

$file = $dataobj->stored_file( $filename )

Get the file object for $filename.

Returns the file object or undef if the file doesn't exist.

Has alias:

$dataobj->get_stored_file( $filename )
 

User Comments


add_dataobj_relations

$dataobj->add_dataobj_relations( $target, %relations )

Add a relation from this data object to the $target data object using predicates defined in the keys of the %relations hash. If values are defined in the hash reciprocal relationships from the $target data object to this data object are also.

You must commit $target data object after calling this method.

Has alias:

$dataobj->add_object_relations( $target, %relations )
 

User Comments


has_dataobj_relations

$boolean = $dataobj->has_dataobj_relations( $target, @required )

Returns true if this object is related to $target by all @required.

If @required is empty will return true if any relationships exist.

Has alias:

$dataobj->has_object_relations( $target, @required )
 

User Comments


has_related_dataobjs

$boolean = $dataobj->has_related_dataobjs( @required )

Returns true if related_dataobjs would return some objects but without actually retrieving the related objects from the database.

Has alias:

$dataobj->has_related_objects( @required )
 

User Comments


related_dataobjs

@dataobjs = $dataobj->related_dataobjs( @required )

Returns a list of objects related to this data object by a relation in @required.

Has alias:

$dataobj->get_related_objects( @required )
 

User Comments


remove_dataobj_relations

$dataobj->remove_dataobj_relations( $target, %relations )

Remove relations between this data object and the $target data object. If %relations is not empty only remove those relationships which are keys in this hash.

You must commit this object and $target to write the changes.

Has alias:

$dataobj->remove_object_relations( $target, %relations )

User Comments


SEE ALSO

EPrints::DataSet

User Comments


COPYRIGHT

© Copyright 2023 University of Southampton.

EPrints 3.4 is supplied by EPrints Services.

http://www.eprints.org/eprints-3.4/

LICENSE

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

EPrints 3.4 and this file are released under the terms of the GNU Lesser General Public License version 3 as published by the Free Software Foundation unless otherwise stated.

EPrints 3.4 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 3.4. If not, see http://www.gnu.org/licenses/.

User Comments