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

From EPrints Documentation
Jump to: navigation, search
(New page: <!-- Pod2Wiki=_preamble_ This page has been automatically generated from the EPrints source. Any wiki changes made between the 'Pod2Wiki=*' and 'End of Pod2Wiki' comments will be lost. -...)
 
(Removing all content from page)
Line 1: Line 1:
<!-- Pod2Wiki=_preamble_
 
This page has been automatically generated from the EPrints source. Any wiki changes made between the 'Pod2Wiki=*' and 'End of Pod2Wiki' comments will be lost.
 
-->{{Pod2Wiki}}{{API:Source|file=EPrints/DataObj/Document.pm|package_name=EPrints::DataObj::Document}}[[Category:API|Document]]<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=head_name -->=NAME=
 
'''EPrints::DataObj::Document''' - A single format of a record.
 
  
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=head_description -->=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:
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_docid -->==docid==
 
 
  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.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_eprintid -->==eprintid==
 
 
  eprintid (itemref)
 
 
The id number of the eprint to which this document belongs.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_format -->==format==
 
 
  format (namedset)
 
 
The format of this document. One of the types of the dataset "document".
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_formatdesc -->==formatdesc==
 
 
  formatdesc (text)
 
 
An additional description of this document. For example the specific version of a format.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_language -->==language==
 
 
  language (namedset)
 
 
The ISO ID of the language of this document. The default configuration of EPrints does not set this.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_security -->==security==
 
 
  security (namedset)
 
 
The security type of this document - who can view it. One of the types of the dataset "security".
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_main -->==main==
 
 
  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.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_documents -->==documents==
 
 
  documents (subobject, multiple)
 
 
A virtual field which represents the list of Documents which are part of this record.
 
 
<!-- End of Pod2Wiki -->
 
<!-- 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.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_new -->==new==
 
 
  $thing = EPrints::DataObj::Document-&gt;new( $session, $docid )
 
 
Return the document with the given $docid, or undef if it does not exist.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_new_from_data -->==new_from_data==
 
 
  $doc = EPrints::DataObj::Document-&gt;new_from_data( $session, $data )
 
 
Construct a new EPrints::DataObj::Document based on the ref to a hash of metadata.
 
 
<!-- End of Pod2Wiki -->
 
<!-- 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.
 
 
<!-- End of Pod2Wiki -->
 
<!-- 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.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_remove -->==remove==
 
 
  $success = $doc-&gt;remove
 
 
Attempt to completely delete this document
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_eprint -->==get_eprint==
 
 
  $eprint = $doc-&gt;get_eprint
 
 
Return the EPrint this document is associated with.
 
 
<!-- End of Pod2Wiki -->
 
<!-- 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.
 
 
<!-- End of Pod2Wiki -->
 
<!-- 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.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_url -->==get_url==
 
 
  $url = $doc-&gt;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.
 
 
<!-- End of Pod2Wiki -->
 
<!-- 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.
 
 
<!-- End of Pod2Wiki -->
 
<!-- 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.
 
 
<!-- End of Pod2Wiki -->
 
<!-- 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().
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_remove_all_files -->==remove_all_files==
 
 
  $success = $doc-&gt;remove_all_files
 
 
Attempt to remove all files associated with this document.
 
 
<!-- End of Pod2Wiki -->
 
<!-- 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().
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_main -->==get_main==
 
 
  $filename = $doc-&gt;get_main
 
 
Return the name of the main file in this document.
 
 
<!-- End of Pod2Wiki -->
 
<!-- 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 );
 
 
<!-- End of Pod2Wiki -->
 
<!-- 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 );
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_upload -->==upload==
 
 
  $success = $doc-&gt;upload( $filehandle, $filename, [$preserve_path] )
 
 
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.
 
 
<!-- End of Pod2Wiki -->
 
<!-- 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.
 
 
If $preserve_path then keep the filename as is (including subdirs and spaces)
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_sanitise -->==sanitise==
 
 
  $cleanfilename = sanitise( $filename )
 
 
Return just the filename (no leading path) and convert any naughty characters to underscore.
 
 
<!-- End of Pod2Wiki -->
 
<!-- 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.
 
 
(In case the over-loading of the word "archive" is getting confusing,  in this context we mean ".zip" or ".tar.gz" archive.)
 
 
<!-- End of Pod2Wiki -->
 
<!-- 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
 
 
This function will add the contents of that archive to the document.
 
 
<!-- End of Pod2Wiki -->
 
<!-- 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.
 
 
This (by default) uses wget. The details can be configured in SystemSettings.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_commit -->==commit==
 
 
  $success = $doc-&gt;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.
 
 
<!-- End of Pod2Wiki -->
 
<!-- 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.
 
 
A reference to an empty array indicates no problems.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_type -->==get_type==
 
 
  $type = $doc-&gt;get_type
 
 
Return the type of this document.
 
 
<!-- End of Pod2Wiki -->
 
<!-- 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.
 
 
<!-- End of Pod2Wiki -->
 
<!-- 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.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_text -->==get_text==
 
 
  $text = $doc-&gt;get_text
 
 
Get the text of the document as a UTF-8 encoded string, if possible.
 
 
This is used for full-text indexing. The text will probably not be well formated.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_words_file -->==words_file==
 
 
  $filename = $doc-&gt;words_file
 
 
Return the filename in which this document uses to cache words  extracted from the full text.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_indexcodes_file -->==indexcodes_file==
 
 
  $filename = $doc-&gt;indexcodes_file
 
 
Return the filename in which this document uses to cache indexcodes  extracted from the words cache file.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_cache_file -->==cache_file==
 
 
  $filename = $doc-&gt;cache_file( $suffix );
 
 
Return a cache filename for this document with the givven suffix.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=head_undocumented_methods -->=UNDOCUMENTED METHODS=
 
{{API:Undocumented Methods}}<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_create -->==create==
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_create_from_data -->==create_from_data==
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_doc_with_eprintid_and_pos -->==doc_with_eprintid_and_pos==
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_icon_url -->==icon_url==
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_main_input_tags -->==main_input_tags==
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_main_render_option -->==main_render_option==
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_make_thumbnails -->==make_thumbnails==
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_mime_type -->==mime_type==
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_register_parent -->==register_parent==
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_remove_thumbnails -->==remove_thumbnails==
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_icon_link -->==render_icon_link==
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_thumbnail_path -->==thumbnail_path==
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_thumbnail_plugin -->==thumbnail_plugin==
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_thumbnail_url -->==thumbnail_url==
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_user_can_view -->==user_can_view==
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=_postamble_ --><!-- End of Pod2Wiki -->
 

Revision as of 15:39, 12 August 2009