Difference between revisions of "API:EPrints/DataObj"

From EPrints Documentation
Jump to: navigation, search
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 source. Any wiki changes made between the 'Pod2Wiki=*' and 'End of Pod2Wiki' comments will be lost.
  -->{{API:Source|file=EPrints/DataObj.pm|package_name=EPrints::DataObj}}[[Category:API|DataObj]]<!-- End of Pod2Wiki -->
+
  -->{{Pod2Wiki}}{{API:Source|file=EPrints/DataObj.pm|package_name=EPrints::DataObj}}[[Category:API|DataObj]]<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=head_name -->'''EPrints::DataObj''' - Base class for records in EPrints.
+
<!-- Pod2Wiki=head_name -->=NAME=
__TOC__
+
'''EPrints::DataObj''' - Base class for records in EPrints.
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=head_description -->=DESCRIPTION=
 
<!-- 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.
+
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.
 
It is ABSTRACT - its methods should not be called directly.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_system_field_info -->==get_system_field_info==
 
<!-- Pod2Wiki=item_get_system_field_info -->==get_system_field_info==
Line 13: Line 16:
 
   $sys_fields = EPrints::DataObj-&gt;get_system_field_info
 
   $sys_fields = EPrints::DataObj-&gt;get_system_field_info
  
Return an array describing the system metadata of the this dataset.
+
Return an array describing the system metadata of the this dataset.
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_new -->==new==
 
<!-- Pod2Wiki=item_new -->==new==
Line 20: Line 24:
  
 
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.
 
If $dataset is not defined uses the default dataset for this object.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_new_from_data -->==new_from_data==
 
<!-- Pod2Wiki=item_new_from_data -->==new_from_data==
Line 26: Line 32:
 
   $dataobj = EPrints::DataObj-&gt;new_from_data( $session, $data [, $dataset ] )
 
   $dataobj = EPrints::DataObj-&gt;new_from_data( $session, $data [, $dataset ] )
  
Construct a new EPrints::DataObj object based on the $data hash reference of metadata.
+
Construct a new EPrints::DataObj object based on the $data hash reference of metadata.
 +
 
 
Used to create an object from the data retrieved from the database.
 
Used to create an object from the data retrieved from the database.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_defaults -->==get_defaults==
 
<!-- Pod2Wiki=item_get_defaults -->==get_defaults==
Line 34: Line 42:
  
 
Return default values for this object based on the starting data.
 
Return default values for this object based on the starting data.
 +
 
Should be subclassed.
 
Should be subclassed.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_remove -->==remove==
 
<!-- Pod2Wiki=item_remove -->==remove==
Line 41: Line 51:
  
 
Remove this data object from the database and any sub-objects or related files.  
 
Remove this data object from the database and any sub-objects or related files.  
 +
 
Return true if successful.
 
Return true if successful.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_clear_changed -->==clear_changed==
 
<!-- Pod2Wiki=item_clear_changed -->==clear_changed==
Line 47: Line 59:
 
   $dataobj-&gt;clear_changed( )
 
   $dataobj-&gt;clear_changed( )
  
Clear any changed fields, which will result in them not being committed unlessforce is used.
+
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.
 
This method is used by the Database to avoid unnecessary commits.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_commit -->==commit==
 
<!-- Pod2Wiki=item_commit -->==commit==
Line 55: Line 69:
  
 
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.
+
 
 +
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.
 
Commit may also queue indexer jobs or log changes, depending on the object.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_value -->==get_value==
 
<!-- Pod2Wiki=item_get_value -->==get_value==
Line 62: Line 79:
 
   $value = $dataobj-&gt;get_value( $fieldname )
 
   $value = $dataobj-&gt;get_value( $fieldname )
  
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).
+
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).
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_set_value -->==set_value==
 
<!-- Pod2Wiki=item_set_value -->==set_value==
Line 69: Line 87:
  
 
Set the value of the named metadata field in this record.
 
Set the value of the named metadata field in this record.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_values -->==get_values==
 
<!-- Pod2Wiki=item_get_values -->==get_values==
Line 74: Line 93:
 
   @values = $dataobj-&gt;get_values( $fieldnames )
 
   @values = $dataobj-&gt;get_values( $fieldnames )
  
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.  
+
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 editorids from this record.
+
 
 +
