Difference between revisions of "API:EPrints/DataObj/Document"
| Line 5: | Line 5: | ||
<!-- Pod2Wiki=_private_ --><!-- Pod2Wiki=head_name --> | <!-- Pod2Wiki=_private_ --><!-- Pod2Wiki=head_name --> | ||
| − | ==NAME | + | ==NAME== |
| − | |||
| − | == | ||
'''EPrints::DataObj::Document''' - A single format of a record. | '''EPrints::DataObj::Document''' - A single format of a record. | ||
| Line 18: | Line 16: | ||
</div> | </div> | ||
<!-- Pod2Wiki=head_description --> | <!-- Pod2Wiki=head_description --> | ||
| − | ==DESCRIPTION | + | ==DESCRIPTION== |
| − | + | Document represents a single format of an EPrint (eg. PDF) - the actual file(s) rather than the metadata. | |
| − | == | ||
| − | Document represents a single format of an EPrint (eg. PDF) - the | ||
| − | actual file(s) rather than the metadata. | ||
| − | Inherits from [[API:EPrints/DataObj/SubObject|EPrints::DataObj::SubObject]], which in turn inherits | + | Inherits from [[API:EPrints/DataObj/SubObject|EPrints::DataObj::SubObject]], which in turn inherits from [[API:EPrints/DataObj|EPrints::DataObj]]. |
| − | |||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 35: | Line 29: | ||
</div> | </div> | ||
<!-- Pod2Wiki=head_instance_variables --> | <!-- Pod2Wiki=head_instance_variables --> | ||
| − | ==INSTANCE VARIABLES | + | ==INSTANCE VARIABLES== |
| − | |||
| − | == | ||
See [[API:EPrints/DataObj#INSTANCE_VARIABLES|EPrints::DataObj#INSTANCE_VARIABLES]]. | See [[API:EPrints/DataObj#INSTANCE_VARIABLES|EPrints::DataObj#INSTANCE_VARIABLES]]. | ||
| Line 48: | Line 40: | ||
</div> | </div> | ||
<!-- Pod2Wiki=head_core_metadata_fields --> | <!-- Pod2Wiki=head_core_metadata_fields --> | ||
| − | ==CORE METADATA FIELDS | + | ==CORE METADATA FIELDS== |
| − | |||
| − | == | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <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> | <span style='display:none'>User Comments</span> | ||
| Line 59: | Line 49: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_docid --> | <!-- Pod2Wiki=item_docid --> | ||
| − | ===docid (int) | + | ===docid (int)=== |
| − | |||
| − | === | ||
The unique ID of the document. | The unique ID of the document. | ||
| Line 73: | Line 61: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_rev_number --> | <!-- Pod2Wiki=item_rev_number --> | ||
| − | ===rev_number (int) | + | ===rev_number (int)=== |
| − | |||
| − | === | ||
The revision number of this document record. | The revision number of this document record. | ||
| Line 87: | Line 73: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_pos --> | <!-- Pod2Wiki=item_pos --> | ||
| − | ===pos (int) | + | ===pos (int)=== |
| − | + | The position of the document record within those associated with the eprint. | |
| − | |||
| − | The position of the document record within those associated with the | ||
| − | eprint. | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 102: | Line 85: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_placement --> | <!-- Pod2Wiki=item_placement --> | ||
| − | ===placement (int) | + | ===placement (int)=== |
| − | + | Placement of the document - the order documents in which should be shown. This may be different to <tt>pos</tt>, as the <tt>ultimate_doc_pos</tt> may lead to a different ordering. | |
| − | |||
| − | Placement of the document - the order documents in which should be | ||
| − | shown. This may be different to <tt>pos</tt>, as the <tt>ultimate_doc_pos</tt> | ||
| − | may lead to a different ordering. | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 118: | Line 97: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_format --> | <!-- Pod2Wiki=item_format --> | ||
| − | ===format (namedset) | + | ===format (namedset)=== |
| − | + | The format of this document. One of the types of the namedset c<document>. | |
| − | |||
| − | The format of this document. One of the types of the namedset | ||
| − | |||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 133: | Line 109: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_formatdesc --> | <!-- Pod2Wiki=item_formatdesc --> | ||
| − | ===formatdesc (text) | + | ===formatdesc (text)=== |
| − | |||
| − | === | ||
| − | An additional description of this document. For example the specific | + | An additional description of this document. For example the specific version of a format. |
| − | version of a format. | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 148: | Line 121: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_language --> | <!-- Pod2Wiki=item_language --> | ||
| − | ===language (namedset) | + | ===language (namedset)=== |
| − | |||
| − | === | ||
| − | The ISO 639-1 code of the language of this document. The default | + | The ISO 639-1 code of the language of this document. The default configuration of EPrints does not set this. |
| − | configuration of EPrints does not set this. | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 163: | Line 133: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_security --> | <!-- Pod2Wiki=item_security --> | ||
| − | ===security (namedset) | + | ===security (namedset)=== |
| − | + | The security type of this document - who can view it. One of the types of the namedset <tt>security</tt>. | |
| − | |||
| − | The security type of this document - who can view it. One of the | ||
| − | types of the namedset <tt>security</tt>. | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 178: | Line 145: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_license --> | <!-- Pod2Wiki=item_license --> | ||
| − | ===license (namedset) | + | ===license (namedset)=== |
| − | |||
| − | === | ||
| − | The license applied of this document - who can view it. One of the | + | The license applied of this document - who can view it. One of the types of the namedset <tt>license</tt>. |
| − | types of the namedset <tt>license</tt>. | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 193: | Line 157: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_main --> | <!-- Pod2Wiki=item_main --> | ||
| − | ===main (text) | + | ===main (text)=== |
| − | |||
| − | === | ||
| − | The file which we should link to. For something like a PDF file this is | + | The file which we should link to. For something like a PDF file this is the only file. For an HTML document with images it would be the name of the actual HTML file. |
| − | |||
| − | |||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 209: | Line 169: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_date_embargo --> | <!-- Pod2Wiki=item_date_embargo --> | ||
| − | ===date_embargo (date) | + | ===date_embargo (date)=== |
| − | |||
| − | === | ||
| − | The date until which the document has restricted access (set by | + | The date until which the document has restricted access (set by <tt>security</tt>). At which point the embargo is lifted and <tt>security</tt> is set to <tt>public</tt> and this field set back to <tt>undef</tt>. |
| − | <tt>security</tt>). At which point the embargo is lifted and <tt>security</tt> | ||
| − | |||
Requires <tt>bin/lift_embargos</tt> script to be deployed as a cron job. | Requires <tt>bin/lift_embargos</tt> script to be deployed as a cron job. | ||
| Line 227: | Line 183: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_date_embargo_retained --> | <!-- Pod2Wiki=item_date_embargo_retained --> | ||
| − | ===date_embargo_retained (date) | + | ===date_embargo_retained (date)=== |
| − | |||
| − | === | ||
| − | The retained date of any embargo originally placed on this document. | + | The retained date of any embargo originally placed on this document. This is updated when a user modifies <tt>date_embargo</tt> but is not unset by the <tt>bin/lift_embargos</tt> script. |
| − | |||
| − | |||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 243: | Line 195: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_media --> | <!-- Pod2Wiki=item_media --> | ||
| − | ===media (compound) | + | ===media (compound)=== |
| − | |||
| − | === | ||
A compound field containing a description of the document media - dimensions, codec etc. | A compound field containing a description of the document media - dimensions, codec etc. | ||
| Line 257: | Line 207: | ||
</div> | </div> | ||
<!-- Pod2Wiki=head_references_and_related_objects --> | <!-- Pod2Wiki=head_references_and_related_objects --> | ||
| − | ==REFERENCES AND RELATED OBJECTS | + | ==REFERENCES AND 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%; '> | <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> | <span style='display:none'>User Comments</span> | ||
| Line 268: | Line 216: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_eprintid --> | <!-- Pod2Wiki=item_eprintid --> | ||
| − | ===eprintid (itemref) | + | ===eprintid (itemref)=== |
| − | |||
| − | === | ||
The ID number of the eprint to which this document belongs. | The ID number of the eprint to which this document belongs. | ||
| Line 282: | Line 228: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_files --> | <!-- Pod2Wiki=item_files --> | ||
| − | ===files (subobject, multiple) | + | ===files (subobject, multiple)=== |
| − | + | A virtual field which represents the list of files which are part of this record. | |
| − | |||
| − | A virtual field which represents the list of files which are part of | ||
| − | |||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 297: | Line 240: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_relation --> | <!-- Pod2Wiki=item_relation --> | ||
| − | ===relation (relation, multiple) | + | ===relation (relation, multiple)=== |
| − | + | Predicated relationships between this document and other data objects within the archive. | |
| − | |||
| − | Predicated relationships between this document and other data objects | ||
| − | |||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 312: | Line 252: | ||
</div> | </div> | ||
<!-- Pod2Wiki=head_methods --> | <!-- Pod2Wiki=head_methods --> | ||
| − | ==METHODS | + | ==METHODS== |
| − | |||
| − | == | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <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> | <span style='display:none'>User Comments</span> | ||
| Line 323: | Line 261: | ||
</div> | </div> | ||
<!-- Pod2Wiki=head_constructor_methods --> | <!-- Pod2Wiki=head_constructor_methods --> | ||
| − | ===Constructor Methods | + | ===Constructor Methods=== |
| − | |||
| − | === | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <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> | <span style='display:none'>User Comments</span> | ||
| Line 336: | Line 272: | ||
====create==== | ====create==== | ||
| − | $doc = EPrints::DataObj::Document::create( $session, $eprint ) | + | $doc = EPrints::DataObj::Document::create( $session, $eprint ) |
| − | + | Create and return a new document belonging to the given <tt>$eprint</tt> object. | |
| − | Create and return a new document belonging to the given <tt>$eprint</tt> | ||
| − | object. | ||
N.B. This creates the document in the database, not just in memory. | N.B. This creates the document in the database, not just in memory. | ||
| Line 354: | Line 288: | ||
$dataobj = EPrints::DataObj::Document::create_from_data( $session, $data, $dataset ) | $dataobj = EPrints::DataObj::Document::create_from_data( $session, $data, $dataset ) | ||
| − | |||
Create document data object from <tt>$data</tt> provided. | Create document data object from <tt>$data</tt> provided. | ||
| Line 369: | Line 302: | ||
</div> | </div> | ||
<!-- Pod2Wiki=head_class_methods --> | <!-- Pod2Wiki=head_class_methods --> | ||
| − | ===Class Methods | + | ===Class Methods=== |
| − | |||
| − | === | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <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> | <span style='display:none'>User Comments</span> | ||
| Line 383: | Line 314: | ||
$fields = EPrints::DataObj::Document->get_system_field_info | $fields = EPrints::DataObj::Document->get_system_field_info | ||
| − | + | Returns an array describing the system metadata of the document dataset. | |
| − | Returns an array describing the system metadata of the document | ||
| − | dataset. | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 398: | Line 327: | ||
$defaults = EPrints::DataObj::Document->get_defaults( $session, $data, $dataset ) | $defaults = EPrints::DataObj::Document->get_defaults( $session, $data, $dataset ) | ||
| − | + | Returns default values for this data object based on the starting <tt>$data</tt>. | |
| − | Returns default values for this data object based on the starting | ||
| − | <tt>$data</tt>. | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 413: | Line 340: | ||
$dataset = EPrints::DataObj::Document->get_dataset_id | $dataset = EPrints::DataObj::Document->get_dataset_id | ||
| − | + | 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. | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 428: | Line 353: | ||
$dataset_id = EPrints::DataObj::Document->get_parent_dataset_id | $dataset_id = EPrints::DataObj::Document->get_parent_dataset_id | ||
| − | |||
Returns the ID of the parent dataset for a document, (i.e. <tt>eprint</tt>). | Returns the ID of the parent dataset for a document, (i.e. <tt>eprint</tt>). | ||
| Line 439: | Line 363: | ||
</div> | </div> | ||
<!-- Pod2Wiki=head_object_methods --> | <!-- Pod2Wiki=head_object_methods --> | ||
| − | ===Object Methods | + | ===Object Methods=== |
| − | |||
| − | === | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <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> | <span style='display:none'>User Comments</span> | ||
| Line 453: | Line 375: | ||
$newdoc = $doc->clone( $eprint ) | $newdoc = $doc->clone( $eprint ) | ||
| − | + | Attempt to clone this document. Both the document metadata and the actual files. The clone will be associated with the given <tt>$eprint</tt>. | |
| − | Attempt to clone this document. Both the document metadata and the | ||
| − | |||
Returns to the newly colument document. | Returns to the newly colument document. | ||
| Line 470: | Line 390: | ||
$success = $doc->remove | $success = $doc->remove | ||
| − | + | Attempt to completely delete this document. Including derived documents such as thumbnails. | |
| − | Attempt to completely delete this document. Including derived | ||
| − | documents such as thumbnails. | ||
Returns boolean dependent on success of deleting document. | Returns boolean dependent on success of deleting document. | ||
| Line 487: | Line 405: | ||
$eprint = $doc->get_eprint | $eprint = $doc->get_eprint | ||
| − | |||
Returns the eprint this document is associated with. | Returns the eprint this document is associated with. | ||
| Line 493: | Line 410: | ||
$doc->get_parent | $doc->get_parent | ||
| − | + | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <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> | <span style='display:none'>User Comments</span> | ||
| Line 505: | Line 422: | ||
$url = $doc->get_baseurl | $url = $doc->get_baseurl | ||
| − | |||
Returns the base URL of the document. | Returns the base URL of the document. | ||
| Line 519: | Line 435: | ||
$boolean = $doc->is_public | $boolean = $doc->is_public | ||
| − | + | Returnes <tt>true</tt> if this document has no security set and is in the live archive. Otherwise, returns <tt>false</tt>. | |
| − | Returnes <tt>true</tt> if this document has no security set and is in the | ||
| − | live archive. Otherwise, returns <tt>false</tt>. | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 534: | Line 448: | ||
$path = $doc->path | $path = $doc->path | ||
| − | |||
Returns the relative path to the document without specifying any file. | Returns the relative path to the document without specifying any file. | ||
| Line 548: | Line 461: | ||
$path = $doc->file_path( [ $file ] ) | $path = $doc->file_path( [ $file ] ) | ||
| − | + | Returns the relative path to <tt>$file</tt> stored in this document. If <tt>$file</tt> is undefined returns the path to the main file. | |
| − | Returns the relative path to <tt>$file</tt> stored in this document. | ||
| − | If <tt>$file</tt> is undefined returns the path to the main file. | ||
This is an efficient shortcut to this: | This is an efficient shortcut to this: | ||
| Line 556: | Line 467: | ||
my $file = $doc->stored_file( $filename ); | my $file = $doc->stored_file( $filename ); | ||
my $path = $file->path; | my $path = $file->path; | ||
| − | + | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <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> | <span style='display:none'>User Comments</span> | ||
| Line 568: | Line 479: | ||
$url = $doc->get_url( [ $file ] ) | $url = $doc->get_url( [ $file ] ) | ||
| − | |||
Returns the full URL of the document. | Returns the full URL of the document. | ||
| Line 584: | Line 494: | ||
$path = $doc->local_path | $path = $doc->local_path | ||
| − | |||
DEPRECATED. | DEPRECATED. | ||
| − | Returns the full path of the directory where this document is stored | + | Returns the full path of the directory where this document is stored in the filesystem. |
| − | |||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 601: | Line 509: | ||
%files = $doc->files | %files = $doc->files | ||
| − | + | Returns a hash, the keys of which are all the files belonging to this document (relative to [[API:EPrints/DataObj/Document#local_path|local_path]]). The values are the sizes of the files in bytes. | |
| − | Returns a hash, the keys of which are all the files belonging to this | ||
| − | |||
| − | files in bytes. | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 617: | Line 522: | ||
$success = $doc->remove_file( $filename ) | $success = $doc->remove_file( $filename ) | ||
| − | + | Attempts to remove the file with <tt>$filename</tt>. <tt>$filename</tt> must be specified in the format that can be retrieved by [[API:EPrints/DataObj/Document#get_stored_file|get_stored_file]]. | |
| − | Attempts to remove the file with <tt>$filename</tt>. <tt>$filename</tt> must be | ||
| − | specified in the format that can be retrieved by [[API:EPrints/DataObj/Document#get_stored_file|get_stored_file]]. | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 632: | Line 535: | ||
$doc->set_main( $main_file ) | $doc->set_main( $main_file ) | ||
| − | + | Sets <tt>main</tt> for the document to the named <tt>$main_file</tt> and adjusts <tt>format</tt> and <tt>mime_type</tt> as necessary. Will not affect the database until the document is committed. | |
| − | Sets <tt>main</tt> for the document to the named <tt>$main_file</tt> and adjusts | ||
| − | <tt>format</tt> and <tt>mime_type</tt> as necessary. Will not affect the database | ||
| − | until the document is committed. | ||
Unsets <tt>main</tt> if <tt>$main_file</tt> is undefined. | Unsets <tt>main</tt> if <tt>$main_file</tt> is undefined. | ||
| Line 650: | Line 550: | ||
$filename = $doc->get_main | $filename = $doc->get_main | ||
| − | |||
Returns the filename of the file set as <tt>main</tt> in this document. | Returns the filename of the file set as <tt>main</tt> in this document. | ||
| Line 664: | Line 563: | ||
$doc->set_format( $format ) | $doc->set_format( $format ) | ||
| − | + | Set format for document to <tt>$format</tt>. Will not affect the database until document is committed. | |
| − | Set format for document to <tt>$format</tt>. Will not affect the database | ||
| − | until document is committed. | ||
Alias for: | Alias for: | ||
$doc->set_value( "format" , $format ); | $doc->set_value( "format" , $format ); | ||
| − | + | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <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> | <span style='display:none'>User Comments</span> | ||
| Line 683: | Line 580: | ||
$doc->set_format_desc( $format_desc ) | $doc->set_format_desc( $format_desc ) | ||
| − | + | Set format description for document to <tt>$format_desc</tt>. Will not affect the database until document is committed. | |
| − | Set format description for document to <tt>$format_desc</tt>. Will not | ||
| − | affect the database until document is committed. | ||
Alias for: | Alias for: | ||
$doc->set_value( "format_desc" , $format_desc ); | $doc->set_value( "format_desc" , $format_desc ); | ||
| − | + | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <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> | <span style='display:none'>User Comments</span> | ||
| Line 702: | Line 597: | ||
$success = $doc->upload( $filehandle, $filename, [ $preserve_path, $filesize ] ) | $success = $doc->upload( $filehandle, $filename, [ $preserve_path, $filesize ] ) | ||
| + | DEPRECATED - Use [[API:EPrints/DataObj/Document#add_file|add_file]], which will automatically identify the file type. | ||
| − | + | Upload the contents of the given <tt>$filehandle</tt> into this document as the given <tt>$filename</tt>. | |
| − | |||
| − | |||
| − | Upload the contents of the given <tt>$filehandle</tt> into this document as | ||
| − | |||
| − | If <tt>$preserve_path</tt> then make any subdirectories needed, otherwise | + | If <tt>$preserve_path</tt> then make any subdirectories needed, otherwise place this in the top level directory. |
| − | place this in the top level directory. | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 723: | Line 614: | ||
$fileobj = $doc->add_file( $file, $filename, [ $preserve_path ] ) | $fileobj = $doc->add_file( $file, $filename, [ $preserve_path ] ) | ||
| + | <tt>$file</tt> is the full path to a file to be added to the document, with name <tt>$filename</tt>. <tt>$filename</tt> is passed through [[API:EPrints/System#sanitise|EPrints::System#sanitise]] before being written. | ||
| − | + | If <tt>$preserve_path</tt> is <tt>tru</tt>e then include path components in <tt>$filename</tt>. | |
| − | |||
| − | |||
| − | |||
| − | If <tt>$preserve_path</tt> is <tt>tru</tt>e then include path components in | ||
| − | <tt>$filename</tt>. | ||
| − | Returns the file object if successfully created or <tt>undef</tt> on | + | Returns the file object if successfully created or <tt>undef</tt> on failure. |
| − | failure. | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 745: | Line 631: | ||
$success = $doc->upload_archive( $filehandle, $filename, $archive_format ) | $success = $doc->upload_archive( $filehandle, $filename, $archive_format ) | ||
| − | |||
DEPRECATED - use [[API:EPrints/DataObj/Document#add_archive|add_archive]]. | DEPRECATED - use [[API:EPrints/DataObj/Document#add_archive|add_archive]]. | ||
| − | Upload the file contents provided through <tt>$filehandle</tt> using the | + | Upload the file contents provided through <tt>$filehandle</tt> using the filename from <tt>$filename</tt>. How to deal with the specified <tt>$archive_format</tt> (e.g. <tt>.zip</tt>, <tt>.tar.gz</tt>) is configured in [[API:EPrints/SystemSettings|EPrints::SystemSettings]]. |
| − | |||
| − | <tt>$archive_format</tt> (e.g. <tt>.zip</tt>, <tt>.tar.gz</tt>) is configured in | ||
| − | [[API:EPrints/SystemSettings|EPrints::SystemSettings]]. | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 764: | Line 646: | ||
$success = $doc->add_archive( $file, $archive_format ) | $success = $doc->add_archive( $file, $archive_format ) | ||
| + | Adds the contents of that archive <tt>$file</tt> to the document, where <tt>$archive_format</tt> is the format of the archive file (e.g. <tt>.zip</tt>, <tt>.tar.gz</tt>, etc.) | ||
| − | + | Returns a boolean dependent on whether the contents of the archive file is added to the document's subdirectory on the filesystem. | |
| − | |||
| − | |||
| − | |||
| − | Returns a boolean dependent on whether the contents of the archive | ||
| − | file is added to the document's subdirectory on the filesystem. | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 783: | Line 661: | ||
$success = $doc->add_directory( $directory ) | $success = $doc->add_directory( $directory ) | ||
| − | + | Upload the contents of <tt>$directory</tt> to this document. This will not set the document's <tt>main</tt> field. | |
| − | Upload the contents of <tt>$directory</tt> to this document. This will not | ||
| − | set the document's <tt>main</tt> field. | ||
This method expects <tt>$directory</tt> to have a trailing slash <tt>/</tt>. | This method expects <tt>$directory</tt> to have a trailing slash <tt>/</tt>. | ||
| Line 802: | Line 678: | ||
$success = $doc->upload_url( $url ) | $success = $doc->upload_url( $url ) | ||
| + | Attempts to grab files from the given <tt>$url</tt> over HTTP. Grabbing files this way is always problematic. Therefore, by default, only relative links will be followed and only links to files in the same directory or subdirectory will be followed. | ||
| − | + | This method by default uses {{API:PodLink|file=https:|package_name=https:|section=|text=wget}}. However, you can modify this in [[API:EPrints/SystemSettings|EPrints::SystemSettings]]. | |
| − | |||
| − | |||
| − | |||
| − | + | Returns a boolean dependent of whether file(s) were successfully uploaded. | |
| − | |||
| − | |||
| − | Returns a boolean dependent of whether file(s) were successfully | ||
| − | |||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 825: | Line 695: | ||
$success = $doc->commit( [ $force ] ) | $success = $doc->commit( [ $force ] ) | ||
| + | Commit any changes that have been made to this data object to the database. | ||
| − | + | Calls <tt>set_document_automatic_fields</tt> in the archive's configuration first to set any automatic fields that may be needed. | |
| − | |||
| − | + | If <tt>$force</tt> is defined and <tt>true</tt> then still commit even if there are no non-volatile changes. | |
| − | |||
| − | + | Returns boolean depending on whether commit of document data object is successful. | |
| − | |||
| − | |||
| − | Returns boolean depending on whether commit of document data object is | ||
| − | |||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 849: | Line 714: | ||
@derived_docs = $doc->get_derived_versions | @derived_docs = $doc->get_derived_versions | ||
| − | + | Returns an array of documents that are derived from the current document through the <tt>isVersionOf</tt> relation. | |
| − | Returns an array of documents that are derived from the current | ||
| − | |||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 864: | Line 727: | ||
$problems = $doc->validate( [ $for_archive ] ) | $problems = $doc->validate( [ $for_archive ] ) | ||
| + | Validates the document data object. If <tt>$for_archive</tt> is defined this will be passed through to the archive configured <tt>validate_document</tt> method, in case it is required for bespoke changes to this method. | ||
| − | + | Returns a reference to an array of XHTML DOM objects describing validation problems with the entire document, including the metadata and repository config specific requirements. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | Returns a reference to an array of XHTML DOM objects describing | ||
| − | validation problems with the entire document, including the metadata | ||
| − | and repository config specific requirements. | ||
A returned reference to an empty array indicates no problems. | A returned reference to an empty array indicates no problems. | ||
| Line 887: | Line 744: | ||
$boolean = $doc->user_can_view( $user ) | $boolean = $doc->user_can_view( $user ) | ||
| − | + | Returns <tt>true</tt> if this document's security settings allow the given <tt>$user</tt> access to view it. | |
| − | Returns <tt>true</tt> if this document's security settings allow the given | ||
| − | <tt>$user</tt> access to view it. | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 902: | Line 757: | ||
$type = $doc->get_type | $type = $doc->get_type | ||
| − | |||
Returns the type of this document. | Returns the type of this document. | ||
| Line 908: | Line 762: | ||
$doc->value( "format" ); | $doc->value( "format" ); | ||
| − | + | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <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> | <span style='display:none'>User Comments</span> | ||
| Line 920: | Line 774: | ||
$doc->queue_files_modified | $doc->queue_files_modified | ||
| − | + | Adds a <tt>files_modified</tt> task (e.g. for creating/updating thumbnails) to the event queue. | |
| − | Adds a <tt>files_modified</tt> task (e.g. for creating/updating thumbnails) | ||
| − | |||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 935: | Line 787: | ||
$doc->files_modified | $doc->files_modified | ||
| − | + | This method does all the things that need doing when a file has been modified. | |
| − | This method does all the things that need doing when a file has been | ||
| − | |||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 950: | Line 800: | ||
$doc->rehash | $doc->rehash | ||
| − | + | Recalculate the hash value of the document. Uses MD5 of the files (in alphabetic order), but can use user-specified hashing function instead. | |
| − | Recalculate the hash value of the document. Uses MD5 of the files (in | ||
| − | |||
| − | instead. | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 966: | Line 813: | ||
$indexcodes_doc = $doc->make_indexcodes | $indexcodes_doc = $doc->make_indexcodes | ||
| − | + | Make the index codes document for this document. Returns the generated index codes document on success or <tt>undef</tt> on failure. | |
| − | Make the index codes document for this document. Returns the generated | ||
| − | index codes document on success or <tt>undef</tt> on failure. | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 981: | Line 826: | ||
$doc = $doc->remove_indexcodes | $doc = $doc->remove_indexcodes | ||
| − | + | Remove any documents containing index codes for this document. Returns the number of documents removed. | |
| − | Remove any documents containing index codes for this document. | ||
| − | Returns the number of documents removed. | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 996: | Line 839: | ||
$filename = $doc->cache_file( $suffix ); | $filename = $doc->cache_file( $suffix ); | ||
| − | |||
DEPRECATED | DEPRECATED | ||
| Line 1,012: | Line 854: | ||
$doc->register_parent( $parent ) | $doc->register_parent( $parent ) | ||
| + | Registers the <tt>$parent</tt> [[API:EPrints/DataObj/EPrint|EPrints::DataObj::EPrint]] object for this document. | ||
| − | + | This may cause reference loops, but it does avoid two identical eprint data objects existing at once. | |
| − | |||
| − | |||
| − | This may cause reference loops, but it does avoid two identical | ||
| − | |||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 1,030: | Line 869: | ||
$doc->thumbnail_url( $size ) | $doc->thumbnail_url( $size ) | ||
| + | Returns the URL for the thumbnail of the document for a specified <tt>$size</tt>. If <tt>$size</tt> is unspecified defaults to <tt>small</tt>. Other values for <tt>$size</tt> include <tt>medium</tt> and <tt>preview</tt>. | ||
| − | Returns | + | Returns <tt>undef</tt> if file for particular type of thumbnail does not exist. |
| − | |||
| − | |||
| − | + | This method is called bt [[API:EPrints/DataObj/Document#icon_url|icon_url]]. It is best to use that method to reliably retrieve the required URL. | |
| − | |||
| − | |||
| − | This method is called bt [[API:EPrints/DataObj/Document#icon_url|icon_url]]. It is best to use that method | ||
| − | |||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 1,052: | Line 886: | ||
$doc->icon_url( $size ) | $doc->icon_url( $size ) | ||
| − | + | Returns the URL for the icon of the document for a specified <tt>$size</tt>. If <tt>$size</tt> is unspecified defaults to <tt>small</tt>. Other values for <tt>$size</tt> include <tt>medium</tt> and <tt>preview</tt>. | |
| − | Returns the URL for the icon of the document for a specified | ||
| − | |||
| − | |||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 1,068: | Line 899: | ||
$frag = $doc->render_icon_link( %opts ) | $frag = $doc->render_icon_link( %opts ) | ||
| − | |||
Render a link to the icon for this document. | Render a link to the icon for this document. | ||
| Line 1,074: | Line 904: | ||
new_window => 1 - Make link go to <tt>_blank</tt> not current window. | new_window => 1 - Make link go to <tt>_blank</tt> not current window. | ||
| − | + | ||
preview => 1 - If possible, provide a preview pop-up. | preview => 1 - If possible, provide a preview pop-up. | ||
| − | + | ||
public => 0 - Show thumbnail/preview only on public documents. | public => 0 - Show thumbnail/preview only on public documents. | ||
| − | + | ||
public => 1 - Show thumbnail/preview on all documents if possible. | public => 1 - Show thumbnail/preview on all documents if possible. | ||
| − | + | ||
with_link => 0 - Do not link. | with_link => 0 - Do not link. | ||
| − | + | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <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> | <span style='display:none'>User Comments</span> | ||
| Line 1,094: | Line 924: | ||
$frag = $doc->render_preview_link( %opts ) | $frag = $doc->render_preview_link( %opts ) | ||
| − | + | Render a link to the preview for this document (if available) using a lightbox. | |
| − | Render a link to the preview for this document (if available) using a | ||
| − | lightbox. | ||
Options: | Options: | ||
| Line 1,111: | Line 939: | ||
caption => $frag | caption => $frag | ||
| − | |||
XHTML fragment to use as the caption, defaults to empty. | XHTML fragment to use as the caption, defaults to empty. | ||
| Line 1,125: | Line 952: | ||
set => "name" | set => "name" | ||
| − | + | The name of the set this document belongs to, defaults to none (preview won't be shown as part of a set). | |
| − | The name of the set this document belongs to, defaults to none | ||
| − | (preview won't be shown as part of a set). | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 1,140: | Line 965: | ||
$plugin = $doc->thumbnail_plugin( $size ) | $plugin = $doc->thumbnail_plugin( $size ) | ||
| − | + | Returns the plugin used to generatee thumbnails of the specified <tt>$size</tt>. | |
| − | Returns the plugin used to generatee thumbnails of the specified | ||
| − | <tt>$size</tt>. | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 1,155: | Line 978: | ||
$path = $doc->thumbnail_path | $path = $doc->thumbnail_path | ||
| − | |||
DEPRECATED | DEPRECATED | ||
| − | Returns the filesystem path to location of thumbnails for the | + | Returns the filesystem path to location of thumbnails for the document. |
| − | document. | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 1,172: | Line 993: | ||
$doc->thumbnail_types | $doc->thumbnail_types | ||
| − | + | Returns array containing names of all the thumbnail types available for this document. | |
| − | Returns array containing names of all the thumbnail types available | ||
| − | for this document. | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 1,187: | Line 1,006: | ||
$doc->remove_thumbnails | $doc->remove_thumbnails | ||
| − | |||
Removes all thumbnail files associated with this document. | Removes all thumbnail files associated with this document. | ||
| Line 1,201: | Line 1,019: | ||
$doc->make_thumbnails | $doc->make_thumbnails | ||
| − | |||
Make all the thumbnail files required for this document. | Make all the thumbnail files required for this document. | ||
| Line 1,215: | Line 1,032: | ||
$mime_type = $doc->mime_type | $mime_type = $doc->mime_type | ||
| − | |||
DEPRECATED - use <tt>$doc->value( "mime_type" )</tt> | DEPRECATED - use <tt>$doc->value( "mime_type" )</tt> | ||
| Line 1,231: | Line 1,047: | ||
$eprintid = $doc->get_parent_id | $eprintid = $doc->get_parent_id | ||
| − | |||
Returns the ID of the parent for this document, (i.e. the eprint ID). | Returns the ID of the parent for this document, (i.e. the eprint ID). | ||
| Line 1,245: | Line 1,060: | ||
$doc->add_relation( $tgt, @types ) | $doc->add_relation( $tgt, @types ) | ||
| + | Add one or more relations with type(s) specified by <tt>@types</tt> to the document data object and pointing to the <tt>$tgt</tt> data object. | ||
| − | + | This will not update the <tt>$tgt</tt> data object even if reflexive relations exist. | |
| − | |||
| − | |||
| − | This will not update the <tt>$tgt</tt> data object even if reflexive | ||
| − | |||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 1,263: | Line 1,075: | ||
$doc->remove_relation( $tgt, [ @types ] ) | $doc->remove_relation( $tgt, [ @types ] ) | ||
| + | Removes the relations for the document data object to the <tt>$tgt</tt> data object. If <tt>@types</tt> is not defined, remove all relations to <tt>$tgt</tt>. If <tt>$tgt</tt> is also undefined removes all relations given in <tt>@types</tt>. | ||
| − | + | If both <tt>$tgt</tt>, and <tt>@types</tt> are both undefined no relations will be removed. If you want to remove all relations do: | |
| − | |||
| − | |||
| − | |||
| − | If both <tt>$tgt</tt>, and <tt>@types</tt> are both undefined no relations will be | ||
| − | removed. If you want to remove all relations do: | ||
$doc->set_value( "relation", [] ); | $doc->set_value( "relation", [] ); | ||
| − | + | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <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> | <span style='display:none'>User Comments</span> | ||
| Line 1,284: | Line 1,092: | ||
$bool = $doc->has_relation( $tgt, [ @types ] ) | $bool = $doc->has_relation( $tgt, [ @types ] ) | ||
| − | + | Returns <tt>true</tt> if document data object has relations to <tt>$tgt</tt>. If <tt>@types</tt> is also given, check these relations satisfy all of the given types. If <tt>$tgt</tt> is undefined, relations that satisfy the given types may be to any data object. | |
| − | Returns <tt>true</tt> if document data object has relations to <tt>$tgt</tt>. If | ||
| − | <tt>@types</tt> is also given, check these relations satisfy all of the | ||
| − | given types. If <tt>$tgt</tt> is undefined, relations that satisfy the | ||
| − | |||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 1,301: | Line 1,105: | ||
$list = $doc->search_related( [ $type ] ) | $list = $doc->search_related( [ $type ] ) | ||
| − | + | Returns an [[API:EPrints/List|EPrints::List]] that contains all document data objects related to this document data object. If <tt>$type</tt> is defined return only those document data object related by that type. | |
| − | Returns an [[API:EPrints/List|EPrints::List]] that contains all document data objects | ||
| − | related to this document data object. If <tt>$type</tt> is defined return | ||
| − | only those document data object related by that type. | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 1,317: | Line 1,118: | ||
$citation = $doc->render_citation_link( $style, %params ) | $citation = $doc->render_citation_link( $style, %params ) | ||
| − | + | Returns a XHTML DOM citation rendering of the document data object. Using citation <tt>$style</tt> and <tt>%params</tt> provided and setting class for DOM parent element to <tt>ep_document_link</tt>. | |
| − | Returns a XHTML DOM citation rendering of the document data object. | ||
| − | |||
| − | |||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 1,333: | Line 1,131: | ||
$frag = $doc->render_video_preview( $css_class ) | $frag = $doc->render_video_preview( $css_class ) | ||
| − | + | Returns a XHTML DOM fragment rendering of a HTML5 video preview with optional subtitles. Assigning the <tt>$css_class</tt> to the parent element if the XHTML DOM fragment, if provided. | |
| − | Returns a XHTML DOM fragment rendering of a HTML5 video preview with | ||
| − | optional subtitles. Assigning the <tt>$css_class</tt> to the parent element | ||
| − | if the XHTML DOM fragment, if provided. | ||
Access / security concerns should be addressed at a higher level. | Access / security concerns should be addressed at a higher level. | ||
| Line 1,351: | Line 1,146: | ||
$boolean = $doc->permit( $priv, $user ) | $boolean = $doc->permit( $priv, $user ) | ||
| − | + | Returns boolean depending on whether the <tt>$user</tt> has the privilege <tt>$priv</tt> to carry out a particular action on this document data object. | |
| − | Returns boolean depending on whether the <tt>$user</tt> has the privilege | ||
| − | <tt>$priv</tt> to carry out a particular action on this document data | ||
| − | object. | ||
See [[API:EPrints/DataObj#permit|EPrints::DataObj#permit]]. | See [[API:EPrints/DataObj#permit|EPrints::DataObj#permit]]. | ||
| Line 1,366: | Line 1,158: | ||
</div> | </div> | ||
<!-- Pod2Wiki=head_utility_methods --> | <!-- Pod2Wiki=head_utility_methods --> | ||
| − | ===Utility Methods | + | ===Utility Methods=== |
| − | |||
| − | === | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <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> | <span style='display:none'>User Comments</span> | ||
| Line 1,380: | Line 1,170: | ||
EPrints::DataObj::doc_with_eprintid_and_pos( $repository, $eprintid, $pos ) | EPrints::DataObj::doc_with_eprintid_and_pos( $repository, $eprintid, $pos ) | ||
| + | Find the document for an eprint based on the <tt>$eprintid</tt> and <tt>$pos</tt> values supplied matching the document's corresponding fields. | ||
| − | + | Returns the document data object matching the criteria. Otherwise, checks <tt>dark_document</tt> dataset if it exists to find a corresponding match. | |
| − | |||
| − | |||
| − | Returns the document data object matching the criteria. Otherwise, | ||
| − | |||
| − | |||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 1,399: | Line 1,185: | ||
EPrints::DataObj::Document::main_input_tags( $session, $object ) | EPrints::DataObj::Document::main_input_tags( $session, $object ) | ||
| − | |||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <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> | <span style='display:none'>User Comments</span> | ||
| Line 1,411: | Line 1,196: | ||
EPrints::DataObj::main_render_option( $session, $object ) | EPrints::DataObj::main_render_option( $session, $object ) | ||
| − | |||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <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> | <span style='display:none'>User Comments</span> | ||
| Line 1,423: | Line 1,207: | ||
$cleanfilename = EPrints::DataObj::Document::sanitise( $filename ) | $cleanfilename = EPrints::DataObj::Document::sanitise( $filename ) | ||
| − | + | Sanitises filename by replacing invalid characters. Mainly uses [[API:EPrints/System#sanitise|EPrints::System#sanitise]] but also replaces <tt>/</tt> with <tt>_</tt> to ensure these do not get confused as a separator between direectories. | |
| − | Sanitises filename by replacing invalid characters. Mainly uses | ||
| − | |||
| − | ensure these do not get confused as a separator between direectories. | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 1,436: | Line 1,217: | ||
</div> | </div> | ||
<!-- Pod2Wiki=head_see_also --> | <!-- Pod2Wiki=head_see_also --> | ||
| − | ==SEE ALSO | + | ==SEE ALSO== |
| − | + | [[API:EPrints/DataObj/SubObject|EPrints::DataObj::SubObject]], [[API:EPrints/DataObj|EPrints::DataObj]] and [[API:EPrints/DataSet|EPrints::DataSet]]. | |
| − | == | ||
| − | [[API:EPrints/DataObj/SubObject|EPrints::DataObj::SubObject]], [[API:EPrints/DataObj|EPrints::DataObj]] and | ||
| − | [[API:EPrints/DataSet|EPrints::DataSet]]. | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 1,450: | Line 1,228: | ||
</div> | </div> | ||
<!-- Pod2Wiki=head_copyright --> | <!-- Pod2Wiki=head_copyright --> | ||
| − | ==COPYRIGHT | + | ==COPYRIGHT== |
| − | |||
| − | == | ||
{{API:Copyright}} | {{API:Copyright}} | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
Latest revision as of 00:38, 3 January 2022
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
- 1 NAME
- 2 DESCRIPTION
- 3 INSTANCE VARIABLES
- 4 CORE METADATA FIELDS
- 5 REFERENCES AND RELATED OBJECTS
- 6 METHODS
- 6.1 Constructor Methods
- 6.2 Class Methods
- 6.3 Object Methods
- 6.3.1 clone
- 6.3.2 remove
- 6.3.3 get_eprint
- 6.3.4 get_baseurl
- 6.3.5 is_public
- 6.3.6 path
- 6.3.7 file_path
- 6.3.8 get_url
- 6.3.9 local_path
- 6.3.10 files
- 6.3.11 remove_file
- 6.3.12 set_main
- 6.3.13 get_main
- 6.3.14 set_format
- 6.3.15 set_format_desc
- 6.3.16 upload
- 6.3.17 add_file
- 6.3.18 upload_archive
- 6.3.19 add_archive
- 6.3.20 add_directory
- 6.3.21 upload_url
- 6.3.22 commit
- 6.3.23 get_derived_versions
- 6.3.24 validate
- 6.3.25 user_can_view
- 6.3.26 get_type
- 6.3.27 queue_files_modified
- 6.3.28 files_modified
- 6.3.29 rehash
- 6.3.30 make_indexcodes
- 6.3.31 remove_indexcodes
- 6.3.32 cache_file
- 6.3.33 register_parent
- 6.3.34 thumbnail_url
- 6.3.35 icon_url
- 6.3.36 render_icon_link
- 6.3.37 render_preview_link
- 6.3.38 caption_frag
- 6.3.39 set_name
- 6.3.40 thumbnail_plugin
- 6.3.41 thumbnail_path
- 6.3.42 thumbnail_types
- 6.3.43 remove_thumbnails
- 6.3.44 make_thumbnails
- 6.3.45 mime_type
- 6.3.46 get_parent_id
- 6.3.47 add_relation
- 6.3.48 remove_relation
- 6.3.49 has_relation
- 6.3.50 search_related
- 6.3.51 render_citation_link
- 6.3.52 render_video_preview
- 6.3.53 permit
- 6.4 Utility Methods
- 7 SEE ALSO
- 8 COPYRIGHT
NAME
EPrints::DataObj::Document - A single format of a record.
DESCRIPTION
Document represents a single format of an EPrint (eg. PDF) - the actual file(s) rather than the metadata.
Inherits from EPrints::DataObj::SubObject, which in turn inherits from EPrints::DataObj.
INSTANCE VARIABLES
See EPrints::DataObj#INSTANCE_VARIABLES.
CORE METADATA FIELDS
docid (int)
The unique ID of the document.
rev_number (int)
The revision number of this document record.
pos (int)
The position of the document record within those associated with the eprint.
placement (int)
Placement of the document - the order documents in which should be shown. This may be different to pos, as the ultimate_doc_pos may lead to a different ordering.
format (namedset)
The format of this document. One of the types of the namedset c<document>.
formatdesc (text)
An additional description of this document. For example the specific version of a format.
language (namedset)
The ISO 639-1 code of the language of this document. The default configuration of EPrints does not set this.
security (namedset)
The security type of this document - who can view it. One of the types of the namedset security.
license (namedset)
The license applied of this document - who can view it. One of the types of the namedset license.
main (text)
The file which we should link to. For something like a PDF file this is the only file. For an HTML document with images it would be the name of the actual HTML file.
date_embargo (date)
The date until which the document has restricted access (set by security). At which point the embargo is lifted and security is set to public and this field set back to undef.
Requires bin/lift_embargos script to be deployed as a cron job.
date_embargo_retained (date)
The retained date of any embargo originally placed on this document. This is updated when a user modifies date_embargo but is not unset by the bin/lift_embargos script.
media (compound)
A compound field containing a description of the document media - dimensions, codec etc.
REFERENCES AND RELATED OBJECTS
eprintid (itemref)
The ID number of the eprint to which this document belongs.
files (subobject, multiple)
A virtual field which represents the list of files which are part of this record.
relation (relation, multiple)
Predicated relationships between this document and other data objects within the archive.
METHODS
Constructor Methods
create
$doc = EPrints::DataObj::Document::create( $session, $eprint )
Create and return a new document belonging to the given $eprint object.
N.B. This creates the document in the database, not just in memory.
create_from_data
$dataobj = EPrints::DataObj::Document::create_from_data( $session, $data, $dataset )
Create document data object from $data provided.
Returns undef if a bad (or no) eprintid specified in $data.
Otherwise calls the parent method in EPrints::DataObj.
Class Methods
get_system_field_info
$fields = EPrints::DataObj::Document->get_system_field_info
Returns an array describing the system metadata of the document dataset.
get_defaults
$defaults = EPrints::DataObj::Document->get_defaults( $session, $data, $dataset )
Returns default values for this data object based on the starting $data.
get_dataset_id
$dataset = EPrints::DataObj::Document->get_dataset_id
Returns the ID of the EPrints::DataSet object to which this record belongs.
get_parent_dataset_id
$dataset_id = EPrints::DataObj::Document->get_parent_dataset_id
Returns the ID of the parent dataset for a document, (i.e. eprint).
Object Methods
clone
$newdoc = $doc->clone( $eprint )
Attempt to clone this document. Both the document metadata and the actual files. The clone will be associated with the given $eprint.
Returns to the newly colument document.
remove
$success = $doc->remove
Attempt to completely delete this document. Including derived documents such as thumbnails.
Returns boolean dependent on success of deleting document.
get_eprint
$eprint = $doc->get_eprint
Returns the eprint this document is associated with.
Alias for:
$doc->get_parent
get_baseurl
$url = $doc->get_baseurl
Returns the base URL of the document.
is_public
$boolean = $doc->is_public
Returnes true if this document has no security set and is in the live archive. Otherwise, returns false.
path
$path = $doc->path
Returns the relative path to the document without specifying any file.
file_path
$path = $doc->file_path( [ $file ] )
Returns the relative path to $file stored in this document. If $file is undefined returns the path to the main file.
This is an efficient shortcut to this:
my $file = $doc->stored_file( $filename ); my $path = $file->path;
get_url
$url = $doc->get_url( [ $file ] )
Returns the full URL of the document.
If $file is not specified then the main file is used.
local_path
$path = $doc->local_path
DEPRECATED.
Returns the full path of the directory where this document is stored in the filesystem.
files
%files = $doc->files
Returns a hash, the keys of which are all the files belonging to this document (relative to local_path). The values are the sizes of the files in bytes.
remove_file
$success = $doc->remove_file( $filename )
Attempts to remove the file with $filename. $filename must be specified in the format that can be retrieved by get_stored_file.
set_main
$doc->set_main( $main_file )
Sets main for the document to the named $main_file and adjusts format and mime_type as necessary. Will not affect the database until the document is committed.
Unsets main if $main_file is undefined.
get_main
$filename = $doc->get_main
Returns the filename of the file set as main in this document.
set_format
$doc->set_format( $format )
Set format for document to $format. Will not affect the database until document is committed.
Alias for:
$doc->set_value( "format" , $format );
set_format_desc
$doc->set_format_desc( $format_desc )
Set format description for document to $format_desc. Will not affect the database until document is committed.
Alias for:
$doc->set_value( "format_desc" , $format_desc );
upload
$success = $doc->upload( $filehandle, $filename, [ $preserve_path, $filesize ] )
DEPRECATED - Use add_file, which will automatically identify the file type.
Upload the contents of the given $filehandle into this document as the given $filename.
If $preserve_path then make any subdirectories needed, otherwise place this in the top level directory.
add_file
$fileobj = $doc->add_file( $file, $filename, [ $preserve_path ] )
$file is the full path to a file to be added to the document, with name $filename. $filename is passed through EPrints::System#sanitise before being written.
If $preserve_path is true then include path components in $filename.
Returns the file object if successfully created or undef on failure.
upload_archive
$success = $doc->upload_archive( $filehandle, $filename, $archive_format )
DEPRECATED - use add_archive.
Upload the file contents provided through $filehandle using the filename from $filename. How to deal with the specified $archive_format (e.g. .zip, .tar.gz) is configured in EPrints::SystemSettings.
add_archive
$success = $doc->add_archive( $file, $archive_format )
Adds the contents of that archive $file to the document, where $archive_format is the format of the archive file (e.g. .zip, .tar.gz, etc.)
Returns a boolean dependent on whether the contents of the archive file is added to the document's subdirectory on the filesystem.
add_directory
$success = $doc->add_directory( $directory )
Upload the contents of $directory to this document. This will not set the document's main field.
This method expects $directory to have a trailing slash /.
Returns boolean depending on success of adding directory to document.
upload_url
$success = $doc->upload_url( $url )
Attempts to grab files from the given $url over HTTP. Grabbing files this way is always problematic. Therefore, by default, only relative links will be followed and only links to files in the same directory or subdirectory will be followed.
This method by default uses wget. However, you can modify this in EPrints::SystemSettings.
Returns a boolean dependent of whether file(s) were successfully uploaded.
commit
$success = $doc->commit( [ $force ] )
Commit any changes that have been made to this data object to the database.
Calls set_document_automatic_fields in the archive's configuration first to set any automatic fields that may be needed.
If $force is defined and true then still commit even if there are no non-volatile changes.
Returns boolean depending on whether commit of document data object is successful.
get_derived_versions
@derived_docs = $doc->get_derived_versions
Returns an array of documents that are derived from the current document through the isVersionOf relation.
validate
$problems = $doc->validate( [ $for_archive ] )
Validates the document data object. If $for_archive is defined this will be passed through to the archive configured validate_document method, in case it is required for bespoke changes to this method.
Returns a reference to an array of XHTML DOM objects describing validation problems with the entire document, including the metadata and repository config specific requirements.
A returned reference to an empty array indicates no problems.
user_can_view
$boolean = $doc->user_can_view( $user )
Returns true if this document's security settings allow the given $user access to view it.
get_type
$type = $doc->get_type
Returns the type of this document.
Alias for:
$doc->value( "format" );
queue_files_modified
$doc->queue_files_modified
Adds a files_modified task (e.g. for creating/updating thumbnails) to the event queue.
files_modified
$doc->files_modified
This method does all the things that need doing when a file has been modified.
rehash
$doc->rehash
Recalculate the hash value of the document. Uses MD5 of the files (in alphabetic order), but can use user-specified hashing function instead.
make_indexcodes
$indexcodes_doc = $doc->make_indexcodes
Make the index codes document for this document. Returns the generated index codes document on success or undef on failure.
remove_indexcodes
$doc = $doc->remove_indexcodes
Remove any documents containing index codes for this document. Returns the number of documents removed.
cache_file
$filename = $doc->cache_file( $suffix );
DEPRECATED
Returns a cache filename for this document with the given $suffix.
register_parent
$doc->register_parent( $parent )
Registers the $parent EPrints::DataObj::EPrint object for this document.
This may cause reference loops, but it does avoid two identical eprint data objects existing at once.
thumbnail_url
$doc->thumbnail_url( $size )
Returns the URL for the thumbnail of the document for a specified $size. If $size is unspecified defaults to small. Other values for $size include medium and preview.
Returns undef if file for particular type of thumbnail does not exist.
This method is called bt icon_url. It is best to use that method to reliably retrieve the required URL.
icon_url
$doc->icon_url( $size )
Returns the URL for the icon of the document for a specified $size. If $size is unspecified defaults to small. Other values for $size include medium and preview.
render_icon_link
$frag = $doc->render_icon_link( %opts )
Render a link to the icon for this document.
Options:
new_window => 1 - Make link go to _blank not current window. preview => 1 - If possible, provide a preview pop-up. public => 0 - Show thumbnail/preview only on public documents. public => 1 - Show thumbnail/preview on all documents if possible. with_link => 0 - Do not link.
render_preview_link
$frag = $doc->render_preview_link( %opts )
Render a link to the preview for this document (if available) using a lightbox.
Options:
caption_frag
caption => $frag
XHTML fragment to use as the caption, defaults to empty.
set_name
set => "name"
The name of the set this document belongs to, defaults to none (preview won't be shown as part of a set).
thumbnail_plugin
$plugin = $doc->thumbnail_plugin( $size )
Returns the plugin used to generatee thumbnails of the specified $size.
thumbnail_path
$path = $doc->thumbnail_path
DEPRECATED
Returns the filesystem path to location of thumbnails for the document.
thumbnail_types
$doc->thumbnail_types
Returns array containing names of all the thumbnail types available for this document.
remove_thumbnails
$doc->remove_thumbnails
Removes all thumbnail files associated with this document.
make_thumbnails
$doc->make_thumbnails
Make all the thumbnail files required for this document.
mime_type
$mime_type = $doc->mime_type
DEPRECATED - use $doc->value( "mime_type" )
Returns the MIME type of this document.
get_parent_id
$eprintid = $doc->get_parent_id
Returns the ID of the parent for this document, (i.e. the eprint ID).
add_relation
$doc->add_relation( $tgt, @types )
Add one or more relations with type(s) specified by @types to the document data object and pointing to the $tgt data object.
This will not update the $tgt data object even if reflexive relations exist.
remove_relation
$doc->remove_relation( $tgt, [ @types ] )
Removes the relations for the document data object to the $tgt data object. If @types is not defined, remove all relations to $tgt. If $tgt is also undefined removes all relations given in @types.
If both $tgt, and @types are both undefined no relations will be removed. If you want to remove all relations do:
$doc->set_value( "relation", [] );
has_relation
$bool = $doc->has_relation( $tgt, [ @types ] )
Returns true if document data object has relations to $tgt. If @types is also given, check these relations satisfy all of the given types. If $tgt is undefined, relations that satisfy the given types may be to any data object.
$list = $doc->search_related( [ $type ] )
Returns an EPrints::List that contains all document data objects related to this document data object. If $type is defined return only those document data object related by that type.
render_citation_link
$citation = $doc->render_citation_link( $style, %params )
Returns a XHTML DOM citation rendering of the document data object. Using citation $style and %params provided and setting class for DOM parent element to ep_document_link.
render_video_preview
$frag = $doc->render_video_preview( $css_class )
Returns a XHTML DOM fragment rendering of a HTML5 video preview with optional subtitles. Assigning the $css_class to the parent element if the XHTML DOM fragment, if provided.
Access / security concerns should be addressed at a higher level.
permit
$boolean = $doc->permit( $priv, $user )
Returns boolean depending on whether the $user has the privilege $priv to carry out a particular action on this document data object.
Utility Methods
doc_with_eprintid_and_pos
EPrints::DataObj::doc_with_eprintid_and_pos( $repository, $eprintid, $pos )
Find the document for an eprint based on the $eprintid and $pos values supplied matching the document's corresponding fields.
Returns the document data object matching the criteria. Otherwise, checks dark_document dataset if it exists to find a corresponding match.
main_input_tags
EPrints::DataObj::Document::main_input_tags( $session, $object )
main_render_option
EPrints::DataObj::main_render_option( $session, $object )
sanitise
$cleanfilename = EPrints::DataObj::Document::sanitise( $filename )
Sanitises filename by replacing invalid characters. Mainly uses EPrints::System#sanitise but also replaces / with _ to ensure these do not get confused as a separator between direectories.
SEE ALSO
EPrints::DataObj::SubObject, EPrints::DataObj and EPrints::DataSet.
COPYRIGHT
© Copyright 2023 University of Southampton.
EPrints 3.4 is supplied by EPrints Services.
http://www.eprints.org/eprints-3.4/
LICENSE
This file is part of EPrints 3.4 http://www.eprints.org/.
EPrints 3.4 and this file are released under the terms of the GNU Lesser General Public License version 3 as published by the Free Software Foundation unless otherwise stated.
EPrints 3.4 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 3.4. If not, see http://www.gnu.org/licenses/.
