Difference between revisions of "API:EPrints/DataObj"

From EPrints Documentation
Jump to: navigation, search
(Removing all content from page)
Line 1: Line 1:
<!-- 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.
 
-->{{Pod2Wiki}}{{API:Source|file=EPrints/DataObj.pm|package_name=EPrints::DataObj}}[[Category:API|DataObj]]<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=head_name -->=NAME=
 
'''EPrints::DataObj''' - Base class for records in EPrints.
 
  
<!-- 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
 
 
ABSTRACT.
 
 
Return an array describing the system metadata of the this  dataset.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_new -->==new==
 
 
  $dataobj = EPrints::DataObj-&gt;new( $session, $id, [$dataset] )
 
 
ABSTRACT.
 
 
Return new data object, created by loading it from the database.
 
 
$dataset is used by EPrint-&gt;new to save searching through all four tables that it could be in.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_new_from_data -->==new_from_data==
 
 
  $dataobj = EPrints::DataObj-&gt;new_from_data( $session, $data, $dataset )
 
 
ABSTRACT.
 
 
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.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_defaults -->==get_defaults==
 
 
  $defaults = EPrints::User-&gt;get_defaults( $session, $data )
 
 
Return default values for this object based on the starting data.
 
 
Should be subclassed.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_remove -->==remove==
 
 
  $success = $dataobj-&gt;remove
 
 
ABSTRACT
 
 
Remove this data object from the database.
 
 
Also removes any sub-objects or related files.
 
 
Return true if successful.
 
 
<!-- End of Pod2Wiki -->
 
<!-- 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 Database to avoid unnecessary commits.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_commit -->==commit==
 
 
  $success = $dataobj-&gt;commit( [$force] )
 
 
ABSTRACT.
 
 
Write this object to the database.
 
 
If $force isn't true then it only actually modifies the database if one or more fields have been changed.
 
 
Commit may also log the changes, depending on the type of data  object.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_value -->==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).
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_set_value -->==set_value==
 
 
  $dataobj-&gt;set_value( $fieldname, $value )
 
 
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 )
 
 
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.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_session -->==get_session==
 
 
  $session = $dataobj-&gt;get_session
 
 
Returns the EPrints::Session object to which this record belongs.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_data -->==get_data==
 
 
  $data = $dataobj-&gt;get_data
 
 
Returns a reference to the hash table of all the metadata for this record keyed  by fieldname.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_dataset -->==get_dataset==
 
 
  $dataset = $dataobj-&gt;get_dataset
 
 
Returns the EPrints::DataSet object to which this record belongs.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_is_set -->==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.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_exists_and_set -->==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.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_id -->==get_id==
 
 
  $id = $dataobj-&gt;get_id
 
 
Returns the value of the primary key of this record.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_gid -->==get_gid==
 
 
  $id = $dataobj-&gt;get_gid
 
 
Returns the globally referential fully-qualified identifier for this object or undef if this object can not be externally referenced.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_value -->==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.
 
 
<!-- End of Pod2Wiki -->
 
<!-- 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 $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 -->
 
<!-- Pod2Wiki=item_render_citation_link -->==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.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_description -->==render_description==
 
 
  $xhtml = $dataobj-&gt;render_description
 
 
Returns a short description of this object using the default citation style for this dataset.
 
 
<!-- End of Pod2Wiki -->
 
<!-- 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.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_full -->==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.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_uri -->==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.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_url -->==get_url==
 
 
  $url = $dataobj-&gt;get_url
 
 
Returns the URL for this record, for example the URL of the abstract page of an eprint.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_control_url -->==get_control_url==
 
 
  $url = $dataobj-&gt;get_control_url
 
 
Returns the URL for the control page for this object.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_type -->==get_type==
 
 
  $type = $dataobj-&gt;get_type
 
 
Returns the type of this record - type of user, type of eprint etc.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_to_xml -->==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.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_export -->==export==
 
 
  $plugin_output = $detaobj-&gt;export( $plugin_id, %params )
 
 
Apply an output plugin to this items. Return the results.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_queue_changes -->==queue_changes==
 
 
  $dataobj-&gt;queue_changes
 
 
Add all the changed fields into the indexers todo queue.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_queue_all -->==queue_all==
 
 
  $dataobj-&gt;queue_all
 
 
Add all the fields into the indexers todo queue.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_has_owner -->==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.
 
 
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 )
 
 
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.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=head_undocumented_methods -->=UNDOCUMENTED METHODS=
 
{{API:Undocumented Methods}}<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_create -->==create==
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_create_from_data -->==create_from_data==
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_value_raw -->==get_value_raw==
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_citation_link_staff -->==render_citation_link_staff==
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_set_under_construction -->==set_under_construction==
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_set_value_raw -->==set_value_raw==
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_tidy -->==tidy==
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_under_construction -->==under_construction==
 
 
<!-- End of Pod2Wiki -->
 
 
$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=item_validate_field -->==validate_field==
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=_postamble_ --><!-- End of Pod2Wiki -->
 

Revision as of 15:40, 12 August 2009