For example "author.id/editor.id" would return a list of all author and editor ids from this record.
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_session -->==get_session==
 
<!-- Pod2Wiki=item_get_session -->==get_session==
Line 82: Line 103:
  
 
Returns the EPrints::Session object to which this record belongs.
 
Returns the EPrints::Session object to which this record belongs.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_data -->==get_data==
 
<!-- Pod2Wiki=item_get_data -->==get_data==
Line 87: Line 109:
 
   $data = $dataobj-&gt;get_data
 
   $data = $dataobj-&gt;get_data
  
Returns a reference to the hash table of all the metadata for this record keyed by fieldname.
+
Returns a reference to the hash table of all the metadata for this record keyed by fieldname.
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_dataset_id -->==get_dataset_id==
 
<!-- Pod2Wiki=item_get_dataset_id -->==get_dataset_id==
Line 94: Line 117:
  
 
Returns the id of the [[API:EPrints/DataSet|EPrints::DataSet]] object to which this record belongs.
 
Returns the id of the [[API:EPrints/DataSet|EPrints::DataSet]] object to which this record belongs.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_dataset -->==get_dataset==
 
<!-- Pod2Wiki=item_get_dataset -->==get_dataset==
Line 100: Line 124:
  
 
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 -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_is_set -->==is_set==
 
<!-- Pod2Wiki=item_is_set -->==is_set==
Line 106: Line 131:
  
 
Returns true if the named field is set in this record, otherwise false.
 
Returns true if the named field is set in this record, otherwise false.
 +
 
Warns if the field does not exist.
 
Warns if the field does not exist.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_exists_and_set -->==exists_and_set==
 
<!-- Pod2Wiki=item_exists_and_set -->==exists_and_set==
Line 113: Line 140:
  
 
Returns true if the named field is set in this record, otherwise false.
 
Returns true if the named field is set in this record, otherwise false.
 +
 
If the field does not exist, just return 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.
+
 
 +
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 -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_id -->==get_id==
 
<!-- Pod2Wiki=item_get_id -->==get_id==
Line 121: Line 151:
  
 
Returns the value of the primary key of this record.
 
Returns the value of the primary key of this record.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_gid -->==get_gid==
 
<!-- Pod2Wiki=item_get_gid -->==get_gid==
Line 127: Line 158:
  
 
DEPRECATED (see uri())
 
DEPRECATED (see uri())
Returns the globally referential fully-qualified identifier for this object orundef if this object can not be externally referenced.
+
 
 +
Returns the globally referential fully-qualified identifier for this object or undef if this object can not be externally referenced.
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_datestamp -->==get_datestamp==
 
<!-- Pod2Wiki=item_get_datestamp -->==get_datestamp==
Line 134: Line 167:
  
 
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 -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_value -->==render_value==
 
<!-- Pod2Wiki=item_render_value -->==render_value==
Line 139: Line 173:
 
   $xhtml = $dataobj-&gt;render_value( $fieldname, [$showall] )
 
   $xhtml = $dataobj-&gt;render_value( $fieldname, [$showall] )
  
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.
+
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.
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_citation -->==render_citation==
 
<!-- Pod2Wiki=item_render_citation -->==render_citation==
Line 145: Line 180:
 
   $xhtml = $dataobj-&gt;render_citation( [$style], [%params] )
 
   $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.
+
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.
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_citation_link -->==render_citation_link==
 
<!-- Pod2Wiki=item_render_citation_link -->==render_citation_link==
Line 151: Line 187:
 
   $xhtml = $dataobj-&gt;render_citation_link( [$style], %params )
 
   $xhtml = $dataobj-&gt;render_citation_link( [$style], %params )
  
Renders a citation (as above) but as a link to the URL for this item. Forexample - the abstract page of an eprint.  
+
Renders a citation (as above) but as a link to the URL for this item. For example - the abstract page of an eprint.  
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_description -->==render_description==
 
<!-- Pod2Wiki=item_render_description -->==render_description==
Line 157: Line 194:
 
   $xhtml = $dataobj-&gt;render_description
 
   $xhtml = $dataobj-&gt;render_description
  
