Difference between revisions of "API:EPrints/DataObj"

From EPrints Documentation
Jump to: navigation, search
(7 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
<!-- Pod2Wiki=_preamble_  
 
<!-- Pod2Wiki=_preamble_  
 
This page has been automatically generated from the EPrints 3.2 source. Any wiki changes made between the 'Pod2Wiki=*' and 'Edit below this comment' comments will be lost.
 
This page has been automatically generated from the EPrints 3.2 source. Any wiki changes made between the 'Pod2Wiki=*' and 'Edit below this comment' comments will be lost.
  -->{{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 -->
+
  -->{{API}}{{Pod2Wiki}}{{API:Source|file=perl_lib/EPrints/DataObj.pm|package_name=EPrints::DataObj}}[[Category:API|DATAOBJ]][[Category:API:EPrints/DataObj|DATAOBJ]]<div><!-- Edit below this comment -->
  
  
Line 8: Line 8:
 
'''EPrints::DataObj''' - Base class for records in EPrints.
 
'''EPrints::DataObj''' - Base class for records in EPrints.
  
<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_description -->
+
==SYNOPSIS==
==DESCRIPTION==
+
$dataobj = $dataset-&gt;dataobj( $id );
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.
+
$dataobj-&gt;delete;
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
$dataobj-&gt;commit( $force );
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
  
 +
$dataset = $dataobj-&gt;dataset;
  
<!-- Pod2Wiki= -->
+
$repo = $dataobj-&gt;repository;
</div>
 
<!-- Pod2Wiki=item_get_system_field_info -->
 
===$sys_fields = EPrints::DataObj-&gt;get_system_field_info===
 
  
Return an array describing the system metadata of the this  dataset.
+
$id = $dataobj-&gt;id;
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
$dataobj-&gt;set_value( $fieldname, $value );
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
  
 +
$value = $dataobj-&gt;value( $fieldname );
  
<!-- Pod2Wiki= -->
+
\@value = $dataobj-&gt;value( $fieldname ); # multiple
</div>
 
<!-- Pod2Wiki=item_new -->
 
===$dataobj = EPrints::DataObj-&gt;new( $session, $id [, $dataset] )===
 
  
Return new data object, created by loading it from the database.
+
$boolean = $dataobj-&gt;is_set( $fieldname );
  
If $dataset is not defined uses the default dataset for this object.
+
$xhtml = $dataobj-&gt;render_value( $fieldname );
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
$xhtml = $dataobj-&gt;render_citation( $style, %opts );
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
  
 +
$uri = $dataobj-&gt;uri;
  
<!-- Pod2Wiki= -->
+
$url = $dataobj-&gt;url;
</div>
 
<!-- Pod2Wiki=item_new_from_data -->
 
===$dataobj = EPrints::DataObj-&gt;new_from_data( $session, $data [, $dataset ] )===
 
  
Construct a new EPrints::DataObj object based on the $data hash  reference of metadata.
+
$string = $dataobj-&gt;export( $plugin_id, %opts );
  
Used to create an object from the data retrieved from the database.
+
$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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_description -->
<!-- Pod2Wiki=item_create_subdataobj -->
+
==DESCRIPTION==
===$dataobj = $dataobj-&gt;create_subdataobj( $fieldname, $epdata )===
+
This module is a base class which 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 several other classes.
  
Creates and returns a new dataobj that is a sub-object of this object in field $fieldname with initial data $epdata.
+
It is ABSTRACT - its methods should not be called directly.
 
 
Clears the sub-object cache for this $fieldname 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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
* $success = $dataobj-&gt;delete
<!-- Pod2Wiki=item_get_defaults -->
+
: Delete this data object from the database and any sub-objects or related files.  
===$defaults = EPrints::User-&gt;get_defaults( $session, $data, $dataset )===
 
 
 
Return default values for this object based on the starting data.
 
  
Should be subclassed.
+
: Return true 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%; '>
+
* $dataobj-&gt;empty()
<span style='display:none'>User Comments</span>
+
: Remove all of this object's values that may be imported.
<!-- Edit below this comment -->
 
  
 +
* $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.
  
<!-- Pod2Wiki= -->
+
<pre> include_subdataobjs - replace sub-dataobjs if given
</div>
+
 
<!-- Pod2Wiki=item_remove -->
+
  # replaces all documents in $dataobj
===$success = $dataobj-&gt;remove===
+
  $dataobj->update( {
 
+
    title => "Wombats on Fire",
Remove this data object from the database and any sub-objects or related files.
+
    documents => [{
 
+
      main => "wombat.pdf",
Return true 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%; '>
+
  }, include_subdataobjs => 1 );</pre>
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
 
 
 
 
<!-- Pod2Wiki= -->
 
</div>
 
<!-- Pod2Wiki=item_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 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_commit -->
 
===$success = $dataobj-&gt;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.
 
 
 
<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_value -->
 
===$value = $dataobj-&gt;get_value( $fieldname )===
 
 
 
Get a the value of a metadata field. 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 array).
 
 
 
<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_value -->
 
===$dataobj-&gt;set_value( $fieldname, $value )===
 
 
 
Set the value of the named metadata field in 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_get_values -->
 
===@values = $dataobj-&gt;get_values( $fieldnames )===
 
 
 
Returns a list of all the values in this record of all the fields specified by $fieldnames. $fieldnames should be in the format used by browse views - slash seperated fieldnames with an optional .id suffix to indicate the id part rather than the main part.
 
 
 
For example "author.id/editor.id" 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_get_session -->
 
===$session = $dataobj-&gt;get_session===
 
 
 
Returns the EPrints::Session 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_get_data -->
 
===$data = $dataobj-&gt;get_data===
 
 
 
Returns a reference to the hash table 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_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_get_dataset -->
 
===$dataset = $dataobj-&gt;get_dataset===
 
 
 
Returns 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_is_set -->
 
===$bool = $dataobj-&gt;is_set( $fieldname )===
 
 
 
Returns true if the named field is set in this record, otherwise false.
 
 
 
Warns if the field 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_exists_and_set -->
 
===$bool = $dataobj-&gt;exists_and_set( $fieldname )===
 
 
 
Returns true if the named field 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, and the fact a field does not exist is not an issue.
 
 
 
<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_id -->
 
===$id = $dataobj-&gt;get_id===
 
 
 
Returns the value of the primary key 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_get_gid -->
 
===$id = $dataobj-&gt;get_gid===
 
 
 
DEPRECATED (see uri())
 
 
 
Returns the globally referential fully-qualified identifier for this object or undef 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 -->
 
===$datestamp = $dataobj-&gt;get_datestamp===
 
 
 
Returns the datestamp of this object in "YYYY-MM-DD hh:mm:ss" format.
 
 
 
<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 -->
 
===$xhtml = $dataobj-&gt;render_value( $fieldname, [$showall] )===
 
 
 
Returns the rendered version of the value of the given field, as appropriate for 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%; '>
 
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
 
 
 
 
<!-- Pod2Wiki= -->
 
</div>
 
<!-- Pod2Wiki=item_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 $style defaults to the type of this record. If $params{url} is set then the citiation will link to the specified 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_render_citation_link -->
 
===$xhtml = $dataobj-&gt;render_citation_link( [$style], %params )===
 
 
 
Renders a citation (as above) but as a link to the URL for this item. For example - the abstract page of 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%; '>
 
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
 
 
 
 
<!-- Pod2Wiki= -->
 
</div>
 
<!-- Pod2Wiki=item_render_description -->
 
===$xhtml = $dataobj-&gt;render_description===
 
 
 
Returns a short description of this object using the default citation style for 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_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 -->
 
===($xhtml, $title ) = $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.
 
 
 
<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_uri -->
 
===$url = $dataobj-&gt;uri===
 
 
 
Returns a unique URI for this object. Not certain to resolve as a  URL.
 
 
 
If $c-&gt;{dataobj_uri}-&gt;{eprint} 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 -->
 
===$uri = $dataobj-&gt;internal_uri()===
 
 
 
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().
 
 
 
<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_url -->
 
===$url = $dataobj-&gt;get_url===
 
 
 
Returns the URL for this record, for example the URL of the abstract page of 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%; '>
 
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
 
 
 
 
<!-- Pod2Wiki= -->
 
</div>
 
<!-- Pod2Wiki=item_get_control_url -->
 
===$url = $dataobj-&gt;get_control_url===
 
 
 
Returns the URL for the control page 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_get_type -->
 
===$type = $dataobj-&gt;get_type===
 
 
 
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%; '>
 
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
 
 
 
 
<!-- Pod2Wiki= -->
 
</div>
 
<!-- Pod2Wiki=item_to_xml -->
 
===$xmlfragment = $dataobj-&gt;to_xml( %opts )===
 
 
 
Convert this object into an XML fragment.
 
 
 
%opts are:
 
 
 
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.
 
 
 
showempty=&gt;1 : fields with no value are shown.
 
 
 
version=&gt;"code" : pick what version of the EPrints XML format to use "1" or "2"
 
 
 
embed=&gt;1 : 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 -->
 
 
 
 
 
<!-- Pod2Wiki= -->
 
</div>
 
<!-- Pod2Wiki=item_xml_to_epdata -->
 
===$epdata = EPrints::DataObj-&gt;xml_to_epdata( $session, $xml, %opts )===
 
  
Populates $epdata based on $xml. This is the inverse of to_xml() but doesn't create a new object.
+
* $success = $dataobj-&gt;commit( [$force] )
 +
: Write this object to the database and reset the changed fields.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
: If $force isn't true then it only actually modifies the database if one or more fields have been changed.
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
  
 +
: Commit may also queue indexer jobs or log changes, depending on the object.
  
<!-- Pod2Wiki= -->
+
* $value = $dataobj-&gt;value( $fieldname )
</div>
+
: Get a the value of a metadata field. 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 array).
<!-- Pod2Wiki=item_export -->
 
===$plugin_output = $detaobj-&gt;export( $plugin_id, %params )===
 
  
Apply an output plugin to this items. Return the results.
+
* $dataobj-&gt;set_value( $fieldname, $value )
 +
: Set the value of the named metadata field in 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%; '>
+
* @values = $dataobj-&gt;get_values( $fieldnames )
<span style='display:none'>User Comments</span>
+
: Returns a list of all the values in this record of all the fields specified by $fieldnames. $fieldnames should be in the format used by browse views - slash seperated fieldnames with an optional .id suffix to indicate the id part rather than the main part.
<!-- Edit below this comment -->
 
  
 +
: For example "author.id/editor.id" would return a list of all author and editor ids from this record.
  
<!-- Pod2Wiki= -->
+
* $bool = $dataobj-&gt;is_set( $fieldname )
</div>
+
: Returns true if the named field is set in this record, otherwise false.
<!-- Pod2Wiki=item_queue_changes -->
 
===$dataobj-&gt;queue_changes===
 
  
Add all the changed fields into the indexers todo queue.
+
: Warns if the field 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%; '>
+
* $bool = $dataobj-&gt;exists_and_set( $fieldname )
<span style='display:none'>User Comments</span>
+
: Returns true if the named field is set in this record, otherwise false.
<!-- Edit below this comment -->
 
  
 +
: If the field does not exist, just return false.
  
<!-- Pod2Wiki= -->
+
: This method is useful for plugins which may operate on multiple  repositories, and the fact a field does not exist is not an issue.
</div>
 
<!-- Pod2Wiki=item_queue_all -->
 
===$dataobj-&gt;queue_all===
 
  
Add all the fields into the indexers todo queue.
+
* $id = $dataobj-&gt;id
 +
: Returns the value of the primary key 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%; '>
+
* $uuid = $dataobj-&gt;uuid( [ $fragment ] )
<span style='display:none'>User Comments</span>
+
: Generates a version 5 UUID for this object e.g.
<!-- Edit below this comment -->
 
  
 +
<pre>  f70ef731-be66-50f4-8e72-8b8de36778b5</pre>
  
<!-- Pod2Wiki= -->
+
: The UUID is generated from the SHA1 hash of the concantenation of <code>uuid_namespace</code>, the {{API:PodLink|file=|package_name=|section=internal_uri|text=object's uri}} and, if defined, '''$fragment'''.
</div>
 
<!-- Pod2Wiki=item_queue_fulltext -->
 
===$dataobj-&gt;queue_fulltext===
 
  
Add a fulltext index into the indexers todo queue.
+
: <code>uuid_namespace</code> is a configuration variable. If <code>uuid_namespace</code> is undefined uses <code>base_url</code>:
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
<pre>  # Note: deliberate typo to prevent copy-and-paste
<span style='display:none'>User Comments</span>
+
  $c-&gt;{uuid_namespace} = "http://your-repository's url"";</pre>
<!-- Edit below this comment -->
 
  
 +
: Returns the formatted UUID.
  
<!-- Pod2Wiki= -->
+
* $xhtml = $dataobj-&gt;render_value( $fieldname, [$showall] )
</div>
+
: Returns the rendered version of the value of the given field, as appropriate for the current session. If $showall is true then all values are rendered -  this is usually used for staff viewing data.
<!-- Pod2Wiki=item_has_owner -->
 
===$boolean = $dataobj-&gt;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.
+
* $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 $style defaults to the type of this record. If $params{url} is set then the citiation will link to the specified URL.
  
It's false on most dataobjs, except those which override this method.
+
* $xhtml = $dataobj-&gt;render_citation_link( [$style], %params )
 +
: Renders a citation (as above) but as a link to the URL for this item. For example - the abstract page of 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%; '>
+
* $xhtml = $dataobj-&gt;render_export_bar( [ $staff ] )
<span style='display:none'>User Comments</span>
+
: Render a drop-down list of exports.
<!-- 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>
 
<!-- Pod2Wiki=item_in_editorial_scope_of -->
 
===$boolean = $dataobj-&gt;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.
+
* $path = $dataobj-&gt;path
 +
: Returns the relative path to this object from the repository's base URL, if the object has a URL.
  
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 a scope AND a priv can edit.
+
: 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%; '>
+
* $url = $dataobj-&gt;url
<span style='display:none'>User Comments</span>
+
: Returns the URL for this record, for example the URL of the abstract page of an eprint.
<!-- Edit below this comment -->
 
  
 +
* $plugin_output = $dataobj-&gt;export( $plugin_id, %params )
 +
: Apply an output plugin to this items. Return the results.
  
<!-- Pod2Wiki= -->
+
* $rc = $dataobj-&gt;permit( $priv [, $user ] )
</div>
+
<pre> # current user can edit via editorial role
<!-- Pod2Wiki=item_validate -->
+
  if( $dataobj-&gt;permit( "xxx/edit", $user ) &amp; 8 )
===$problems = $dataobj-&gt;validate( [ $for_archive ], $workflow_id )===
+
  {
 +
    ...
 +
  }
 +
  # anyone can view this object
 +
  if( $dataobj-&gt;permit( "xxx/view" ) )
 +
  {
 +
  }</pre>
  
Return a reference to an array of XHTML DOM objects describing validation problems with the entire $dataobj based on $workflow_id.
+
: Returns true if the current user (or 'anybody') can perform this action.
  
If $workflow_id is undefined defaults to "default".
+
: Returns a bit mask where:
  
A reference to an empty array indicates no problems.
+
<pre>  0 - not permitted
 +
  1 - anybody
 +
  2 - logged in user
 +
  4 - user as owner
 +
  8 - user as editor</pre>
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
: See also [[API:EPrints/Repository#allow_anybody|EPrints::Repository/allow_anybody]] and [[API:EPrints/DataObj/User#allow|EPrints::DataObj::User/allow]].
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
  
 +
* $list = $dataobj-&gt;duplicates()
 +
: Return a conservative list of other objects that look like this one.
  
<!-- Pod2Wiki= -->
+
<!-- Pod2Wiki=head_copyright -->
</div>
+
==COPYRIGHT==
<!-- Pod2Wiki=item_get_warnings -->
+
Copyright 2000-2011 University of Southampton.
===$warnings = $dataobj-&gt;get_warnings( )===
 
  
Return a reference to an array of XHTML DOM objects describing problems with the entire $dataobj.
+
This file is part of EPrints http://www.eprints.org/.
  
A reference to an empty array indicates no problems.
+
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.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
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 PURPOSESee the GNU Lesser General Public License for more details.
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
 
 
 
 
<!-- Pod2Wiki= -->
 
</div>
 
<!-- Pod2Wiki=item_add_stored_file -->
 
===$file = $dataobj-&gt;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.
 
 
 
<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_stored_file -->
 
===$file = $dataobj-&gt;get_stored_file( $filename )===
 
 
 
Get the file object for $filename.
 
  
Returns the file object or undef if the file doesn't exist.
+
You should have received a copy of the GNU Lesser General Public License along with EPrints.  If not, see http://www.gnu.org/licenses/.
  
<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=_postamble_ -->
<!-- Pod2Wiki=head_related_objects -->
 
===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 -->
 
<!-- Edit below this comment -->
 
 
<!-- Pod2Wiki= -->
 
</div>
 
<!-- Pod2Wiki=item_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.
 
 
You must commit $target after calling 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_has_object_relations -->
 
====$bool = $dataobj-&gt;has_object_relations( $target, @types )====
 
 
Returns true if this object is related to $target by all @types.
 
 
If @types is empty will return true if any relationships 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_has_related_objects -->
 
====$bool = $dataobj-&gt;has_related_objects( @types )====
 
 
Returns true if get_related_objects() would return some objects, but without actually retrieving the related objects from 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_get_related_objects -->
 
====$dataobjs = $dataobj-&gt;get_related_objects( @types )====
 
 
Returns a list of objects related to this object by @types.
 
 
<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_remove_object_relations -->
 
====$dataobj-&gt;remove_object_relations( $target [, $has =&gt; $is [, $has =&gt; $is ] )====
 
 
Remove relations between this object and $target. If $has =&gt; $is pairs are defined will only remove those relationships given.
 
 
You must commit $target after calling 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=_postamble_ --><!-- Edit below this comment -->
 

Revision as of 09:56, 22 January 2013

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::DataObj - Base class for records in EPrints.


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;

$url = $dataobj->url;

$string = $dataobj->export( $plugin_id, %opts );

$dataobj = $dataobj->create_subobject( $fieldname, $epdata );


DESCRIPTION

This module is a base class which is inherited by EPrints::DataObj::EPrint, EPrints::DataObj::User, EPrints::DataObj::Subject and EPrints::DataObj::Document and several other classes.

It is ABSTRACT - its methods should not be called directly.


  • $success = $dataobj->delete
Delete this data object from the database and any sub-objects or related files.
Return true if successful.
  • $dataobj->empty()
Remove all of this object's values that may be imported.
  • $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 );
  • $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.
  • $value = $dataobj->value( $fieldname )
Get a the value of a metadata field. 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 array).
  • $dataobj->set_value( $fieldname, $value )
Set the value of the named metadata field in this record.
  • @values = $dataobj->get_values( $fieldnames )
Returns a list of all the values in this record of all the fields specified by $fieldnames. $fieldnames should be in the format used by browse views - slash seperated fieldnames with an optional .id suffix to indicate the id part rather than the main part.
For example "author.id/editor.id" would return a list of all author and editor ids from this record.
  • $bool = $dataobj->is_set( $fieldname )
Returns true if the named field is set in this record, otherwise false.
Warns if the field does not exist.
  • $bool = $dataobj->exists_and_set( $fieldname )
Returns true if the named field 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, and the fact a field does not exist is not an issue.
  • $id = $dataobj->id
Returns the value of the primary key of this record.
  • $uuid = $dataobj->uuid( [ $fragment ] )
Generates a version 5 UUID for this object e.g.
  f70ef731-be66-50f4-8e72-8b8de36778b5
The UUID is generated from the SHA1 hash of the concantenation of uuid_namespace, the object's uri and, if defined, $fragment.
uuid_namespace is a configuration variable. If uuid_namespace is undefined uses base_url:
  # Note: deliberate typo to prevent copy-and-paste
  $c->{uuid_namespace} = "http://your-repository's url"";
Returns the formatted UUID.
  • $xhtml = $dataobj->render_value( $fieldname, [$showall] )
Returns the rendered version of the value of the given field, as appropriate for the current session. If $showall is true then all values are rendered - this is usually used for staff viewing data.
  • $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 citiation will link to the specified URL.
  • $xhtml = $dataobj->render_citation_link( [$style], %params )
Renders a citation (as above) but as a link to the URL for this item. For example - the abstract page of an eprint.
  • $xhtml = $dataobj->render_export_bar( [ $staff ] )
Render a drop-down list of exports.
  • $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.
  • $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.
  • $url = $dataobj->url
Returns the URL for this record, for example the URL of the abstract page of an eprint.
  • $plugin_output = $dataobj->export( $plugin_id, %params )
Apply an output plugin to this items. Return the results.
  • $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 current 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.
  • $list = $dataobj->duplicates()
Return a conservative list of other objects that look like this one.

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