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

From EPrints Documentation
Jump to: navigation, search
 
(10 intermediate revisions by 2 users not shown)
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=perl_lib/EPrints/DataObj/Document.pm|package_name=EPrints::DataObj::Document}}[[Category:API|DOCUMENT]][[Category:API:EPrints/DataObj|DOCUMENT]][[Category:API:EPrints/DataObj/Document|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%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=head_synopsis --></div>
+
<!-- Pod2Wiki= -->
==SYNOPSIS==
+
<!-- Pod2Wiki=head_description -->
  Inherrits all methods from EPrints::DataObj.
+
==DESCRIPTION==
 
+
Document represents a single format of an EPrint (eg. PDF) - the  actual file(s) rather than the metadata.
  # create a new document on $eprint
+
 
  my $doc_data = {
+
This class is a subclass of DataObj, with the following metadata fields:
    _parent =&gt; $eprint,
+
 
    eprintid =&gt; $eprint-&gt;get_id,
+
* 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.
  my $doc_ds = $handle-&gt;get_dataset( 'document' );
+
 
  my $document = $doc_ds-&gt;create_object( $handle, $doc_data );
+
: This should probably have been and "int" but isn't. I later version of EPrints may change this.
 
+
 
  # Add files to the document  
+
* eprintid (itemref)
  $success = $doc-&gt;add_file( $file, $filename, [$preserve_path] );
+
: The id number of the eprint to which this document belongs.
  $success = $doc-&gt;upload( $filehandle, $filename [, $preserve_path [, $filesize ] ] );
+
 
  $success = $doc-&gt;upload_archive( $filehandle, $filename, $archive_format );
+
* placement (int)
  $success = $doc-&gt;add_archive( $file, $archive_format );
+
: Placement of the document - the order documents should be shown in.
  $success = $doc-&gt;add_directory( $directory );
+
 
  $success = $doc-&gt;upload_url( $url );
+
* format (namedset)
 
+
: The format of this document. One of the types of the dataset "document".
  # get an existing document
+
 
  $document = $handle-&gt;get_document( $doc_id );
+
* formatdesc (text)
  # or
+
: An additional description of this document. For example the specific version of a format.
  foreach my $doc ( $eprint-&gt;get_all_documents ) { ... }
+
 
 
+
* language (namedset)
  # eprint to which this document belongs
+
: The ISO ID of the language of this document. The default configuration of EPrints does not set this.
  $eprint = $doc-&gt;get_eprint;
+
 
 
+
* security (namedset)
  # delete a document object *forever*:
+
: The security type of this document - who can view it. One of the types of the dataset "security".
  $success = $doc-&gt;remove;
+
 
 
+
* main (text)
  $url = $doc-&gt;get_url( [$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.
  $path = $doc-&gt;local_path;
+
 
  %files = $doc-&gt;files;
+
* files (subobject, multiple)
 
+
: A virtual field which represents the list of Files which are part of this record.
  # delete a file
+
 
  $success = $doc-&gt;remove_file( $filename );
+
* media
  # delete all files
+
: A compound field containing a description of the document media - dimensions, codec etc.
  $success = $doc-&gt;remove_all_files;
+
 
 
 
  # change the file which is used as the URL for the document.
 
  $doc-&gt;set_main( $main_file );
 
 
 
  # icons and previews
 
  $xhtml = $doc-&gt;render_icon_link( %opts );
 
  $xhtml = $doc-&gt;render_preview_link( %opts );
 
 
 
<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>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=head_description --></div>
+
<!-- Pod2Wiki= -->
==DESCRIPTION==
+
<!-- Pod2Wiki=head_methods -->
Document represents a single format of an EPrint (eg. PDF) - the actual file(s) rather than the metadata.
+
==METHODS==
 +
<!-- Pod2Wiki=head_get_system_field_info -->
 +
===get_system_field_info===
 +
 
 +
<source lang="perl">$metadata = EPrints::DataObj::Document->get_system_field_info
 +
 
 +
</source>
 +
Return an array describing the system metadata of the Document dataset.
 +
 
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_get_dataset_id -->
 +
===get_dataset_id===
 +
 
 +
<source lang="perl">$dataset = EPrints::DataObj::Document->get_dataset_id
  
This class is a subclass of DataObj, with the following metadata fields:  
+
</source>
 +
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%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_docid --></div>
+
<!-- Pod2Wiki= -->
===docid (text)===
+
<!-- Pod2Wiki=head_get_defaults -->
 +
===get_defaults===
  
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.
+
<source lang="perl">$defaults = EPrints::DataObj::Document->get_defaults( $session, $data )
  
This should probably have been and "int" but isn't. I later version of EPrints may change this.
+
</source>
 +
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%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_eprintid --></div>
+
<!-- Pod2Wiki= -->
===eprintid (itemref)===
+
<!-- Pod2Wiki=head_clone -->
 +
===clone===
 +
 
 +
<source lang="perl">$newdoc = $doc->clone( $eprint )
  
The id number of the eprint to which this document belongs.
+
</source>
 +
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%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_placement --></div>
+
<!-- Pod2Wiki= -->
===placement (int)===
+
<!-- Pod2Wiki=head_remove -->
 +
===remove===
  
Placement of the document - the order documents should be shown in.
+
<source lang="perl">$success = $doc->remove
 +
 
 +
</source>
 +
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%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_format --></div>
+
<!-- Pod2Wiki= -->
===format (namedset)===
+
<!-- Pod2Wiki=head_get_eprint -->
 +
===get_eprint===
  
The format of this document. One of the types of the dataset "document".
+
<source lang="perl">$eprint = $doc->get_eprint
 +
 
 +
</source>
 +
Return the EPrint this document is associated with.
 +
 
 +
This is a synonym for 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%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_formatdesc --></div>
+
<!-- Pod2Wiki= -->
===formatdesc (text)===
+
<!-- Pod2Wiki=head_get_baseurl -->
 +
===get_baseurl===
  
An additional description of this document. For example the specific version of a format.
+
<source lang="perl">$url = $doc->get_baseurl( [$staff] )
 +
 
 +
</source>
 +
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%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_language --></div>
+
<!-- Pod2Wiki= -->
===language (namedset)===
+
<!-- Pod2Wiki=head_is_public -->
 +
===is_public===
 +
 
 +
<source lang="perl">$boolean = $doc->is_public()
  
The ISO ID of the language of this document. The default configuration of EPrints does not set this.
+
</source>
 +
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%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_security --></div>
+
<!-- Pod2Wiki= -->
===security (namedset)===
+
<!-- Pod2Wiki=head_path -->
 +
===path===
  
The security type of this document - who can view it. One of the types of the namedset "security".
+
<source lang="perl">$path = $doc->path
 +
 
 +
</source>
 +
Returns the relative path to the document WITHOUT any file.
  
<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>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_content --></div>
+
<!-- Pod2Wiki= -->
===content (namedset)===
+
<!-- Pod2Wiki=head_file_path -->
 +
===file_path===
  
The type of content. Conceptual type, no format. ie. Supporting Material or published version. Values from namedset "content"
+
<source lang="perl">$path = $doc->file_path( [ $filename ] )
 +
 
 +
</source>
 +
Returns the relative path to $filename stored in this document. If $filename is undefined returns the path to the main file.
 +
 
 +
This is an efficient shortcut to this:
 +
 
 +
<pre> my $file = $doc-&gt;stored_file( $filename );
 +
  my $path = $file-&gt;path;</pre>
  
<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>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_license --></div>
+
<!-- Pod2Wiki= -->
===license (namedset)===
+
<!-- Pod2Wiki=head_get_url -->
 +
===get_url===
 +
 
 +
<source lang="perl">$url = $doc->get_url( [$file] )
 +
 
 +
</source>
 +
Return the full URL of the document. Overrides the stub in DataObj.
  
The type of license for the document. Such as GFDL or creative commons. Values from namedset "licenses"
+
If file is not specified then the "main" file is used.
  
<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>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_main --></div>
+
<!-- Pod2Wiki= -->
===main (text)===
+
<!-- Pod2Wiki=head_files -->
 +
===files===
 +
 
 +
<source lang="perl">%files = $doc->files
  
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.
+
</source>
 +
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%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_documents --></div>
+
<!-- Pod2Wiki= -->
===documents (subobject, multiple)===
+
<!-- Pod2Wiki=head_remove_file -->
 +
===remove_file===
  
A virtual field which represents the list of Documents which are part of this record.
+
<source lang="perl">$success = $doc->remove_file( $filename )
 +
 
 +
</source>
 +
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%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=head_methods --></div>
+
<!-- Pod2Wiki= -->
==METHODS==
+
<!-- Pod2Wiki=head_set_main -->
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
===set_main===
<h4><span style='display:none'>User Comments</span></h4>
+
 
 +
<source lang="perl">$doc->set_main( $main_file )
 +
 
 +
</source>
 +
Sets the main file and adjusts format and mime type as necessary. Won't affect the database until a $doc-&gt;commit().
 +
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_clone --></div>
+
<!-- Pod2Wiki= -->
===$newdoc = $doc-&gt;clone( $eprint )===
+
<!-- Pod2Wiki=head_get_main -->
 +
===get_main===
 +
 
 +
<source lang="perl">$filename = $doc->get_main
  
Attempt to clone this document. Both the document metadata and the actual files. The clone will be associated with the given EPrint.
+
</source>
 +
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%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_get_eprint --></div>
+
<!-- Pod2Wiki= -->
===$eprint = $doc-&gt;get_eprint===
+
<!-- Pod2Wiki=head_set_format -->
 +
===set_format===
  
Return the EPrint this document is associated with.
+
<source lang="perl">$doc->set_format( $format )
  
This is a synonym for get_parent().
+
</source>
 +
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%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_is_public --></div>
+
<!-- Pod2Wiki= -->
===$boolean = $doc-&gt;is_public()===
+
<!-- Pod2Wiki=head_set_format_desc -->
 +
===set_format_desc===
  
True if this document has no security set and is in the live archive.
+
<source lang="perl">$doc->set_format_desc( $format_desc )
 +
 
 +
</source>
 +
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%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_get_url --></div>
+
<!-- Pod2Wiki= -->
===$url = $doc-&gt;get_url( [$file] )===
+
<!-- Pod2Wiki=head_add_file -->
 +
===add_file===
  
Return the full URL of the document.
+
<source lang="perl">$fileobj = $doc->add_file( $file, $filename [, $preserve_path] )
  
If file is not specified then the "main" file is used.
+
</source>
 +
$file is the full path to a file to be added to the document, with name $filename. $filename is passed through [[API:EPrints/System#sanitise|EPrints::System/sanitise]] before being written.
 +
 
 +
If $preserve_path is true then include path components in $filename.
 +
 
 +
Returns the $fileobj created 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%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_local_path --></div>
+
<!-- Pod2Wiki= -->
===$path = $doc-&gt;local_path===
+
<!-- Pod2Wiki=head_add_archive -->
 +
===add_archive===
 +
 
 +
<source lang="perl">$success = $doc->add_archive( $file, $archive_format )
 +
 
 +
</source>
 +
$file is the full path to an archive file, eg. zip or .tar.gz
  
Return the full path of the directory where this document is stored in the filesystem.
+
This function will add the contents of that archive to the document.
  
<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>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_files --></div>
+
<!-- Pod2Wiki= -->
===%files = $doc-&gt;files===
+
<!-- Pod2Wiki=head_add_directory -->
 +
===add_directory===
 +
 
 +
<source lang="perl">$success = $doc->add_directory( $directory )
 +
 
 +
</source>
 +
Upload the contents of $directory to this document. This will not set the main file.
  
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.
+
This method expects $directory to have a trailing slash (/).
  
<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>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_remove_file --></div>
+
<!-- Pod2Wiki= -->
===$success = $doc-&gt;remove_file( $filename )===
+
<!-- Pod2Wiki=head_upload_url -->
 +
===upload_url===
  
Attempt to remove the given file. Give the filename as it is returned by get_files().
+
<source lang="perl">$success = $doc->upload_url( $url )
 +
 
 +
</source>
 +
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.
  
<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>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_remove_all_files --></div>
+
<!-- Pod2Wiki= -->
===$success = $doc-&gt;remove_all_files===
+
<!-- Pod2Wiki=head_commit -->
 +
===commit===
  
Attempt to remove all files associated with this document.
+
<source lang="perl">$success = $doc->commit
 +
 
 +
</source>
 +
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.
  
<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>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_set_main --></div>
+
<!-- Pod2Wiki= -->
===$doc-&gt;set_main( $main_file )===
+
<!-- Pod2Wiki=head_validate -->
 +
===validate===
  
Sets the main file. Won't affect the database until a $doc-&gt;commit().
+
<source lang="perl">$problems = $doc->validate( [$for_archive] )
  
This checks the file exists, so is more than an alias for get_value.
+
</source>
 +
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.
  
<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>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_upload --></div>
+
<!-- Pod2Wiki= -->
===$success = $doc-&gt;upload( $filehandle, $filename [, $preserve_path [, $filesize ] ] )===
+
<!-- Pod2Wiki=head_get_type -->
 +
===get_type===
  
Upload the contents of the given file handle into this document as the given filename.
+
<source lang="perl">$type = $doc->get_type
  
If $preserve_path then make any subdirectories needed, otherwise place this in the top level.
+
</source>
 +
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%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_add_file --></div>
+
<!-- Pod2Wiki= -->
===$success = $doc-&gt;add_file( $file, $filename, [$preserve_path] )===
+
<!-- Pod2Wiki=head_files_modified -->
 +
===files_modified===
  
$file is the full path to a file to be added to the document, with name $filename.
+
<source lang="perl">$doc->files_modified
  
If $preserve_path then keep the filename as is (including subdirs and spaces)
+
</source>
 +
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%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_upload_archive --></div>
+
<!-- Pod2Wiki= -->
===$success = $doc-&gt;upload_archive( $filehandle, $filename, $archive_format )===
+
<!-- Pod2Wiki=head_rehash -->
 +
===rehash===
  
Upload the contents of the given archive file. How to deal with the  archive format is configured in SystemSettings.
+
<source lang="perl">$doc->rehash
  
(In case the over-loading of the word "archive" is getting confusing, in this context we mean ".zip" or ".tar.gz" archive.)
+
</source>
 +
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%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_add_archive --></div>
+
<!-- Pod2Wiki= -->
===$success = $doc-&gt;add_archive( $file, $archive_format )===
+
<!-- Pod2Wiki=head_make_indexcodes -->
 +
===make_indexcodes===
  
$file is the full path to an archive file, eg. zip or .tar.gz
+
<source lang="perl">$doc = $doc->make_indexcodes()
  
This function will add the contents of that archive to the document.
+
</source>
 +
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%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_add_directory --></div>
+
<!-- Pod2Wiki= -->
===$success = $doc-&gt;add_directory( $directory )===
+
<!-- Pod2Wiki=head_remove_indexcodes -->
 +
===remove_indexcodes===
  
Upload the contents of $directory to this document. This will not set the main file.
+
<source lang="perl">$doc = $doc->remove_indexcodes()
  
This method expects $directory to have a trailing slash (/).
+
</source>
 +
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%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_upload_url --></div>
+
<!-- Pod2Wiki= -->
===$success = $doc-&gt;upload_url( $url )===
+
<!-- Pod2Wiki=head_render_icon_link -->
 +
===render_icon_link===
  
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.
+
<source lang="perl">$frag = $doc->render_icon_link( %opts )
 +
 
 +
</source>
 +
Render a link to the icon for this document.
 +
 
 +
Options:
 +
 
 +
* new_window =&gt; 1
 +
: Make link go to _blank not current window.
 +
 
 +
* preview =&gt; 1
 +
: If possible, provide a preview pop-up.
 +
 
 +
* public =&gt; 0
 +
: Show thumbnail/preview only on public docs.
  
This (by default) uses wget. The details can be configured in SystemSettings.
+
* public =&gt; 1
 +
: 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%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_new_window_1 --></div>
+
<!-- Pod2Wiki= -->
===new_window =&gt; 1===
+
<!-- Pod2Wiki=head_render_preview_link -->
 +
===render_preview_link===
  
Make link go to _blank not current window.
+
<source lang="perl">$frag = $doc->render_preview_link( %opts )
 +
 
 +
</source>
 +
Render a link to the preview for this document (if available) using a lightbox.
 +
 
 +
Options:
 +
 
 +
* caption =&gt; $frag
 +
: XHTML fragment to use as the caption, defaults to empty.
 +
 
 +
* 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).
  
<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>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_preview_1 --></div>
+
<!-- Pod2Wiki= -->
===preview =&gt; 1===
+
<!-- Pod2Wiki=head_add_relation -->
 +
===add_relation===
 +
 
 +
<source lang="perl">$doc->add_relation( $tgt, @types )
  
If possible, provide a preview pop-up.
+
</source>
 +
Add one or more relations to $doc pointing to $tgt (does not modify $tgt).
  
<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>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_public_0 --></div>
+
<!-- Pod2Wiki= -->
===public =&gt; 0===
+
<!-- Pod2Wiki=head_remove_relation -->
 +
===remove_relation===
 +
 
 +
<source lang="perl">$doc->remove_relation( $tgt [, @types ] )
 +
 
 +
</source>
 +
Removes the relations in $doc to $tgt. If @types isn't given removes all relations to $tgt. If $tgt is undefined removes all relations given in @types.
  
Show thumbnail/preview only on public docs.
+
If you want to remove all relations do $doc-&gt;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%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_public_1 --></div>
+
<!-- Pod2Wiki= -->
===public =&gt; 1===
+
<!-- Pod2Wiki=head_has_relation -->
 +
===has_relation===
 +
 
 +
<source lang="perl">$bool = $doc->has_relation( $tgt [, @types ] )
  
Show thumbnail/preview on all docs if poss.
+
</source>
 +
Returns true if $doc has relations to $tgt. If @types is given checks that $doc satisfies all of the given types. $tgt may be undefined.
  
<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>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_caption_frag --></div>
+
<!-- Pod2Wiki= -->
===caption =&gt; $frag===
+
<!-- Pod2Wiki=head_search_related -->
 +
===search_related===
  
XHTML fragment to use as the caption, defaults to empty.
+
<source lang="perl">$list = $doc->search_related( [ $type ] )
 +
 
 +
</source>
 +
Return a [[API:EPrints/List|EPrints::List]] that contains all documents related to this document. If $type is defined returns only those documents related by $type.
  
<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>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_set_foo --></div>
+
<!-- Pod2Wiki= -->
===set =&gt; "foo"===
+
<!-- Pod2Wiki=head_copyright -->
 +
==COPYRIGHT==
 +
Copyright 2000-2011 University of Southampton.
 +
 
 +
This file is part of EPrints http://www.eprints.org/.
 +
 
 +
EPrints is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
  
The name of the set this document belongs to, defaults to none (preview won't be shown as part of a set).
+
EPrints is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
 +
 
 +
You should have received a copy of the GNU Lesser General Public License along with EPrints.  If not, see http://www.gnu.org/licenses/.
  
<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>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=_postamble_ --><!-- Edit below this comment -->
+
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=_postamble_ -->
 +
<!-- Edit below this comment -->

Latest revision as of 09:57, 22 January 2013

EPrints 3 Reference: Directory Structure - Metadata Fields - Repository Configuration - XML Config Files - XML Export Format - EPrints data structure - Core API - Data Objects


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.


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:

  • 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.
  • eprintid (itemref)
The id number of the eprint to which this document belongs.
  • placement (int)
Placement of the document - the order documents should be shown in.
  • format (namedset)
The format of this document. One of the types of the dataset "document".
  • formatdesc (text)
An additional description of this document. For example the specific version of a format.
  • language (namedset)
The ISO ID 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 dataset "security".
  • 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.
  • files (subobject, multiple)
A virtual field which represents the list of Files which are part of this record.
  • media
A compound field containing a description of the document media - dimensions, codec etc.


METHODS

get_system_field_info

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

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


get_dataset_id

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

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


get_defaults

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

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


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.


remove

$success = $doc->remove

Attempt to completely delete this document


get_eprint

$eprint = $doc->get_eprint

Return the EPrint this document is associated with.

This is a synonym for get_parent().


get_baseurl

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

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


is_public

$boolean = $doc->is_public()

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


path

$path = $doc->path

Returns the relative path to the document WITHOUT any file.


file_path

$path = $doc->file_path( [ $filename ] )

Returns the relative path to $filename stored in this document. If $filename 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] )

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

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


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.


remove_file

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

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


set_main

$doc->set_main( $main_file )

Sets the main file and adjusts format and mime type as necessary. Won't affect the database until a $doc->commit().


get_main

$filename = $doc->get_main

Return the name of the main file in this document.


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 );


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 );


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 $fileobj created or undef on failure.


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.


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 (/).


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.


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.


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.


get_type

$type = $doc->get_type

Return the type of this document.


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

$doc = $doc->make_indexcodes()

Make the indexcodes document for this document. Returns the generated document 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.


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 docs.
  • public => 1
Show thumbnail/preview on all docs if poss.


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
XHTML fragment to use as the caption, defaults to empty.
  • set => "foo"
The name of the set this document belongs to, defaults to none (preview won't be shown as part of a set).


add_relation

$doc->add_relation( $tgt, @types )

Add one or more relations to $doc pointing to $tgt (does not modify $tgt).


remove_relation

$doc->remove_relation( $tgt [, @types ] )

Removes the relations in $doc to $tgt. If @types isn't given removes all relations to $tgt. If $tgt is undefined removes all relations given in @types.

If you want to remove all relations do $doc->set_value( "relation", [] );


has_relation

$bool = $doc->has_relation( $tgt [, @types ] )

Returns true if $doc has relations to $tgt. If @types is given checks that $doc satisfies all of the given types. $tgt may be undefined.


search_related

$list = $doc->search_related( [ $type ] )

Return a EPrints::List that contains all documents related to this document. If $type is defined returns only those documents related by $type.


COPYRIGHT

Copyright 2000-2011 University of Southampton.

This file is part of EPrints http://www.eprints.org/.

EPrints is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

EPrints is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with EPrints. If not, see http://www.gnu.org/licenses/.