Returns a short description of this object using the default citation stylefor this dataset.
+
Returns a short description of this object using the default citation style for this dataset.
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render -->==render==
 
<!-- Pod2Wiki=item_render -->==render==
Line 163: Line 201:
 
   ($xhtml, $title ) = $dataobj-&gt;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.
+
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.
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_full -->==render_full==
 
<!-- Pod2Wiki=item_render_full -->==render_full==
Line 169: Line 208:
 
   ($xhtml, $title ) = $dataobj-&gt;render_full
 
   ($xhtml, $title ) = $dataobj-&gt;render_full
  
Return an XHTML table in DOM describing this record. All values ofall fields are listed. This is the staff view.
+
Return an XHTML table in DOM describing this record. All values of all fields are listed. This is the staff view.
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_uri -->==uri==
 
<!-- Pod2Wiki=item_uri -->==uri==
Line 175: Line 215:
 
   $url = $dataobj-&gt;uri
 
   $url = $dataobj-&gt;uri
  
Returns a unique URI for this object. Not certain to resolve as a URL.
+
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.
 
If $c-&gt;{dataobj_uri}-&gt;{eprint} is a function, call that to work it out.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_internal_uri -->==internal_uri==
 
<!-- Pod2Wiki=item_internal_uri -->==internal_uri==
Line 183: Line 225:
  
 
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().
 
To retrieve an object by internal URI use [[API:EPrints/DataSet|EPrints::DataSet]]::get_object_from_uri().
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_url -->==get_url==
 
<!-- Pod2Wiki=item_get_url -->==get_url==
Line 189: Line 233:
 
   $url = $dataobj-&gt;get_url
 
   $url = $dataobj-&gt;get_url
  
Returns the URL for this record, for example the URL of the abstract pageof an eprint.
+
Returns the URL for this record, for example the URL of the abstract page of an eprint.
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_control_url -->==get_control_url==
 
<!-- Pod2Wiki=item_get_control_url -->==get_control_url==
Line 196: Line 241:
  
 
Returns the URL for the control page for this object.  
 
Returns the URL for the control page for this object.  
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_type -->==get_type==
 
<!-- Pod2Wiki=item_get_type -->==get_type==
Line 202: Line 248:
  
 
Returns the type of this record - type of user, type of eprint etc.
 
Returns the type of this record - type of user, type of eprint etc.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_to_xml -->==to_xml==
 
<!-- Pod2Wiki=item_to_xml -->==to_xml==
Line 208: Line 255:
  
 
Convert this object into an XML fragment.  
 
Convert this object into an XML fragment.  
 +
 
%opts are:
 
%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.
+
 
 +
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.
 
showempty=&gt;1 : fields with no value are shown.
version=&gt;"code" : pick what version of the EPrints XML formatto use "1" or "2"
+
 
 +
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.
 
embed=&gt;1 : include the data of a file, not just it's URL.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_xml_to_epdata -->==xml_to_epdata==
 
<!-- Pod2Wiki=item_xml_to_epdata -->==xml_to_epdata==
Line 219: Line 272:
  
 
Populates $epdata based on $xml. This is the inverse of to_xml() but doesn't create a new object.
 
Populates $epdata based on $xml. This is the inverse of to_xml() but doesn't create a new object.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_export -->==export==
 
<!-- Pod2Wiki=item_export -->==export==
Line 225: Line 279:
  
 
Apply an output plugin to this items. Return the results.
 
Apply an output plugin to this items. Return the results.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_queue_changes -->==queue_changes==
 
<!-- Pod2Wiki=item_queue_changes -->==queue_changes==
Line 231: Line 286:
  
 
Add all the changed fields into the indexers todo queue.
 
Add all the changed fields into the indexers todo queue.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_queue_all -->==queue_all==
 
<!-- Pod2Wiki=item_queue_all -->==queue_all==
Line 237: Line 293:
  
 
Add all the fields into the indexers todo queue.
 
Add all the fields into the indexers todo queue.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_queue_fulltext -->==queue_fulltext==
 
<!-- Pod2Wiki=item_queue_fulltext -->==queue_fulltext==
Line 243: Line 300:
  
 
Add a fulltext index into the indexers todo queue.
 
