Difference between revisions of "API:EPrints/DataObj/Document"

From EPrints Documentation
Jump to: navigation, search
Line 1: Line 1:
 
<!-- Pod2Wiki=_preamble_  
 
<!-- Pod2Wiki=_preamble_  
 
This page has been automatically generated from the EPrints 3.2 source. Any wiki changes made between the 'Pod2Wiki=*' and 'Edit below this comment' comments will be lost.
 
This page has been automatically generated from the EPrints 3.2 source. Any wiki changes made between the 'Pod2Wiki=*' and 'Edit below this comment' comments will be lost.
  -->
+
  -->{{API}}{{Pod2Wiki}}{{API:Source|file=EPrints/DataObj/Document.pm|package_name=EPrints::DataObj::Document}}[[Category:API|Document]]<div><!-- Edit below this comment -->
__NOTOC__
 
{{API}}{{Pod2Wiki}}{{API:Source|file=EPrints/DataObj/Document.pm|package_name=EPrints::DataObj::Document}}[[Category:API|Document]]<div><!-- Edit below this comment -->
 
  
  
<!-- Pod2Wiki=head_name --></div>
+
<!-- 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.
  
 
<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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=head_description --></div>
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- 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.
Line 22: Line 22:
  
 
<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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_docid --></div>
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_docid -->
 
===docid (text)===
 
===docid (text)===
  
Line 34: Line 36:
  
 
<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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_eprintid --></div>
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_eprintid -->
 
===eprintid (itemref)===
 
===eprintid (itemref)===
  
Line 44: Line 48:
  
 
<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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_placement --></div>
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_placement -->
 
===placement (int)===
 
===placement (int)===
  
Line 54: Line 60:
  
 
<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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_format --></div>
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_format -->
 
===format (namedset)===
 
===format (namedset)===
  
Line 64: Line 72:
  
 
<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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_formatdesc --></div>
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_formatdesc -->
 
===formatdesc (text)===
 
===formatdesc (text)===
  
Line 74: Line 84:
  
 
<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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_language --></div>
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_language -->
 
===language (namedset)===
 
===language (namedset)===
  
Line 84: Line 96:
  
 
<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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_security --></div>
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_security -->
 
===security (namedset)===
 
===security (namedset)===
  
Line 94: Line 108:
  
 
<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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_main --></div>
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_main -->
 
===main (text)===
 
===main (text)===
  
Line 104: Line 120:
  
 
<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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_documents --></div>
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_documents -->
 
===documents (subobject, multiple)===
 
===documents (subobject, multiple)===
  
Line 114: Line 132:
  
 
<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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=head_methods --></div>
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- 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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_get_system_field_info --></div>
+
<!-- Pod2Wiki= -->
===$metadata = EPrints::DataObj::Document-&gt;get_system_field_info===
+
</div>
 +
<!-- Pod2Wiki=item_get_system_field_info -->
 +
===get_system_field_info===
  
 +
$metadata = EPrints::DataObj::Document-&gt;get_system_field_info
 
Return an array describing the system metadata of the Document dataset.
 
Return 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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_get_dataset_id --></div>
+
<!-- Pod2Wiki= -->
===$dataset = EPrints::DataObj::Document-&gt;get_dataset_id===
+
</div>
 +
<!-- Pod2Wiki=item_get_dataset_id -->
 +
===get_dataset_id===
  
 +
$dataset = EPrints::DataObj::Document-&gt;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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_get_defaults --></div>
+
<!-- Pod2Wiki= -->
===$defaults = EPrints::DataObj::Document-&gt;get_defaults( $session, $data )===
+
</div>
 +
<!-- Pod2Wiki=item_get_defaults -->
 +
===get_defaults===
  
 +
$defaults = EPrints::DataObj::Document-&gt;get_defaults( $session, $data )
 
Return default values for this object based on the starting data.
 
Return default values for this object based on the starting data.
  
 
<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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_clone --></div>
+
<!-- Pod2Wiki= -->
===$newdoc = $doc-&gt;clone( $eprint )===
+
</div>
 +
<!-- Pod2Wiki=item_clone -->
 +
===clone===
  
 +
$newdoc = $doc-&gt;clone( $eprint )
 
Attempt to clone this document. Both the document metadata and the actual files. The clone will be associated with the given EPrint.
 
