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

From EPrints Documentation
Jump to: navigation, search
(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/EPrint.pm|package_name=EPrints::DataObj::EPrint}}[[Category:API|EPrint]]<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=head_name -->=NAME=
 
'''EPrints::DataObj::EPrint''' - Class representing an actual EPrint
 
  
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=head_description -->=DESCRIPTION=
 
This class represents a single eprint record and the metadata  associated with it. This is associated with one of more  EPrint::Document objects.
 
 
EPrints::DataObj::EPrint is a subclass of EPrints::DataObj with the following metadata fields (plus those defined in ArchiveMetadataFieldsConfig):
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=head_system_metadata -->=SYSTEM METADATA=
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_eprintid -->==eprintid==
 
 
  eprintid (int)
 
 
The unique numerical ID of this eprint.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_rev_number -->==rev_number==
 
 
  rev_number (int)
 
 
The number of the current revision of this record.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_userid -->==userid==
 
 
  userid (itemref)
 
 
The id of the user who deposited this eprint (if any). Scripted importing could cause this not to be set.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_dir -->==dir==
 
 
  dir (text)
 
 
The directory, relative to the documents directory for this repository, which this eprints data is stored in. Eg. disk0/00/00/03/34 for record 334.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_datestamp -->==datestamp==
 
 
  datestamp (time)
 
 
The date this record first appeared live in the repository.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_lastmod -->==lastmod==
 
 
  lastmod (time)
 
 
The date this record was last modified.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_status_changes -->==status_changes==
 
 
  status_changes (time)
 
 
The date/time this record was moved between inbox, buffer, archive, etc.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_type -->==type==
 
 
  type (namedset)
 
 
The type of this record, one of the types of the "eprint" dataset.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_succeeds -->==succeeds==
 
 
  succeeds (itemref)
 
 
The ID of the eprint (if any) which this succeeds.  This field should have been an int and may be changed in a later upgrade.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_commentary -->==commentary==
 
 
  commentary (itemref)
 
 
The ID of the eprint (if any) which this eprint is a commentary on.  This  field should have been an int and may be changed in a later upgrade.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_replacedby -->==replacedby==
 
 
  replacedby (itemref)
 
 
The ID of the eprint (if any) which has replaced this eprint. This is only set on records in the "deletion" dataset.  This field should have been an int and may be changed in a later upgrade.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=head_methods -->=METHODS=
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_system_field_info -->==get_system_field_info==
 
 
  $metadata = EPrints::DataObj::EPrint-&gt;get_system_field_info
 
 
Return an array describing the system metadata of the EPrint dataset.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_new -->==new==
 
 
  $eprint = EPrints::DataObj::EPrint-&gt;new( $session, $eprint_id )
 
 
Return the eprint with the given eprint_id, or undef if it does not exist.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_new_from_data -->==new_from_data==
 
 
  $eprint = EPrints::DataObj::EPrint-&gt;new_from_data( $session, $data, $dataset )
 
 
Construct a new EPrints::DataObj::EPrint object based on the $data hash  reference of metadata.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_gid -->==get_gid==
 
 
  $dataset = $eprint-&gt;get_gid
 
 
Returns the OAI identifier for this eprint.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_dataset -->==get_dataset==
 
 
  $dataset = $eprint-&gt;get_dataset
 
 
Return the dataset to which this object belongs. This will return one of the virtual datasets: inbox, buffer, archive or deletion.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_defaults -->==get_defaults==
 
 
  $defaults = EPrints::DataObj::EPrint-&gt;get_defaults( $session, $data )
 
 
Return default values for this object based on the starting data.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_clone -->==clone==
 
 
  $eprint = $eprint-&gt;clone( $dest_dataset, $copy_documents, $link )
 
 
Create a copy of this EPrint with a new ID in the given dataset. Return the new eprint, or undef in the case of an error.
 
 
If $copy_documents is set and true then the documents (and files) will be copied in addition to the metadata.
 
 
If $nolink is true then the new eprint is not connected to the old one.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_log_mail_owner -->==log_mail_owner==
 
 
  $eprint-&gt;log_mail_owner( $mail )
 
 
Log that the given mail message was send to the owner of this EPrint.
 
 
$mail is the same XHTML DOM that was sent as the email.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_editorial_contact -->==get_editorial_contact==
 
 
  $user = $eprint-&gt;get_editorial_contact
 
 
Return the user identified as the editorial contact for this item.
 
 
By default returns undef.
 
 
nb. This has nothing to do with the editor defined in the metadata
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_remove -->==remove==
 
 
  $success = $eprint-&gt;remove
 
 
Erase this eprint and any associated records from the database and filesystem.
 
 
This should only be called on eprints in "inbox" or "buffer".
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_commit -->==commit==
 
 
  $success = $eprint-&gt;commit( [$force] );
 
 
