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

From EPrints Documentation
Jump to: navigation, search
Line 10: Line 10:
 
'''EPrints::DataObj::Document''' - A single format of a record.
 
'''EPrints::DataObj::Document''' - A single format of a record.
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 62: Line 62:
 
   $xhtml = $doc-&gt;render_preview_link( %opts );
 
   $xhtml = $doc-&gt;render_preview_link( %opts );
 
    
 
    
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 73: Line 73:
 
This class is a subclass of DataObj, with the following metadata fields:  
 
This class is a subclass of DataObj, with the following metadata fields:  
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 85: Line 85:
 
This should probably have been and "int" but isn't. I later version of EPrints may change this.
 
This should probably have been and "int" but isn't. I later version of EPrints may change this.
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 95: Line 95:
 
The id number of the eprint to which this document belongs.
 
The id number of the eprint to which this document belongs.
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 105: Line 105:
 
Placement of the document - the order documents should be shown in.
 
Placement of the document - the order documents should be shown in.
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 115: Line 115:
 
The format of this document. One of the types of the dataset "document".
 
The format of this document. One of the types of the dataset "document".
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 125: Line 125:
 
An additional description of this document. For example the specific version of a format.
 
An additional description of this document. For example the specific version of a format.
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 135: Line 135:
 
The ISO ID of the language of this document. The default configuration of EPrints does not set this.
 
The ISO ID of the language of this document. The default configuration of EPrints does not set this.
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 145: Line 145:
 
The security type of this document - who can view it. One of the types of the namedset "security".
 
The security type of this document - who can view it. One of the types of the namedset "security".
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 155: Line 155:
 
The type of content. Conceptual type, no format. ie. Supporting Material or  published version. Values from namedset "content"
 
The type of content. Conceptual type, no format. ie. Supporting Material or  published version. Values from namedset "content"
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 165: Line 165:
 
The type of license for the document. Such as GFDL or creative commons. Values from namedset "licenses"
 
The type of license for the document. Such as GFDL or creative commons. Values from namedset "licenses"
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 175: Line 175:
 
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.
 
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: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 185: Line 185:
 
A virtual field which represents the list of Documents which are part of this record.
 
A virtual field which represents the list of Documents which are part of this record.
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 192: Line 192:
 
<!-- Pod2Wiki=head_methods --></div>
 
<!-- Pod2Wiki=head_methods --></div>
 
==METHODS==
 
==METHODS==
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 202: Line 202:
 
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: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 214: Line 214:
 
This is a synonym for get_parent().
 
This is a synonym for get_parent().
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 224: Line 224:
 
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: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 236: Line 236:
 
If file is not specified then the "main" file is used.
 
If file is not specified then the "main" file is used.
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 246: Line 246:
 
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: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 256: Line 256:
 
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: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 266: Line 266:
 
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: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 276: Line 276:
 
Attempt to remove all files associated with this document.
 
Attempt to remove all files associated with this document.
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 288: Line 288:
 
This checks the file exists, so is more than an alias for get_value.
 
This checks the file exists, so is more than an alias for get_value.
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 300: Line 300:
 
If $preserve_path then make any subdirectories needed, otherwise place this in the top level.
 
If $preserve_path then make any subdirectories needed, otherwise place this in the top level.
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 312: Line 312:
 
If $preserve_path then keep the filename as is (including subdirs and spaces)
 
If $preserve_path then keep the filename as is (including subdirs and spaces)
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 324: Line 324:
 
(In case the over-loading of the word "archive" is getting confusing,  in this context we mean ".zip" or ".tar.gz" archive.)
 
(In case the over-loading of the word "archive" is getting confusing,  in this context we mean ".zip" or ".tar.gz" archive.)
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 336: Line 336:
 
This function will add the contents of that archive to the document.
 
This function will add the contents of that archive to the document.
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 348: Line 348:
 
This method expects $directory to have a trailing slash (/).
 
This method expects $directory to have a trailing slash (/).
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 360: Line 360:
 
This (by default) uses wget. The details can be configured in SystemSettings.
 
This (by default) uses wget. The details can be configured in SystemSettings.
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 370: Line 370:
 
Make link go to _blank not current window.
 
Make link go to _blank not current window.
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 380: Line 380:
 
If possible, provide a preview pop-up.
 
If possible, provide a preview pop-up.
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 390: Line 390:
 
Show thumbnail/preview only on public docs.
 
Show thumbnail/preview only on public docs.
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 400: Line 400:
 
Show thumbnail/preview on all docs if poss.
 
Show thumbnail/preview on all docs if poss.
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 410: Line 410:
 
XHTML fragment to use as the caption, defaults to empty.
 
XHTML fragment to use as the caption, defaults to empty.
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 420: Line 420:
 
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: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->

Revision as of 14:03, 24 August 2009


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


SYNOPSIS

 Inherrits all methods from EPrints::DataObj.
 
 # create a new document on $eprint 
 my $doc_data = {
   _parent => $eprint,
   eprintid => $eprint->get_id,
 };
 my $doc_ds = $handle->get_repository->get_dataset( 'document' );
 my $document = $doc_ds->create_object( $handle, $doc_data );
 
 # Add files to the document  
 $success = $doc->add_file( $file, $filename, [$preserve_path] );
 $success = $doc->upload( $filehandle, $filename [, $preserve_path [, $filesize ] ] );
 $success = $doc->upload_archive( $filehandle, $filename, $archive_format );
 $success = $doc->add_archive( $file, $archive_format );
 $success = $doc->add_directory( $directory );
 $success = $doc->upload_url( $url );
 
 # get an existing document
 $document = EPrints::DataObj::EPrint->new( $handle, $doc_id );
 # or
 foreach my $doc ( $eprint->get_all_documents ) { ... }
 
 # eprint to which this document belongs
 $eprint = $doc->get_eprint;
 
 # delete a document object *forever*:
 $success = $doc->remove;
 
 $url = $doc->get_url( [$file] );
 $path = $doc->local_path;
 %files = $doc->files;
 
 # delete a file
 $success = $doc->remove_file( $filename );
 # delete all files
 $success = $doc->remove_all_files;
 
 # change the file which is used as the URL for the document.
 $doc->set_main( $main_file );
 
 # icons and previews
 $xhtml = $doc->render_icon_link( %opts );
 $xhtml = $doc->render_preview_link( %opts );
 

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 namedset "security".

User Comments


content (namedset)

The type of content. Conceptual type, no format. ie. Supporting Material or published version. Values from namedset "content"

User Comments


license (namedset)

The type of license for the document. Such as GFDL or creative commons. Values from namedset "licenses"

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


$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


$eprint = $doc->get_eprint

Return the EPrint this document is associated with.

This is a synonym for get_parent().

User Comments


$boolean = $doc->is_public()

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

User Comments


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

Return the full URL of the document.

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

User Comments


$path = $doc->local_path

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

User Comments


%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


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

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

User Comments


$success = $doc->remove_all_files

Attempt to remove all files associated with this document.

User Comments


$doc->set_main( $main_file )

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

This checks the file exists, so is more than an alias for get_value.

User Comments


$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


$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


$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


$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


$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


$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


new_window => 1

Make link go to _blank not current window.

User Comments


preview => 1

If possible, provide a preview pop-up.

User Comments


public => 0

Show thumbnail/preview only on public docs.

User Comments


public => 1

Show thumbnail/preview on all docs if poss.

User Comments


caption => $frag

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

User Comments


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