Add a fulltext index into the indexers todo queue.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_has_owner -->==has_owner==
 
<!-- Pod2Wiki=item_has_owner -->==has_owner==
Line 248: Line 306:
 
   $boolean = $dataobj-&gt;has_owner( $user )
 
   $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 samerecord if you wanted.
+
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 dataobjs, except those which override this method.
 
It's false on most dataobjs, except those which override this method.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_in_editorial_scope_of -->==in_editorial_scope_of==
 
<!-- Pod2Wiki=item_in_editorial_scope_of -->==in_editorial_scope_of==
Line 255: Line 315:
 
   $boolean = $dataobj-&gt;in_editorial_scope_of( $user )
 
   $boolean = $dataobj-&gt;in_editorial_scope_of( $user )
  
As for has_owner, but if the user is identified as someone with aneditorial scope which includes this record.
+
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 rightsto use this. It's currently used just to filter eprint editors sothat only ones with a scope AND a priv can edit.
+
 
 +
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.
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_validate -->==validate==
 
<!-- Pod2Wiki=item_validate -->==validate==
Line 262: Line 324:
 
   $problems = $dataobj-&gt;validate( [ $for_archive ], $workflow_id )
 
   $problems = $dataobj-&gt;validate( [ $for_archive ], $workflow_id )
  
Return a reference to an array of XHTML DOM objects describingvalidation problems with the entire $dataobj based on $workflow_id.
+
Return a reference to an array of XHTML DOM objects describing validation problems with the entire $dataobj based on $workflow_id.
 +
 
 
If $workflow_id is undefined defaults to "default".
 
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 -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_warnings -->==get_warnings==
 
<!-- Pod2Wiki=item_get_warnings -->==get_warnings==
Line 270: Line 335:
 
   $warnings = $dataobj-&gt;get_warnings( )
 
   $warnings = $dataobj-&gt;get_warnings( )
  
Return a reference to an array of XHTML DOM objects describingproblems with the entire $dataobj.
+
Return a reference to an array of XHTML DOM objects describing problems 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 -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_add_stored_file -->==add_stored_file==
 
<!-- Pod2Wiki=item_add_stored_file -->==add_stored_file==
Line 278: Line 345:
  
 
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.
 
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.
 +
 
Returns the file object or undef if the storage failed.
 
Returns the file object or undef if the storage failed.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_stored_file -->==get_stored_file==
 
<!-- Pod2Wiki=item_get_stored_file -->==get_stored_file==
Line 285: Line 354:
  
 
Get the file object for $filename.
 
Get the file object for $filename.
 +
 
Returns the file object or undef if the file doesn't exist.
 
Returns the file object or undef if the file doesn't exist.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=head_related_objects -->==Related Objects==
 
<!-- Pod2Wiki=head_related_objects -->==Related Objects==
Line 294: Line 365:
  
 
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.
 
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.
 
You must commit $target after calling this method.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_has_object_relations -->===has_object_relations===
 
<!-- Pod2Wiki=item_has_object_relations -->===has_object_relations===
Line 301: Line 374:
  
 
Returns true if this object is related to $target by all @types.
 
Returns true if this object is related to $target by all @types.
 +
 
If @types is empty will return true if any relationships exist.
 
If @types is empty will return true if any relationships exist.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_has_related_objects -->===has_related_objects===
 
<!-- Pod2Wiki=item_has_related_objects -->===has_related_objects===
Line 308: Line 383:
  
 
Returns true if get_related_objects() would return some objects, but without actually retrieving the related objects from the database.
 
Returns true if get_related_objects() would return some objects, but without actually retrieving the related objects from the database.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_related_objects -->===get_related_objects===
 
<!-- Pod2Wiki=item_get_related_objects -->===get_related_objects===
Line 314: Line 390:
  
 
Returns a list of objects related to this object by @types.
 
Returns a list of objects related to this object by @types.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_remove_object_relations -->===remove_object_relations===
 
<!-- Pod2Wiki=item_remove_object_relations -->===remove_object_relations===
Line 320: Line 397:
  
 
Remove relations between this object and $target. If $has =&gt; $is pairs are defined will only remove those relationships given.
 
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.
 