Commit any changes that might have been made to the database.
 
 
If the item has not be changed then this function does nothing unless $force is true.
 
 
Calls {{API:PodLink|file=|package_name=|section=set_eprint_automatic_fields|text=/set_eprint_automatic_fields}} just before the <tt>$eprint</tt> is committed.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_write_revision -->==write_revision==
 
 
  $eprint-&gt;write_revision
 
 
Write out a snapshot of the XML describing the current state of the eprint.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_validate -->==validate==
 
 
  $problems = $eprint-&gt;validate( [$for_archive], $workflow_id )
 
 
Return a reference to an array of XHTML DOM objects describing validation problems with the entire eprint based on $workflow_id.
 
 
If $workflow_id is undefined defaults to "default".
 
 
A reference to an empty array indicates no problems.
 
 
Calls {{API:PodLink|file=|package_name=|section=validate_eprint|text=/validate_eprint}} for the <tt>$eprint</tt>.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_warnings -->==get_warnings==
 
 
  $warnings = $eprint-&gt;get_warnings
 
 
Return a reference to an array of XHTML DOM objects describing warnings about this eprint - that is things that are not quite  validation errors, but it'd be nice if they were fixed.
 
 
Calls {{API:PodLink|file=|package_name=|section=eprint_warnings|text=/eprint_warnings}} for the <tt>$eprint</tt>.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_skip_validation -->==skip_validation==
 
 
  $boolean = $eprint-&gt;skip_validation
 
 
Returns true if this eprint should pass validation without being properly validated. This is to allow the use of dodgey data imported from legacy systems.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_prune_documents -->==prune_documents==
 
 
  $eprint-&gt;prune_documents
 
 
Remove any documents associated with this eprint which don't actually have any files.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_all_documents -->==get_all_documents==
 
 
  @documents = $eprint-&gt;get_all_documents
 
 
Return an array of all EPrint::Document objects associated with this eprint.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_required_formats -->==required_formats==
 
 
  @formats =  $eprint-&gt;required_formats
 
 
Return a list of the required formats for this  eprint. Only one of the required formats is required, not all.
 
 
An empty list means no format is required.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_move_to_deletion -->==move_to_deletion==
 
 
  $success = $eprint-&gt;move_to_deletion
 
 
Transfer the EPrint into the "deletion" dataset. Should only be called in eprints in the "archive" dataset.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_move_to_inbox -->==move_to_inbox==
 
 
  $success = $eprint-&gt;move_to_inbox
 
 
Transfer the EPrint into the "inbox" dataset. Should only be called in eprints in the "buffer" dataset.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_move_to_buffer -->==move_to_buffer==
 
 
  $success = $eprint-&gt;move_to_buffer
 
 
Transfer the EPrint into the "buffer" dataset. Should only be called in eprints in the "inbox" or "archive" dataset.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_move_to_archive -->==move_to_archive==
 
 
  $success = $eprint-&gt;move_to_archive
 
 
Move this eprint into the main "archive" dataset. Normally only called on eprints in "deletion" or "buffer" datasets.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_local_path -->==local_path==
 
 
  $path = $eprint-&gt;local_path
 
 
Return the full path of the EPrint directory on the local filesystem. No trailing slash.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_url_stem -->==url_stem==
 
 
  $url = $eprint-&gt;url_stem
 
 
Return the URL to this EPrint's directory. Note, this INCLUDES the trailing slash, unlike the local_path method.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_generate_static -->==generate_static==
 
 
  $eprint-&gt;generate_static
 
 
Generate the static version of the abstract web page. In a multi-language repository this will generate one version per language.
 
 
If called on inbox or buffer, remove the abstract page.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_generate_static_all_related -->==generate_static_all_related==
 
 
  $eprint-&gt;generate_static_all_related
 
 
Generate the static pages for this eprint plus any it's related to, by succession or commentary.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_remove_static -->==remove_static==
 
 
  $eprint-&gt;remove_static
 
 
Remove the static web page or pages.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render -->==render==
 
 
  ( $description, $title, $links ) = $eprint-&gt;render
 
 
Render the eprint. The 3 returned values are references to XHTML DOM objects. $description is the public viewable description of this eprint that appears as the body of the abstract page. $title is the title of the abstract page for this eprint. $links is any elements which should go in the &lt;head&gt; of this page.
 
 
Calls {{API:PodLink|file=|package_name=|section=eprint_render|text=/eprint_render}} to actually render the <tt>$eprint</tt>, if it isn't deleted.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_history -->==render_history==
 
 
  ( $html ) = $eprint-&gt;render_history
 
 
Render the history of this eprint as XHTML DOM.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_control_url -->==get_control_url==
 
 
  $url = $eprint-&gt;get_control_url
 
 
Return the URL of the control page for this eprint.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_url -->==get_url==
 
 
  $url = $eprint-&gt;get_url
 
 
Return the public URL of this eprints abstract page.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_user -->==get_user==
 
 
  $user = $eprint-&gt;get_user
 
 
