|
|
| 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->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->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->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->get_defaults( $session, $data )
| |
| − |
| |
| − | Return default values for this object based on the starting data.
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_clone -->==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.
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_remove -->==remove==
| |
| − |
| |
| − | $success = $doc->remove
| |
| − |
| |
| − | Attempt to completely delete this document
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_get_eprint -->==get_eprint==
| |
| − |
| |
| − | $eprint = $doc->get_eprint
| |
| − |
| |
| − | Return the EPrint this document is associated with.
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_get_baseurl -->==get_baseurl==
| |
| − |
| |
| − | $url = $doc->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->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->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->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->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.
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_remove_file -->==remove_file==
| |
| − |
| |
| − | $success = $doc->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->remove_all_files
| |
| − |
| |
| − | Attempt to remove all files associated with this document.
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_set_main -->==set_main==
| |
| − |
| |
| − | $doc->set_main( $main_file )
| |
| − |
| |
| − | Sets the main file. Won't affect the database until a $doc->commit().
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_get_main -->==get_main==
| |
| − |
| |
| − | $filename = $doc->get_main
| |
| − |
| |
| − | Return the name of the main file in this document.
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_set_format -->==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 );
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_set_format_desc -->==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 );
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_upload -->==upload==
| |
| − |
| |
| − | $success = $doc->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->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->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->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->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->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->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->get_type
| |
| − |
| |
| − | Return the type of this document.
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_files_modified -->==files_modified==
| |
| − |
| |
| − | $doc->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->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->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->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->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->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 -->
| |
