- 1 NAME
- 2 DESCRIPTION
- 2.1 docid
- 2.2 eprintid
- 2.3 format
- 2.4 formatdesc
- 2.5 language
- 2.6 security
- 2.7 main
- 2.8 documents
- 2.9 get_system_field_info
- 2.10 new
- 2.11 new_from_data
- 2.12 get_defaults
- 2.13 clone
- 2.14 remove
- 2.15 get_eprint
- 2.16 get_baseurl
- 2.17 is_public
- 2.18 get_url
- 2.19 local_path
- 2.20 files
- 2.21 remove_file
- 2.22 remove_all_files
- 2.23 set_main
- 2.24 get_main
- 2.25 set_format
- 2.26 set_format_desc
- 2.27 upload
- 2.28 add_file
- 2.29 sanitise
- 2.30 upload_archive
- 2.31 add_archive
- 2.32 upload_url
- 2.33 commit
- 2.34 validate
- 2.35 get_type
- 2.36 files_modified
- 2.37 rehash
- 2.38 get_text
- 2.39 words_file
- 2.40 indexcodes_file
- 2.41 cache_file
- 3 UNDOCUMENTED METHODS
EPrints::DataObj::Document - A single format of a record.
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:
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.
The id number of the eprint to which this document belongs.
The format of this document. One of the types of the dataset "document".
An additional description of this document. For example the specific version of a format.
The ISO ID of the language of this document. The default configuration of EPrints does not set this.
The security type of this document - who can view it. One of the types of the dataset "security".
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.
documents (subobject, multiple)
A virtual field which represents the list of Documents which are part of this record.
$metadata = EPrints::DataObj::Document->get_system_field_info
Return an array describing the system metadata of the Document dataset.
$thing = EPrints::DataObj::Document->new( $session, $docid )
Return the document with the given $docid, or undef if it does not exist.
$doc = EPrints::DataObj::Document->new_from_data( $session, $data )
Construct a new EPrints::DataObj::Document based on the ref to a hash of metadata.
$defaults = EPrints::DataObj::Document->get_defaults( $session, $data )
Return default values for this object based on the starting data.
$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.
$success = $doc->remove
Attempt to completely delete this document
$eprint = $doc->get_eprint
Return the EPrint this document is associated with.
$url = $doc->get_baseurl( [$staff] )
Return the base URL of the document. Overrides the stub in DataObj. $staff is currently ignored.
$boolean = $doc->is_public()
True if this document has no security set and is in the live archive.
$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.
$path = $doc->local_path
Return the full path of the directory where this document is stored in the filesystem.
%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.
$success = $doc->remove_file( $filename )
Attempt to remove the given file. Give the filename as it is returned by get_files().
$success = $doc->remove_all_files
Attempt to remove all files associated with this document.
$doc->set_main( $main_file )
Sets the main file. Won't affect the database until a $doc->commit().
$filename = $doc->get_main
Return the name of the main file in this document.
$doc->set_format( $format )
Set format. Won't affect the database until a commit(). Just an alias for $doc->set_value( "format" , $format );
$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 );
$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.
$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)
$cleanfilename = sanitise( $filename )
Return just the filename (no leading path) and convert any naughty characters to underscore.
$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.)
$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.
$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.
$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.
$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.
$type = $doc->get_type
Return the type of this document.
This method does all the things that need doing when a file has been modified.
Recalculate the hash value of the document. Uses MD5 of the files (in alphabetic order), but can use user specified hashing function instead.
$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.
$filename = $doc->words_file
Return the filename in which this document uses to cache words extracted from the full text.
$filename = $doc->indexcodes_file
Return the filename in which this document uses to cache indexcodes extracted from the words cache file.
$filename = $doc->cache_file( $suffix );
Return a cache filename for this document with the givven suffix.