Attempt to clone this document. Both the document metadata and the actual files. The clone will be associated with the given 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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_remove --></div>
+
<!-- Pod2Wiki= -->
===$success = $doc-&gt;remove===
+
</div>
 +
<!-- Pod2Wiki=item_remove -->
 +
===remove===
  
 +
$success = $doc-&gt;remove
 
Attempt to completely delete this document
 
Attempt to completely delete 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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_get_eprint --></div>
+
<!-- Pod2Wiki= -->
===$eprint = $doc-&gt;get_eprint===
+
</div>
 +
<!-- Pod2Wiki=item_get_eprint -->
 +
===get_eprint===
  
 +
$eprint = $doc-&gt;get_eprint
 
Return the EPrint this document is associated with.
 
Return the EPrint this document is associated with.
  
Line 183: Line 221:
  
 
<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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_get_baseurl --></div>
+
<!-- Pod2Wiki= -->
===$url = $doc-&gt;get_baseurl( [$staff] )===
+
</div>
 +
<!-- Pod2Wiki=item_get_baseurl -->
 +
===get_baseurl===
  
 +
$url = $doc-&gt;get_baseurl( [$staff] )
 
Return the base URL of the document. Overrides the stub in DataObj. $staff is currently ignored.
 
Return the base URL of the document. Overrides the stub in DataObj. $staff is currently ignored.
  
 
<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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_is_public --></div>
+
<!-- Pod2Wiki= -->
===$boolean = $doc-&gt;is_public()===
+
</div>
 +
<!-- Pod2Wiki=item_is_public -->
 +
===is_public===
  
 +
$boolean = $doc-&gt;is_public()
 
True if this document has no security set and is in the live archive.
 
True if this document has no security set and is in the live archive.
  
 
<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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_get_url --></div>
+
<!-- Pod2Wiki= -->
===$url = $doc-&gt;get_url( [$file] )===
+
</div>
 +
<!-- Pod2Wiki=item_get_url -->
 +
===get_url===
  
 +
$url = $doc-&gt;get_url( [$file] )
 
Return the full URL of the document. Overrides the stub in DataObj.
 
Return the full URL of the document. Overrides the stub in DataObj.
  
Line 215: Line 262:
  
 
<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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_local_path --></div>
+
<!-- Pod2Wiki= -->
===$path = $doc-&gt;local_path===
+
</div>
 +
<!-- Pod2Wiki=item_local_path -->
 +
===local_path===
  
 +
$path = $doc-&gt;local_path
 
Return the full path of the directory where this document is stored in the filesystem.
 
Return 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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_files --></div>
+
<!-- Pod2Wiki= -->
===%files = $doc-&gt;files===
+
</div>
 +
<!-- Pod2Wiki=item_files -->
 +
===files===
  
 +
%files = $doc-&gt;files
 
Return a hash, the keys of which are all the files belonging to this document (relative to $doc-&gt;local_path). The values are the sizes of the files, in bytes.
 
Return a hash, the keys of which are all the files belonging to this document (relative to $doc-&gt;local_path). The values are the sizes of the 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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_remove_file --></div>
+
<!-- Pod2Wiki= -->
===$success = $doc-&gt;remove_file( $filename )===
+
</div>
 +
<!-- Pod2Wiki=item_remove_file -->
 +
===remove_file===
  
 +
$success = $doc-&gt;remove_file( $filename )
 
Attempt to remove the given file. Give the filename as it is returned by get_files().
 
Attempt to remove the given file. Give the filename as it is returned by get_files().
  
 
<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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_set_main --></div>
+
<!-- Pod2Wiki= -->
===$doc-&gt;set_main( $main_file )===
+
</div>
 +
<!-- Pod2Wiki=item_set_main -->
 +
===set_main===
  
 +
$doc-&gt;set_main( $main_file )
 
Sets the main file. Won't affect the database until a $doc-&gt;commit().
 
Sets the main file. Won't affect the database until a $doc-&gt;commit().
  
 
<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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_get_main --></div>
+
<!-- Pod2Wiki= -->
===$filename = $doc-&gt;get_main===
+
</div>
 +
<!-- Pod2Wiki=item_get_main -->
 +
===get_main===
  
 +
$filename = $doc-&gt;get_main
 
Return the name of the main file in this document.
 
Return the name of the main file in 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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_set_format --></div>
+
<!-- Pod2Wiki= -->
===$doc-&gt;set_format( $format )===
+
</div>
 +