Return the EPrints::User to whom this eprint belongs (if any).
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_eprintid_to_path -->==eprintid_to_path==
 
 
  $path = EPrints::DataObj::EPrint::eprintid_to_path( $eprintid )
 
 
Return this eprints id converted into directories. Thousands of  files in one directory cause problems. For example, the eprint with the  id 50344 would have the path 00/05/03/44.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_all_related -->==get_all_related==
 
 
  @eprints = $eprint-&gt;get_all_related
 
 
Return the eprints that are related in some way to this in a succession or commentary thread. The returned list does NOT include this EPrint.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_in_thread -->==in_thread==
 
 
  $boolean = $eprint-&gt;in_thread( $field )
 
 
Return true if this eprint is part of a thread of $field. $field should be an EPrint::MetaField representing either "commentary" or "succeeds".
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_first_in_thread -->==first_in_thread==
 
 
  $eprint = $eprint-&gt;first_in_thread( $field )
 
 
Return the first (earliest) version or first paper in the thread of commentaries of this paper in the repository.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_later_in_thread -->==later_in_thread==
 
 
  @eprints = $eprint-&gt;later_in_thread( $field )
 
 
Return a list of the immediately later items in the thread.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_all_in_thread -->==all_in_thread==
 
 
  @eprints = $eprint-&gt;all_in_thread( $field )
 
 
Return all of the EPrints in the given thread.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_last_in_thread -->==last_in_thread==
 
 
  $eprint = $eprint-&gt;last_in_thread( $field )
 
 
Return the last item in the specified thread.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_remove_from_threads -->==remove_from_threads==
 
 
  $eprint-&gt;remove_from_threads
 
 
Extract the eprint from any threads it's in. i.e., if any other paper is a later version of or commentary on this paper, the link from that paper to this will be removed.
 
 
Abstract pages are updated if needed.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_version_thread -->==render_version_thread==
 
 
  $xhtml = $eprint-&gt;render_version_thread( $field )
 
 
Render XHTML DOM describing the entire thread as nested unordered lists.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_loop_error -->==loop_error==
 
 
  $eprint-&gt;loop_error( $field, @looped_ids )
 
 
This eprint is part of a threading loop which is not allowed. Log a warning.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_type -->==get_type==
 
 
  $type = $eprint-&gt;get_type
 
 
Return the type of this eprint.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_export_links -->==render_export_links==
 
 
  $xhtml_ul_list = $eprint-&gt;render_export_links( [$staff] )
 
 
Return a &lt;ul&gt; list containing links to all the formats this eprint is available in.
 
 
If $staff is true then show all formats available to staff, and link to the staff export URL.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_user_roles -->==user_roles==
 
 
  @roles = $eprint-&gt;user_roles( $user )
 
 
Return the @roles $user has on $eprint.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_datestamp -->==datestamp==
 
 
  $eprint-&gt;datestamp
 
 
DEPRECATED.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_in_editorial_scope_of -->==in_editorial_scope_of==
 
 
  $boolean = $eprint-&gt;in_editorial_scope_of( $possible_editor )
 
 
Returns true if $possible_editor can edit this eprint. This is according to the user editperms.
 
 
This does not mean the user has the editor priv., just that if they do then they may edit the given item.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_has_owner -->==has_owner==
 
 
  $boolean = $eprint-&gt;has_owner( $possible_owner )
 
 
Returns true if $possible_owner can edit this eprint. This is according to the user editperms.
 
 
This does not mean the user has the editor priv., just that if they do then they may edit the given item.
 
 
Uses the callback "does_user_own_eprint" if available.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=head_callbacks -->=CALLBACKS=
 
Callbacks may optionally be defined in the ArchiveConfig.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_validate_field -->==validate_field==
 
 
  validate_field( $field, $value, $session, [$for_archive] )
 
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_validate_eprint -->==validate_eprint==
 
 
  validate_eprint( $eprint, $session, [$for_archive] )
 
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_set_eprint_defaults -->==set_eprint_defaults==
 
 
  set_eprint_defaults( $data, $session )
 
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_set_eprint_automatic_fields -->==set_eprint_automatic_fields==
 
 
  set_eprint_automatic_fields( $eprint )
 
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_eprint_render -->==eprint_render==
 
 
  eprint_render( $eprint, $session )
 
 
 
See {{API:PodLink|file=ArchiveRenderConfig|package_name=ArchiveRenderConfig|section=eprint_render|text=ArchiveRenderConfig/eprint_render}}.
 
 
<!-- 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_order_issues_newest_open_timestamp -->==order_issues_newest_open_timestamp==
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_box_list -->==render_box_list==
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_fileinfo -->==render_fileinfo==
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_issues -->==render_issues==
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_preview -->==render_preview==
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_succeed_thread_modified -->==succeed_thread_modified==
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=_postamble_ --><!-- End of Pod2Wiki -->
 

Revision as of 15:40, 12 August 2009