You must commit $target after calling this method.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=head_undocumented_methods -->=UNDOCUMENTED METHODS=
 
<!-- Pod2Wiki=head_undocumented_methods -->=UNDOCUMENTED METHODS=

Revision as of 18:10, 11 August 2009

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.

DESCRIPTION

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

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

get_system_field_info

 $sys_fields = EPrints::DataObj->get_system_field_info

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

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.

new_from_data

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

Construct a new EPrints::DataObj object based on the $data hash reference of metadata.

Used to create an object from the data retrieved from the database.

get_defaults

 $defaults = EPrints::User->get_defaults( $session, $data, $dataset )

Return default values for this object based on the starting data.

Should be subclassed.

remove

 $success = $dataobj->remove

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

Return true if successful.

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 Database to avoid unnecessary commits.

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.

get_value

 $value = $dataobj->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).

set_value

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

Set the value of the named metadata field in this record.

get_values

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

get_session

 $session = $dataobj->get_session

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

get_data

 $data = $dataobj->get_data

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

get_dataset_id

 $dataset = EPrints::DataObj->get_dataset_id

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

get_dataset

 $dataset = $dataobj->get_dataset

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

is_set

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

exists_and_set

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

get_id

 $id = $dataobj->get_id

Returns the value of the primary key of this record.

get_gid

 $id = $dataobj->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.

get_datestamp

 $datestamp = $dataobj->get_datestamp

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

render_value

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

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 citiation will link to the specified URL.

render_citation_link

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

render_description

 $xhtml = $dataobj->render_description

Returns a short description of this object using the default citation style for this dataset.

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.

render_full

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

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

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.

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().

get_url

 $url = $dataobj->get_url

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

get_control_url

 $url = $dataobj->get_control_url

Returns the URL for the control page for this object.

get_type

 $type = $dataobj->get_type

Returns the type of this record - type of user, type of eprint etc.

to_xml

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

Convert this object into an XML fragment.

%opts are:

no_xmlns=>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=>1 : fields with no value are shown.

version=>"code" : pick what version of the EPrints XML format to use "1" or "2"

embed=>1 : include the data of a file, not just it's URL.

xml_to_epdata

 $epdata = EPrints::DataObj->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.

export

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

Apply an output plugin to this items. Return the results.

queue_changes

 $dataobj->queue_changes

Add all the changed fields into the indexers todo queue.

queue_all

 $dataobj->queue_all

Add all the fields into the indexers todo queue.

queue_fulltext

 $dataobj->queue_fulltext

Add a fulltext index into the indexers todo queue.

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 dataobjs, except those which override this method.

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 a scope AND a priv can edit.

validate

 $problems = $dataobj->validate( [ $for_archive ], $workflow_id )

Return a reference to an array of XHTML DOM objects describing validation 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.

get_warnings

 $warnings = $dataobj->get_warnings( )

Return a reference to an array of XHTML DOM objects describing problems with the entire $dataobj.

A reference to an empty array indicates no problems.

add_stored_file

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

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.

Returns the file object or undef if the storage failed.

get_stored_file

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

Get the file object for $filename.

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

Related Objects

add_object_relations

 $dataobj->add_object_relations( $target, $has => $is [, $has => $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.

has_object_relations

 $bool = $dataobj->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.

has_related_objects

 $bool = $dataobj->has_related_objects( @types )

Returns true if get_related_objects() would return some objects, but without actually retrieving the related objects from the database.

get_related_objects

 $dataobjs = $dataobj->get_related_objects( @types )

Returns a list of objects related to this object by @types.

remove_object_relations

 $dataobj->remove_object_relations( $target [, $has => $is [, $has => $is ] )

Remove relations between this object and $target. If $has => $is pairs are defined will only remove those relationships given.

You must commit $target after calling this method.

UNDOCUMENTED METHODS

Warning These methods were found in the source code but didn't have any POD associated with them. This may be because we haven't got around to documenting them yet or it could be because they are internal to the API and not intended for use by other parts of EPrints.

clone

create

create_from_data

get_value_raw

render_citation_link_staff

set_under_construction

set_value_raw

tidy

under_construction

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

validate_field