<!-- Pod2Wiki=item_set_format -->
 +
===set_format===
  
 +
$doc-&gt;set_format( $format )
 
Set format. Won't affect the database until a commit(). Just an alias  for $doc-&gt;set_value( "format" , $format );
 
Set format. Won't affect the database until a commit(). Just an alias  for $doc-&gt;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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_set_format_desc --></div>
+
<!-- Pod2Wiki= -->
===$doc-&gt;set_format_desc( $format_desc )===
+
</div>
 +
<!-- Pod2Wiki=item_set_format_desc -->
 +
===set_format_desc===
  
 +
$doc-&gt;set_format_desc( $format_desc )
 
Set the format description.  Won't affect the database until a commit(). Just an alias for $doc-&gt;set_value( "format_desc" , $format_desc );
 
Set the format description.  Won't affect the database until a commit(). Just an alias for $doc-&gt;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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_upload --></div>
+
<!-- Pod2Wiki= -->
===$success = $doc-&gt;upload( $filehandle, $filename [, $preserve_path [, $filesize ] ] )===
+
</div>
 +
<!-- Pod2Wiki=item_upload -->
 +
===upload===
  
 +
$success = $doc-&gt;upload( $filehandle, $filename [, $preserve_path [, $filesize ] ] )
 
Upload the contents of the given file handle into this document as the given filename.
 
Upload the contents of the given file handle into this document as the given filename.
  
Line 297: Line 368:
  
 
<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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_add_file --></div>
+
<!-- Pod2Wiki= -->
===$success = $doc-&gt;add_file( $file, $filename, [$preserve_path] )===
+
</div>
 +
<!-- Pod2Wiki=item_add_file -->
 +
===add_file===
  
 +
$success = $doc-&gt;add_file( $file, $filename, [$preserve_path] )
 
$file is the full path to a file to be added to the document, with name $filename.
 
$file is the full path to a file to be added to the document, with name $filename.
  
Line 309: Line 383:
  
 
<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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_sanitise --></div>
+
<!-- Pod2Wiki= -->
===$cleanfilename = sanitise( $filename )===
+
</div>
 +
<!-- Pod2Wiki=item_sanitise -->
 +
===sanitise===
  
 +
$cleanfilename = sanitise( $filename )
 
Return just the filename (no leading path) and convert any naughty characters to underscore.
 
Return just the filename (no leading path) and convert any naughty characters to underscore.
  
 
<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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_upload_archive --></div>
+
<!-- Pod2Wiki= -->
===$success = $doc-&gt;upload_archive( $filehandle, $filename, $archive_format )===
+
</div>
 +
<!-- Pod2Wiki=item_upload_archive -->
 +
===upload_archive===
  
 +
$success = $doc-&gt;upload_archive( $filehandle, $filename, $archive_format )
 
Upload the contents of the given archive file. How to deal with the  archive format is configured in SystemSettings.  
 
Upload the contents of the given archive file. How to deal with the  archive format is configured in SystemSettings.  
  
Line 331: Line 411:
  
 
<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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_add_archive --></div>
+
<!-- Pod2Wiki= -->
===$success = $doc-&gt;add_archive( $file, $archive_format )===
+
</div>
 +
<!-- Pod2Wiki=item_add_archive -->
 +
===add_archive===
  
 +
$success = $doc-&gt;add_archive( $file, $archive_format )
 
$file is the full path to an archive file, eg. zip or .tar.gz  
 
$file is the full path to an archive file, eg. zip or .tar.gz  
  
Line 343: Line 426:
  
 
<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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_add_directory --></div>
+
<!-- Pod2Wiki= -->
===$success = $doc-&gt;add_directory( $directory )===
+
</div>
 +
<!-- Pod2Wiki=item_add_directory -->
 +
===add_directory===
  
 +
$success = $doc-&gt;add_directory( $directory )
 
Upload the contents of $directory to this document. This will not set the main file.
 
Upload the contents of $directory to this document. This will not set the main file.
  
Line 355: Line 441:
  
 
<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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_upload_url --></div>
+
<!-- Pod2Wiki= -->
===$success = $doc-&gt;upload_url( $url )===
+
</div>
 +
<!-- Pod2Wiki=item_upload_url -->
 +
===upload_url===
  
 +
$success = $doc-&gt;upload_url( $url )
 
