Difference between revisions of "API:EPrints/DataObj"
Line 8: | Line 8: | ||
'''EPrints::DataObj''' - Base class for records in EPrints. | '''EPrints::DataObj''' - Base class for records in EPrints. | ||
− | |||
− | |||
<!-- Edit below this comment --> | <!-- Edit below this comment --> | ||
<!-- Pod2Wiki= --> | <!-- Pod2Wiki= --> | ||
− | |||
<!-- Pod2Wiki=head_synopsis --> | <!-- Pod2Wiki=head_synopsis --> | ||
==SYNOPSIS== | ==SYNOPSIS== | ||
Line 49: | Line 46: | ||
$dataobj = $dataobj->create_subobject( $fieldname, $epdata ); | $dataobj = $dataobj->create_subobject( $fieldname, $epdata ); | ||
− | |||
− | |||
<!-- Edit below this comment --> | <!-- Edit below this comment --> | ||
<!-- Pod2Wiki= --> | <!-- Pod2Wiki= --> | ||
− | |||
<!-- Pod2Wiki=head_description --> | <!-- Pod2Wiki=head_description --> | ||
==DESCRIPTION== | ==DESCRIPTION== | ||
Line 62: | Line 56: | ||
It is ABSTRACT - its methods should not be called directly. | It is ABSTRACT - its methods should not be called directly. | ||
− | |||
− | |||
<!-- Edit below this comment --> | <!-- Edit below this comment --> | ||
<!-- Pod2Wiki= --> | <!-- Pod2Wiki= --> | ||
− | + | * $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. | |
− | |||
+ | <pre> 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 );</pre> | ||
− | + | * $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. | ||
− | < | + | <pre> f70ef731-be66-50f4-8e72-8b8de36778b5</pre> |
− | </ | ||
− | |||
− | |||
− | + | : 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'''. | |
− | < | + | : <code>uuid_namespace</code> is a configuration variable. If <code>uuid_namespace</code> is undefined uses <code>base_url</code>: |
− | < | ||
− | < | ||
+ | <pre> # Note: deliberate typo to prevent copy-and-paste | ||
+ | $c->{uuid_namespace} = "http://your-repository's url"";</pre> | ||
− | + | : Returns the formatted UUID. | |
− | |||
− | |||
− | |||
− | Returns | + | * $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 ] ) | |
+ | <pre> # current user can edit via editorial role | ||
+ | if( $dataobj->permit( "xxx/edit", $user ) & 8 ) | ||
+ | { | ||
+ | ... | ||
+ | } | ||
+ | # anyone can view this object | ||
+ | if( $dataobj->permit( "xxx/view" ) ) | ||
+ | { | ||
+ | }</pre> | ||
− | + | : Returns true if the current user (or 'anybody') can perform this action. | |
− | + | : Returns a bit mask where: | |
− | < | + | <pre> 0 - not permitted |
− | + | 1 - anybody | |
− | + | 2 - logged in user | |
+ | 4 - user as owner | ||
+ | 8 - user as editor</pre> | ||
+ | : See also [[API:EPrints/Repository#allow_anybody|EPrints::Repository/allow_anybody]] and [[API:EPrints/DataObj/User#allow|EPrints::DataObj::User/allow]]. | ||
− | + | * $list = $dataobj->duplicates() | |
− | + | : Return a conservative list of other objects that look like this one. | |
− | |||
− | |||
− | + | <!-- Pod2Wiki=head_copyright --> | |
+ | ==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/. | |
− | |||
− | |||
<!-- Edit below this comment --> | <!-- Edit below this comment --> | ||
<!-- Pod2Wiki= --> | <!-- Pod2Wiki= --> | ||
− | + | <!-- Pod2Wiki=_postamble_ --> | |
− | <!-- Pod2Wiki= | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
<!-- Edit below this comment --> | <!-- 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
Latest Source Code (3.4, 3.3) | Revision Log | Before editing this page please read Pod2Wiki
Contents
NAME
EPrints::DataObj - Base class for records in EPrints.
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. Ifuuid_namespace
is undefined usesbase_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
- $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/.