API:EPrints/DataObj

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.

User Comments

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.

User Comments

$sys_fields = EPrints::DataObj->get_system_field_info

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

User Comments

$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

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

User Comments

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

Creates and returns a new dataobj 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

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

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

Should be subclassed.

User Comments

$success = $dataobj->remove

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

Return true if successful.

User Comments

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

User Comments

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

User Comments

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

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

User Comments

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

User Comments

$session = $dataobj->get_session

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

User Comments

$data = $dataobj->get_data

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

User Comments

$dataset = EPrints::DataObj->get_dataset_id

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

User Comments

$dataset = $dataobj->get_dataset

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

User Comments

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

User Comments

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

User Comments

$id = $dataobj->get_id

Returns the value of the primary key of this record.

User Comments

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

User Comments

$datestamp = $dataobj->get_datestamp

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

User Comments

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

User Comments

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

User Comments

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

User Comments

$xhtml = $dataobj->render_description

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

User Comments

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

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

User Comments

$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

$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

$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

$url = $dataobj->get_url

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

User Comments

$url = $dataobj->get_control_url

Returns the URL for the control page for this object.

User Comments

$type = $dataobj->get_type

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

User Comments

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

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

User Comments

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

User Comments

$dataobj->to_sax( Handler => $handler, %opts )

Stream this object to a SAX handler.

This does not output any document-level events.

User Comments

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

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

See /start_element.

User Comments

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

See /start_element.

User Comments

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

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

User Comments

$dataobj->queue_changes

Add all the changed fields into the indexers todo queue.

User Comments

$dataobj->queue_all

Add all the fields into the indexers todo queue.

User Comments

$dataobj->queue_fulltext

Add a fulltext index into the indexers todo queue.

User Comments

$dataobj->queue_removed()

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

User Comments

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

User Comments

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

User Comments

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

User Comments

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

User Comments

$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

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

Get the file object for $filename.

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

User Comments

Related Objects

User Comments

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

User Comments

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

User Comments

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

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

User Comments

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

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

User Comments

$dataobj->remove_dataobj_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 this object and $target to write the changes.

User Comments