Attempt to grab stuff from the given URL. Grabbing HTML stuff this way is always problematic, so (by default): only relative links will  be followed and only links to files in the same directory or  subdirectory will be followed.
 
Attempt to grab stuff from the given URL. Grabbing HTML stuff this way is always problematic, so (by default): only relative links will  be followed and only links to files in the same directory or  subdirectory will be followed.
  
Line 367: Line 456:
  
 
<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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_commit --></div>
+
<!-- Pod2Wiki= -->
===$success = $doc-&gt;commit===
+
</div>
 +
<!-- Pod2Wiki=item_commit -->
 +
===commit===
  
 +
$success = $doc-&gt;commit
 
Commit any changes that have been made to this object to the database.
 
Commit any changes that have been made to this object to the database.
  
Line 379: Line 471:
  
 
<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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_validate --></div>
+
<!-- Pod2Wiki= -->
===$problems = $doc-&gt;validate( [$for_archive] )===
+
</div>
 +
<!-- Pod2Wiki=item_validate -->
 +
===validate===
  
 +
$problems = $doc-&gt;validate( [$for_archive] )
 
Return an array of XHTML DOM objects describing validation problems with the entire document, including the metadata and repository config specific requirements.
 
Return an array of XHTML DOM objects describing validation problems with the entire document, including the metadata and repository config specific requirements.
  
Line 391: Line 486:
  
 
<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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_get_type --></div>
+
<!-- Pod2Wiki= -->
===$type = $doc-&gt;get_type===
+
</div>
 +
<!-- Pod2Wiki=item_get_type -->
 +
===get_type===
  
 +
$type = $doc-&gt;get_type
 
Return the type of this document.
 
Return the type of 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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_files_modified --></div>
+
<!-- Pod2Wiki= -->
===$doc-&gt;files_modified===
+
</div>
 +
<!-- Pod2Wiki=item_files_modified -->
 +
===files_modified===
  
 +
$doc-&gt;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 modified.
  
 
<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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_rehash --></div>
+
<!-- Pod2Wiki= -->
===$doc-&gt;rehash===
+
</div>
 +
<!-- Pod2Wiki=item_rehash -->
 +
===rehash===
  
 +
$doc-&gt;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 alphabetic order), but can use user specified hashing function 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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_make_indexcodes --></div>
+
<!-- Pod2Wiki= -->
===$doc = $doc-&gt;make_indexcodes()===
+
</div>
 +
<!-- Pod2Wiki=item_make_indexcodes -->
 +
===make_indexcodes===
  
 +
$doc = $doc-&gt;make_indexcodes()
 
Make the indexcodes document for this document. Returns the generated document or undef on failure.
 
Make the indexcodes document for this document. Returns the generated document or undef 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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_remove_indexcodes --></div>
+
<!-- Pod2Wiki= -->
===$doc = $doc-&gt;remove_indexcodes()===
+
</div>
 +
<!-- Pod2Wiki=item_remove_indexcodes -->
 +
===remove_indexcodes===
  
 +
$doc = $doc-&gt;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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_cache_file --></div>
+
<!-- Pod2Wiki= -->
===$filename = $doc-&gt;cache_file( $suffix );===
+
</div>
 +
<!-- Pod2Wiki=item_cache_file -->
 +
===cache_file===
  
 +
$filename = $doc-&gt;cache_file( $suffix );
 
Return a cache filename for this document with the givven suffix.
 
Return a cache filename for this document with the givven suffix.
  
 
<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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_render_icon_link --></div>
+
<!-- Pod2Wiki= -->
===$frag = $doc-&gt;render_icon_link( %opts )===
+
</div>
 +
<!-- Pod2Wiki=item_render_icon_link -->
 +
===render_icon_link===
  
 +
$frag = $doc-&gt;render_icon_link( %opts )
 
Render a link to the icon for this document.
 
Render a link to the icon for this document.
  
Line 463: Line 579:
  
 
<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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_new_window_1 --></div>
+
<!-- Pod2Wiki= -->
===new_window =&gt; 1===
+
</div>
 +
<!-- Pod2Wiki=item_new_window_1 -->
 +
===new_window_1===
  
 +
new_window =&gt; 1
 
Make link go to _blank not current window.
 
Make link go to _blank not current window.
  
 
<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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_preview_1 --></div>
+
<!-- Pod2Wiki= -->
===preview =&gt; 1===
+
</div>
 +
<!-- Pod2Wiki=item_preview_1 -->
 +
