Difference between revisions of "API:EPrints/DataObj/Document"
| Line 1: | Line 1: | ||
| − | + | <!-- 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. | ||
| + | --> | ||
| + | __NOTOC__ | ||
| + | {{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> | ||
| + | ==NAME== | ||
| + | '''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%; '> | ||
| + | <h4><span style='display:none'>User Comments</span></h4> | ||
| + | <!-- Edit below this comment --> | ||
| + | |||
| + | |||
| + | <!-- Pod2Wiki=head_synopsis --></div> | ||
| + | ==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 ); | ||
| + | |||
| + | <div style='background-color: #eef; 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 --> | ||
| + | |||
| + | |||
| + | <!-- Pod2Wiki=head_description --></div> | ||
| + | ==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: | ||
| + | |||
| + | <div style='background-color: #eef; 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 --> | ||
| + | |||
| + | |||
| + | <!-- Pod2Wiki=item_docid --></div> | ||
| + | ===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. | ||
| + | |||
| + | <div style='background-color: #eef; 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 --> | ||
| + | |||
| + | |||
| + | <!-- Pod2Wiki=item_eprintid --></div> | ||
| + | ===eprintid (itemref)=== | ||
| + | |||
| + | 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%; '> | ||
| + | <h4><span style='display:none'>User Comments</span></h4> | ||
| + | <!-- Edit below this comment --> | ||
| + | |||
| + | |||
| + | <!-- Pod2Wiki=item_placement --></div> | ||
| + | ===placement (int)=== | ||
| + | |||
| + | 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%; '> | ||
| + | <h4><span style='display:none'>User Comments</span></h4> | ||
| + | <!-- Edit below this comment --> | ||
| + | |||
| + | |||
| + | <!-- Pod2Wiki=item_format --></div> | ||
| + | ===format (namedset)=== | ||
| + | |||
| + | 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%; '> | ||
| + | <h4><span style='display:none'>User Comments</span></h4> | ||
| + | <!-- Edit below this comment --> | ||
| + | |||
| + | |||
| + | <!-- Pod2Wiki=item_formatdesc --></div> | ||
| + | ===formatdesc (text)=== | ||
| + | |||
| + | 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%; '> | ||
| + | <h4><span style='display:none'>User Comments</span></h4> | ||
| + | <!-- Edit below this comment --> | ||
| + | |||
| + | |||
| + | <!-- Pod2Wiki=item_language --></div> | ||
| + | ===language (namedset)=== | ||
| + | |||
| + | 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%; '> | ||
| + | <h4><span style='display:none'>User Comments</span></h4> | ||
| + | <!-- Edit below this comment --> | ||
| + | |||
| + | |||
| + | <!-- Pod2Wiki=item_security --></div> | ||
| + | ===security (namedset)=== | ||
| + | |||
| + | 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%; '> | ||
| + | <h4><span style='display:none'>User Comments</span></h4> | ||
| + | <!-- Edit below this comment --> | ||
| + | |||
| + | |||
| + | <!-- Pod2Wiki=item_content --></div> | ||
| + | ===content (namedset)=== | ||
| + | |||
| + | 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%; '> | ||
| + | <h4><span style='display:none'>User Comments</span></h4> | ||
| + | <!-- Edit below this comment --> | ||
| + | |||
| + | |||
| + | <!-- Pod2Wiki=item_license --></div> | ||
| + | ===license (namedset)=== | ||
| + | |||
| + | 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%; '> | ||
| + | <h4><span style='display:none'>User Comments</span></h4> | ||
| + | <!-- Edit below this comment --> | ||
| + | |||
| + | |||
| + | <!-- Pod2Wiki=item_main --></div> | ||
| + | ===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. | ||
| + | |||
| + | <div style='background-color: #eef; 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 --> | ||
| + | |||
| + | |||
| + | <!-- Pod2Wiki=item_documents --></div> | ||
| + | ===documents (subobject, multiple)=== | ||
| + | |||
| + | 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%; '> | ||
| + | <h4><span style='display:none'>User Comments</span></h4> | ||
| + | <!-- Edit below this comment --> | ||
| + | |||
| + | |||
| + | <!-- Pod2Wiki=head_methods --></div> | ||
| + | ==METHODS== | ||
| + | <div style='background-color: #eef; 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 --> | ||
| + | |||
| + | |||
| + | <!-- Pod2Wiki=item_clone --></div> | ||
| + | ===$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. | ||
| + | |||
| + | <div style='background-color: #eef; 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 --> | ||
| + | |||
| + | |||
| + | <!-- Pod2Wiki=item_get_eprint --></div> | ||
| + | ===$eprint = $doc->get_eprint=== | ||
| + | |||
| + | Return the EPrint this document is associated with. | ||
| + | |||
| + | 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%; '> | ||
| + | <h4><span style='display:none'>User Comments</span></h4> | ||
| + | <!-- Edit below this comment --> | ||
| + | |||
| + | |||
| + | <!-- Pod2Wiki=item_is_public --></div> | ||
| + | ===$boolean = $doc->is_public()=== | ||
| + | |||
| + | 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%; '> | ||
| + | <h4><span style='display:none'>User Comments</span></h4> | ||
| + | <!-- Edit below this comment --> | ||
| + | |||
| + | |||
| + | <!-- Pod2Wiki=item_get_url --></div> | ||
| + | ===$url = $doc->get_url( [$file] )=== | ||
| + | |||
| + | Return the full URL of the document. | ||
| + | |||
| + | 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%; '> | ||
| + | <h4><span style='display:none'>User Comments</span></h4> | ||
| + | <!-- Edit below this comment --> | ||
| + | |||
| + | |||
| + | <!-- Pod2Wiki=item_local_path --></div> | ||
| + | ===$path = $doc->local_path=== | ||
| + | |||
| + | 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%; '> | ||
| + | <h4><span style='display:none'>User Comments</span></h4> | ||
| + | <!-- Edit below this comment --> | ||
| + | |||
| + | |||
| + | <!-- Pod2Wiki=item_files --></div> | ||
| + | ===%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. | ||
| + | |||
| + | <div style='background-color: #eef; 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 --> | ||
| + | |||
| + | |||
| + | <!-- Pod2Wiki=item_remove_file --></div> | ||
| + | ===$success = $doc->remove_file( $filename )=== | ||
| + | |||
| + | 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%; '> | ||
| + | <h4><span style='display:none'>User Comments</span></h4> | ||
| + | <!-- Edit below this comment --> | ||
| + | |||
| + | |||
| + | <!-- Pod2Wiki=item_remove_all_files --></div> | ||
| + | ===$success = $doc->remove_all_files=== | ||
| + | |||
| + | 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%; '> | ||
| + | <h4><span style='display:none'>User Comments</span></h4> | ||
| + | <!-- Edit below this comment --> | ||
| + | |||
| + | |||
| + | <!-- Pod2Wiki=item_set_main --></div> | ||
| + | ===$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. | ||
| + | |||
| + | <div style='background-color: #eef; 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 --> | ||
| + | |||
| + | |||
| + | <!-- Pod2Wiki=item_upload --></div> | ||
| + | ===$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. | ||
| + | |||
| + | <div style='background-color: #eef; 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 --> | ||
| + | |||
| + | |||
| + | <!-- Pod2Wiki=item_add_file --></div> | ||
| + | ===$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) | ||
| + | |||
| + | <div style='background-color: #eef; 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 --> | ||
| + | |||
| + | |||
| + | <!-- Pod2Wiki=item_upload_archive --></div> | ||
| + | ===$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.) | ||
| + | |||
| + | <div style='background-color: #eef; 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 --> | ||
| + | |||
| + | |||
| + | <!-- Pod2Wiki=item_add_archive --></div> | ||
| + | ===$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. | ||
| + | |||
| + | <div style='background-color: #eef; 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 --> | ||
| + | |||
| + | |||
| + | <!-- Pod2Wiki=item_add_directory --></div> | ||
| + | ===$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 (/). | ||
| + | |||
| + | <div style='background-color: #eef; 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 --> | ||
| + | |||
| + | |||
| + | <!-- Pod2Wiki=item_upload_url --></div> | ||
| + | ===$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. | ||
| + | |||
| + | <div style='background-color: #eef; 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 --> | ||
| + | |||
| + | |||
| + | <!-- Pod2Wiki=item_new_window_1 --></div> | ||
| + | ===new_window => 1=== | ||
| + | |||
| + | 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%; '> | ||
| + | <h4><span style='display:none'>User Comments</span></h4> | ||
| + | <!-- Edit below this comment --> | ||
| + | |||
| + | |||
| + | <!-- Pod2Wiki=item_preview_1 --></div> | ||
| + | ===preview => 1=== | ||
| + | |||
| + | 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%; '> | ||
| + | <h4><span style='display:none'>User Comments</span></h4> | ||
| + | <!-- Edit below this comment --> | ||
| + | |||
| + | |||
| + | <!-- Pod2Wiki=item_public_0 --></div> | ||
| + | ===public => 0=== | ||
| + | |||
| + | 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%; '> | ||
| + | <h4><span style='display:none'>User Comments</span></h4> | ||
| + | <!-- Edit below this comment --> | ||
| + | |||
| + | |||
| + | <!-- Pod2Wiki=item_public_1 --></div> | ||
| + | ===public => 1=== | ||
| + | |||
| + | 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%; '> | ||
| + | <h4><span style='display:none'>User Comments</span></h4> | ||
| + | <!-- Edit below this comment --> | ||
| + | |||
| + | |||
| + | <!-- Pod2Wiki=item_caption_frag --></div> | ||
| + | ===caption => $frag=== | ||
| + | |||
| + | 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%; '> | ||
| + | <h4><span style='display:none'>User Comments</span></h4> | ||
| + | <!-- Edit below this comment --> | ||
| + | |||
| + | |||
| + | <!-- Pod2Wiki=item_set_foo --></div> | ||
| + | ===set => "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: #eef; 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 --> | ||
| + | |||
| + | |||
| + | <!-- Pod2Wiki=_postamble_ --><!-- Edit below this comment --> | ||
Revision as of 16:00, 19 August 2009
Latest Source Code (3.4, 3.3) | Revision Log | Before editing this page please read Pod2Wiki
NAME
EPrints::DataObj::Document - A single format of a record.
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 );
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 namedset "security".
content (namedset)
The type of content. Conceptual type, no format. ie. Supporting Material or published version. Values from namedset "content"
license (namedset)
The type of license for the document. Such as GFDL or creative commons. Values from namedset "licenses"
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.
documents (subobject, multiple)
A virtual field which represents the list of Documents which are part of this record.
METHODS
$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.
$eprint = $doc->get_eprint
Return the EPrint this document is associated with.
This is a synonym for get_parent().
$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.
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().
This checks the file exists, so is more than an alias for get_value.
$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.
$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)
$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->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 (/).
$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.
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.
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).