===preview_1===
  
 +
preview =&gt; 1
 
If possible, provide a preview pop-up.
 
If possible, provide a preview pop-up.
  
 
<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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_public_0 --></div>
+
<!-- Pod2Wiki= -->
===public =&gt; 0===
+
</div>
 +
<!-- Pod2Wiki=item_public_0 -->
 +
===public_0===
  
 +
public =&gt; 0
 
Show thumbnail/preview only on public docs.
 
Show thumbnail/preview only on public docs.
  
 
<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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_public_1 --></div>
+
<!-- Pod2Wiki= -->
===public =&gt; 1===
+
</div>
 +
<!-- Pod2Wiki=item_public_1 -->
 +
===public_1===
  
 +
public =&gt; 1
 
Show thumbnail/preview on all docs if poss.
 
Show thumbnail/preview on all docs if poss.
  
 
<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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_render_preview_link --></div>
+
<!-- Pod2Wiki= -->
===$frag = $doc-&gt;render_preview_link( %opts )===
+
</div>
 +
<!-- Pod2Wiki=item_render_preview_link -->
 +
===render_preview_link===
  
 +
$frag = $doc-&gt;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.
  
Line 515: Line 646:
  
 
<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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_caption_frag --></div>
+
<!-- Pod2Wiki= -->
===caption =&gt; $frag===
+
</div>
 +
<!-- Pod2Wiki=item_caption_frag -->
 +
===caption_frag===
  
 +
caption =&gt; $frag
 
XHTML fragment to use as the caption, defaults to empty.
 
XHTML fragment to use as the caption, defaults to empty.
  
 
<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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_set_foo --></div>
+
<!-- Pod2Wiki= -->
===set =&gt; "foo"===
+
</div>
 +
<!-- Pod2Wiki=item_set_foo -->
 +
===set_foo===
  
 +
set =&gt; "foo"
 
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%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 +
<!-- Pod2Wiki= -->
 +
</div>
 
<!-- Pod2Wiki=_postamble_ --><!-- Edit below this comment -->
 
<!-- Pod2Wiki=_postamble_ --><!-- Edit below this comment -->

Revision as of 13:21, 25 February 2010

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.3, 3.2) | Revision Log | Before editing this page please read Pod2Wiki


NAME

EPrints::DataObj::Document - A single format of a record.

User Comments


DESCRIPTION

Document represents a single format of an EPrint (eg. PDF) - the actual file(s) rather than the metadata.

This class is a subclass of DataObj, with the following metadata fields:

User Comments


docid (text)

The unique ID of the document. This is a string of the format 123-02 where the first number is the eprint id and the second is the document number within that eprint.

This should probably have been and "int" but isn't. I later version of EPrints may change this.

User Comments


eprintid (itemref)

The id number of the eprint to which this document belongs.

User Comments


placement (int)

Placement of the document - the order documents should be shown in.

User Comments


format (namedset)

The format of this document. One of the types of the dataset "document".

User Comments


formatdesc (text)

An additional description of this document. For example the specific version of a format.

User Comments


language (namedset)

The ISO ID of the language of this document. The default configuration of EPrints does not set this.

User Comments


security (namedset)

The security type of this document - who can view it. One of the types of the dataset "security".

User Comments


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.

User Comments


documents (subobject, multiple)

A virtual field which represents the list of Documents which are part of this record.

User Comments


METHODS

User Comments


get_system_field_info

$metadata = EPrints::DataObj::Document->get_system_field_info

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

User Comments


get_dataset_id

$dataset = EPrints::DataObj::Document->get_dataset_id

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

User Comments


get_defaults

$defaults = EPrints::DataObj::Document->get_defaults( $session, $data )

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

User Comments


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.

User Comments


remove

$success = $doc->remove

Attempt to completely delete this document

User Comments


get_eprint

$eprint = $doc->get_eprint

Return the EPrint this document is associated with.

This is a synonym for get_parent().

User Comments


get_baseurl

$url = $doc->get_baseurl( [$staff] )

Return the base URL of the document. Overrides the stub in DataObj. $staff is currently ignored.

User Comments


is_public

$boolean = $doc->is_public()

True if this document has no security set and is in the live archive.

User Comments


get_url

$url = $doc->get_url( [$file] )

Return the full URL of the document. Overrides the stub in DataObj.

If file is not specified then the "main" file is used.

User Comments


local_path

$path = $doc->local_path

Return the full path of the directory where this document is stored in the filesystem.

User Comments


files

%files = $doc->files

Return a hash, the keys of which are all the files belonging to this document (relative to $doc->local_path). The values are the sizes of the files, in bytes.

User Comments


remove_file

$success = $doc->remove_file( $filename )

Attempt to remove the given file. Give the filename as it is returned by get_files().

User Comments


set_main

$doc->set_main( $main_file )

Sets the main file. Won't affect the database until a $doc->commit().

User Comments


get_main

$filename = $doc->get_main

Return the name of the main file in this document.

User Comments


set_format

$doc->set_format( $format )

Set format. Won't affect the database until a commit(). Just an alias for $doc->set_value( "format" , $format );

User Comments


set_format_desc

$doc->set_format_desc( $format_desc )

Set the format description. Won't affect the database until a commit(). Just an alias for $doc->set_value( "format_desc" , $format_desc );

User Comments


upload

$success = $doc->upload( $filehandle, $filename [, $preserve_path [, $filesize ] ] )

Upload the contents of the given file handle into this document as the given filename.

If $preserve_path then make any subdirectories needed, otherwise place this in the top level.

User Comments


add_file

$success = $doc->add_file( $file, $filename, [$preserve_path] )

$file is the full path to a file to be added to the document, with name $filename.

If $preserve_path then keep the filename as is (including subdirs and spaces)

User Comments


sanitise

$cleanfilename = sanitise( $filename )

Return just the filename (no leading path) and convert any naughty characters to underscore.

User Comments


upload_archive

$success = $doc->upload_archive( $filehandle, $filename, $archive_format )

Upload the contents of the given archive file. How to deal with the archive format is configured in SystemSettings.

(In case the over-loading of the word "archive" is getting confusing, in this context we mean ".zip" or ".tar.gz" archive.)

User Comments


add_archive

$success = $doc->add_archive( $file, $archive_format )

$file is the full path to an archive file, eg. zip or .tar.gz

This function will add the contents of that archive to the document.

User Comments


add_directory

$success = $doc->add_directory( $directory )

Upload the contents of $directory to this document. This will not set the main file.

This method expects $directory to have a trailing slash (/).

User Comments


upload_url

$success = $doc->upload_url( $url )

Attempt to grab stuff from the given URL. Grabbing HTML stuff this way is always problematic, so (by default): only relative links will be followed and only links to files in the same directory or subdirectory will be followed.

This (by default) uses wget. The details can be configured in SystemSettings.

User Comments


commit

$success = $doc->commit

Commit any changes that have been made to this object to the database.

Calls "set_document_automatic_fields" in the ArchiveConfig first to set any automatic fields that may be needed.

User Comments


validate

$problems = $doc->validate( [$for_archive] )

Return an array of XHTML DOM objects describing validation problems with the entire document, including the metadata and repository config specific requirements.

A reference to an empty array indicates no problems.

User Comments


get_type

$type = $doc->get_type

Return the type of this document.

User Comments


files_modified

$doc->files_modified

This method does all the things that need doing when a file has been modified.

User Comments


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.

User Comments


make_indexcodes

$doc = $doc->make_indexcodes()

Make the indexcodes document for this document. Returns the generated document or undef on failure.

User Comments


remove_indexcodes

$doc = $doc->remove_indexcodes()

Remove any documents containing index codes for this document. Returns the number of documents removed.

User Comments


cache_file

$filename = $doc->cache_file( $suffix );

Return a cache filename for this document with the givven suffix.

User Comments


render_icon_link

$frag = $doc->render_icon_link( %opts )

Render a link to the icon for this document.

Options:

User Comments


new_window_1

new_window => 1

Make link go to _blank not current window.

User Comments


preview_1

preview => 1

If possible, provide a preview pop-up.

User Comments


public_0

public => 0

Show thumbnail/preview only on public docs.

User Comments


public_1

public => 1

Show thumbnail/preview on all docs if poss.

User Comments


render_preview_link

$frag = $doc->render_preview_link( %opts )

Render a link to the preview for this document (if available) using a lightbox.

Options:

User Comments


caption_frag

caption => $frag

XHTML fragment to use as the caption, defaults to empty.

User Comments


set_foo

set => "foo"

The name of the set this document belongs to, defaults to none (preview won't be shown as part of a set).

User Comments