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

From EPrints Documentation
Jump to: navigation, search
Line 1: Line 1:
 
<!-- Pod2Wiki=_preamble_  
 
<!-- 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.
 
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.
  -->{{API:Source|file=EPrints/DataObj/EPrint.pm|package_name=EPrints::DataObj::EPrint}}[[Category:API|EPrint]]<!-- End of Pod2Wiki -->
+
  -->{{Pod2Wiki}}{{API:Source|file=EPrints/DataObj/EPrint.pm|package_name=EPrints::DataObj::EPrint}}[[Category:API|EPrint]]<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=head_name -->'''EPrints::DataObj::EPrint''' - Class representing an actual EPrint
+
<!-- Pod2Wiki=head_name -->=NAME=
__TOC__
+
'''EPrints::DataObj::EPrint''' - Class representing an actual EPrint
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=head_description -->=DESCRIPTION=
 
<!-- 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.
+
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 followingmetadata fields (plus those defined in ArchiveMetadataFieldsConfig):
+
 
 +
EPrints::DataObj::EPrint is a subclass of EPrints::DataObj with the following metadata fields (plus those defined in ArchiveMetadataFieldsConfig):
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=head_system_metadata -->=SYSTEM METADATA=
 
<!-- Pod2Wiki=head_system_metadata -->=SYSTEM METADATA=
Line 16: Line 19:
  
 
The unique numerical ID of this eprint.  
 
The unique numerical ID of this eprint.  
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_rev_number -->==rev_number==
 
<!-- Pod2Wiki=item_rev_number -->==rev_number==
Line 22: Line 26:
  
 
The number of the current revision of this record.
 
The number of the current revision of this record.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_userid -->==userid==
 
<!-- Pod2Wiki=item_userid -->==userid==
Line 27: Line 32:
 
   userid (itemref)
 
   userid (itemref)
  
The id of the user who deposited this eprint (if any). Scripted importingcould cause this not to be set.
+
The id of the user who deposited this eprint (if any). Scripted importing could cause this not to be set.
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_dir -->==dir==
 
<!-- Pod2Wiki=item_dir -->==dir==
Line 33: Line 39:
 
   dir (text)
 
   dir (text)
  
The directory, relative to the documents directory for this repository, whichthis eprints data is stored in. Eg. disk0/00/00/03/34 for record 334.
+
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 -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_datestamp -->==datestamp==
 
<!-- Pod2Wiki=item_datestamp -->==datestamp==
Line 40: Line 47:
  
 
The date this record first appeared live in the repository.
 
The date this record first appeared live in the repository.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_lastmod -->==lastmod==
 
<!-- Pod2Wiki=item_lastmod -->==lastmod==
Line 46: Line 54:
  
 
The date this record was last modified.
 
The date this record was last modified.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_status_changes -->==status_changes==
 
<!-- Pod2Wiki=item_status_changes -->==status_changes==
Line 52: Line 61:
  
 
The date/time this record was moved between inbox, buffer, archive, etc.
 
The date/time this record was moved between inbox, buffer, archive, etc.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_type -->==type==
 
<!-- Pod2Wiki=item_type -->==type==
Line 58: Line 68:
  
 
The type of this record, one of the types of the "eprint" dataset.
 
The type of this record, one of the types of the "eprint" dataset.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_succeeds -->==succeeds==
 
<!-- Pod2Wiki=item_succeeds -->==succeeds==
Line 63: Line 74:
 
   succeeds (itemref)
 
   succeeds (itemref)
  
The ID of the eprint (if any) which this succeeds.  This field should havebeen an int and may be changed in a later upgrade.
+
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 -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_commentary -->==commentary==
 
<!-- Pod2Wiki=item_commentary -->==commentary==
Line 69: Line 81:
 
   commentary (itemref)
 
   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.
+
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 -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_replacedby -->==replacedby==
 
<!-- Pod2Wiki=item_replacedby -->==replacedby==
Line 75: Line 88:
 
   replacedby (itemref)
 
   replacedby (itemref)
  
The ID of the eprint (if any) which has replaced this eprint. This is only seton records in the "deletion" dataset.  This field should havebeen an int and may be changed in a later upgrade.
+
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 -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=head_methods -->=METHODS=
 
<!-- Pod2Wiki=head_methods -->=METHODS=
Line 84: Line 98:
  
 
Return an array describing the system metadata of the EPrint dataset.
 
Return an array describing the system metadata of the EPrint dataset.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_get_dataset_id -->==get_dataset_id==
+
<!-- Pod2Wiki=item_new -->==new==
  
   $dataset = EPrints::DataObj::EPrint-&gt;get_dataset_id
+
   $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.
  
Returns the id of the [[API:EPrints/DataSet|EPrints::DataSet]] object to which this record belongs.
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_dataset -->==get_dataset==
 
<!-- Pod2Wiki=item_get_dataset -->==get_dataset==
Line 95: Line 125:
 
   $dataset = $eprint-&gt;get_dataset
 
   $dataset = $eprint-&gt;get_dataset
  
Return the dataset to which this object belongs. This will returnone of the virtual datasets: inbox, buffer, archive or deletion.
+
Return the dataset to which this object belongs. This will return one of the virtual datasets: inbox, buffer, archive or deletion.
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_defaults -->==get_defaults==
 
<!-- Pod2Wiki=item_get_defaults -->==get_defaults==
Line 102: Line 133:
  
 
Return default values for this object based on the starting data.
 
Return default values for this object based on the starting data.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_clone -->==clone==
 
<!-- Pod2Wiki=item_clone -->==clone==
Line 107: Line 139:
 
   $eprint = $eprint-&gt;clone( $dest_dataset, $copy_documents, $link )
 
   $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.
+
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 theold one.
+
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 -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_log_mail_owner -->==log_mail_owner==
 
<!-- Pod2Wiki=item_log_mail_owner -->==log_mail_owner==
Line 116: Line 151:
  
 
Log that the given mail message was send to the owner of this EPrint.
 
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.
 
$mail is the same XHTML DOM that was sent as the email.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_editorial_contact -->==get_editorial_contact==
 
<!-- Pod2Wiki=item_get_editorial_contact -->==get_editorial_contact==
Line 123: Line 160:
  
 
Return the user identified as the editorial contact for this item.
 
Return the user identified as the editorial contact for this item.
 +
 
By default returns undef.
 
By default returns undef.
 +
 
nb. This has nothing to do with the editor defined in the metadata
 
nb. This has nothing to do with the editor defined in the metadata
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_remove -->==remove==
 
<!-- Pod2Wiki=item_remove -->==remove==
Line 130: Line 170:
 
   $success = $eprint-&gt;remove
 
   $success = $eprint-&gt;remove
  
Erase this eprint and any associated records from the database andfilesystem.
+
Erase this eprint and any associated records from the database and filesystem.
 +
 
 
This should only be called on eprints in "inbox" or "buffer".
 
This should only be called on eprints in "inbox" or "buffer".
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_commit -->==commit==
 
<!-- Pod2Wiki=item_commit -->==commit==
Line 138: Line 180:
  
 
Commit any changes that might have been made to the database.
 
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 L!/set_eprint_automatic_fields! just before the <tt>$eprint</tt> is committed.
+
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 -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_write_revision -->==write_revision==
 
<!-- Pod2Wiki=item_write_revision -->==write_revision==
Line 145: Line 190:
 
   $eprint-&gt;write_revision
 
   $eprint-&gt;write_revision
  
Write out a snapshot of the XML describing the current state of theeprint.
+
Write out a snapshot of the XML describing the current state of the eprint.
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_validate -->==validate==
 
<!-- Pod2Wiki=item_validate -->==validate==
Line 151: Line 197:
 
   $problems = $eprint-&gt;validate( [$for_archive], $workflow_id )
 
   $problems = $eprint-&gt;validate( [$for_archive], $workflow_id )
  
Return a reference to an array of XHTML DOM objects describingvalidation problems with the entire eprint based on $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".
 
If $workflow_id is undefined defaults to "default".
 +
 
A reference to an empty array indicates no problems.
 
A reference to an empty array indicates no problems.
Calls L!/validate_eprint! for the <tt>$eprint</tt>.
+
 
 +
Calls {{API:PodLink|file=|package_name=|section=validate_eprint|text=/validate_eprint}} for the <tt>$eprint</tt>.
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_warnings -->==get_warnings==
 
<!-- Pod2Wiki=item_get_warnings -->==get_warnings==
Line 160: Line 210:
 
   $warnings = $eprint-&gt;get_warnings
 
   $warnings = $eprint-&gt;get_warnings
  
Return a reference to an array of XHTML DOM objects describingwarnings about this eprint - that is things that are not quite validation errors, but it'd be nice if they were fixed.
+
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 L!/eprint_warnings! for the <tt>$eprint</tt>.
+
 
 +
Calls {{API:PodLink|file=|package_name=|section=eprint_warnings|text=/eprint_warnings}} for the <tt>$eprint</tt>.
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_skip_validation -->==skip_validation==
 
<!-- Pod2Wiki=item_skip_validation -->==skip_validation==
Line 167: Line 219:
 
   $boolean = $eprint-&gt;skip_validation
 
   $boolean = $eprint-&gt;skip_validation
  
Returns true if this eprint should pass validation without beingproperly validated. This is to allow the use of dodgey data importedfrom legacy systems.
+
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 -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_prune_documents -->==prune_documents==
 
<!-- Pod2Wiki=item_prune_documents -->==prune_documents==
Line 173: Line 226:
 
   $eprint-&gt;prune_documents
 
   $eprint-&gt;prune_documents
  
Remove any documents associated with this eprint which don't actuallyhave any files.
+
Remove any documents associated with this eprint which don't actually have any files.
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_all_documents -->==get_all_documents==
 
<!-- Pod2Wiki=item_get_all_documents -->==get_all_documents==
Line 179: Line 233:
 
   @documents = $eprint-&gt;get_all_documents
 
   @documents = $eprint-&gt;get_all_documents
  
Return an array of all EPrint::Document objects associated with thiseprint.
+
Return an array of all EPrint::Document objects associated with this eprint.
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_required_formats -->==required_formats==
 
<!-- Pod2Wiki=item_required_formats -->==required_formats==
Line 185: Line 240:
 
   @formats =  $eprint-&gt;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.
+
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.
 
An empty list means no format is required.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_move_to_deletion -->==move_to_deletion==
 
<!-- Pod2Wiki=item_move_to_deletion -->==move_to_deletion==
Line 192: Line 249:
 
   $success = $eprint-&gt;move_to_deletion
 
   $success = $eprint-&gt;move_to_deletion
  
Transfer the EPrint into the "deletion" dataset. Should only becalled in eprints in the "archive" dataset.
+
Transfer the EPrint into the "deletion" dataset. Should only be called in eprints in the "archive" dataset.
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_move_to_inbox -->==move_to_inbox==
 
<!-- Pod2Wiki=item_move_to_inbox -->==move_to_inbox==
Line 198: Line 256:
 
   $success = $eprint-&gt;move_to_inbox
 
   $success = $eprint-&gt;move_to_inbox
  
Transfer the EPrint into the "inbox" dataset. Should only becalled in eprints in the "buffer" dataset.
+
Transfer the EPrint into the "inbox" dataset. Should only be called in eprints in the "buffer" dataset.
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_move_to_buffer -->==move_to_buffer==
 
<!-- Pod2Wiki=item_move_to_buffer -->==move_to_buffer==
Line 204: Line 263:
 
   $success = $eprint-&gt;move_to_buffer
 
   $success = $eprint-&gt;move_to_buffer
  
Transfer the EPrint into the "buffer" dataset. Should only becalled in eprints in the "inbox" or "archive" dataset.
+
Transfer the EPrint into the "buffer" dataset. Should only be called in eprints in the "inbox" or "archive" dataset.
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_move_to_archive -->==move_to_archive==
 
<!-- Pod2Wiki=item_move_to_archive -->==move_to_archive==
Line 210: Line 270:
 
   $success = $eprint-&gt;move_to_archive
 
   $success = $eprint-&gt;move_to_archive
  
Move this eprint into the main "archive" dataset. Normally only calledon eprints in "deletion" or "buffer" datasets.
+
Move this eprint into the main "archive" dataset. Normally only called on eprints in "deletion" or "buffer" datasets.
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_local_path -->==local_path==
 
<!-- Pod2Wiki=item_local_path -->==local_path==
Line 216: Line 277:
 
   $path = $eprint-&gt;local_path
 
   $path = $eprint-&gt;local_path
  
Return the full path of the EPrint directory on the local filesystem.No trailing slash.
+
Return the full path of the EPrint directory on the local filesystem. No trailing slash.
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_url_stem -->==url_stem==
 
<!-- Pod2Wiki=item_url_stem -->==url_stem==
Line 222: Line 284:
 
   $url = $eprint-&gt;url_stem
 
   $url = $eprint-&gt;url_stem
  
Return the URL to this EPrint's directory. Note, this INCLUDES thetrailing slash, unlike the local_path method.
+
Return the URL to this EPrint's directory. Note, this INCLUDES the trailing slash, unlike the local_path method.
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_generate_static -->==generate_static==
 
<!-- Pod2Wiki=item_generate_static -->==generate_static==
Line 228: Line 291:
 
   $eprint-&gt;generate_static
 
   $eprint-&gt;generate_static
  
Generate the static version of the abstract web page. In a multi-languagerepository this will generate one version per language.
+
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.
 
If called on inbox or buffer, remove the abstract page.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_generate_static_all_related -->==generate_static_all_related==
 
<!-- Pod2Wiki=item_generate_static_all_related -->==generate_static_all_related==
Line 235: Line 300:
 
   $eprint-&gt;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.
+
Generate the static pages for this eprint plus any it's related to, by succession or commentary.
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_remove_static -->==remove_static==
 
<!-- Pod2Wiki=item_remove_static -->==remove_static==
Line 242: Line 308:
  
 
Remove the static web page or pages.
 
Remove the static web page or pages.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render -->==render==
 
<!-- Pod2Wiki=item_render -->==render==
Line 247: Line 314:
 
   ( $description, $title, $links ) = $eprint-&gt;render
 
   ( $description, $title, $links ) = $eprint-&gt;render
  
Render the eprint. The 3 returned values are references to XHTML DOMobjects. $description is the public viewable description of this eprintthat appears as the body of the abstract page. $title is the title ofthe abstract page for this eprint. $links is any elements which shouldgo in the &lt;head&gt; of this page.
+
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 L!/eprint_render! to actually render the <tt>$eprint</tt>, if it isn't deleted.
+
 
 +
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 -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_history -->==render_history==
 
<!-- Pod2Wiki=item_render_history -->==render_history==
Line 255: Line 324:
  
 
Render the history of this eprint as XHTML DOM.
 
Render the history of this eprint as XHTML DOM.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_control_url -->==get_control_url==
 
<!-- Pod2Wiki=item_get_control_url -->==get_control_url==
Line 261: Line 331:
  
 
Return the URL of the control page for this eprint.
 
Return the URL of the control page for this eprint.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_url -->==get_url==
 
<!-- Pod2Wiki=item_get_url -->==get_url==
Line 267: Line 338:
  
 
Return the public URL of this eprints abstract page.  
 
Return the public URL of this eprints abstract page.  
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_user -->==get_user==
 
<!-- Pod2Wiki=item_get_user -->==get_user==
Line 273: Line 345:
  
 
Return the EPrints::User to whom this eprint belongs (if any).
 
Return the EPrints::User to whom this eprint belongs (if any).
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_eprintid_to_path -->==eprintid_to_path==
 
<!-- Pod2Wiki=item_eprintid_to_path -->==eprintid_to_path==
Line 278: Line 351:
 
   $path = EPrints::DataObj::EPrint::eprintid_to_path( $eprintid )
 
   $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.
+
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 -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_all_related -->==get_all_related==
 
<!-- Pod2Wiki=item_get_all_related -->==get_all_related==
Line 284: Line 358:
 
   @eprints = $eprint-&gt;get_all_related
 
   @eprints = $eprint-&gt;get_all_related
  
Return the eprints that are related in some way to this in a successionor commentary thread. The returned list does NOT include this EPrint.
+
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 -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_in_thread -->==in_thread==
 
<!-- Pod2Wiki=item_in_thread -->==in_thread==
Line 290: Line 365:
 
   $boolean = $eprint-&gt;in_thread( $field )
 
   $boolean = $eprint-&gt;in_thread( $field )
  
Return true if this eprint is part of a thread of $field. $fieldshould be an EPrint::MetaField representing either "commentary" or"succeeds".
+
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 -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_first_in_thread -->==first_in_thread==
 
<!-- Pod2Wiki=item_first_in_thread -->==first_in_thread==
Line 296: Line 372:
 
   $eprint = $eprint-&gt;first_in_thread( $field )
 
   $eprint = $eprint-&gt;first_in_thread( $field )
  
Return the first (earliest) version or first paper in the threadof commentaries of this paper in the repository.
+
Return the first (earliest) version or first paper in the thread of commentaries of this paper in the repository.
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_later_in_thread -->==later_in_thread==
 
<!-- Pod2Wiki=item_later_in_thread -->==later_in_thread==
Line 303: Line 380:
  
 
Return a list of the immediately later items in the thread.  
 
Return a list of the immediately later items in the thread.  
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_all_in_thread -->==all_in_thread==
 
<!-- Pod2Wiki=item_all_in_thread -->==all_in_thread==
Line 309: Line 387:
  
 
Return all of the EPrints in the given thread.
 
Return all of the EPrints in the given thread.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_last_in_thread -->==last_in_thread==
 
<!-- Pod2Wiki=item_last_in_thread -->==last_in_thread==
Line 315: Line 394:
  
 
Return the last item in the specified thread.
 
Return the last item in the specified thread.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_remove_from_threads -->==remove_from_threads==
 
<!-- Pod2Wiki=item_remove_from_threads -->==remove_from_threads==
Line 320: Line 400:
 
   $eprint-&gt;remove_from_threads
 
   $eprint-&gt;remove_from_threads
  
Extract the eprint from any threads it's in. i.e., if any otherpaper is a later version of or commentary on this paper, the linkfrom that paper to this will be removed.
+
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.
 
Abstract pages are updated if needed.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_version_thread -->==render_version_thread==
 
<!-- Pod2Wiki=item_render_version_thread -->==render_version_thread==
Line 328: Line 410:
  
 
Render XHTML DOM describing the entire thread as nested unordered lists.
 
Render XHTML DOM describing the entire thread as nested unordered lists.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_loop_error -->==loop_error==
 
<!-- Pod2Wiki=item_loop_error -->==loop_error==
Line 333: Line 416:
 
   $eprint-&gt;loop_error( $field, @looped_ids )
 
   $eprint-&gt;loop_error( $field, @looped_ids )
  
This eprint is part of a threading loop which is not allowed. Log awarning.
+
This eprint is part of a threading loop which is not allowed. Log a warning.
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_type -->==get_type==
 
<!-- Pod2Wiki=item_get_type -->==get_type==
Line 340: Line 424:
  
 
Return the type of this eprint.
 
Return the type of this eprint.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_export_links -->==render_export_links==
 
<!-- Pod2Wiki=item_render_export_links -->==render_export_links==
Line 345: Line 430:
 
   $xhtml_ul_list = $eprint-&gt;render_export_links( [$staff] )
 
   $xhtml_ul_list = $eprint-&gt;render_export_links( [$staff] )
  
Return a &lt;ul&gt; list containing links to all the formats this eprintis available in.  
+
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 linkto the staff export URL.
+
 
 +
If $staff is true then show all formats available to staff, and link to the staff export URL.
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_user_roles -->==user_roles==
 
<!-- Pod2Wiki=item_user_roles -->==user_roles==
Line 353: Line 440:
  
 
Return the @roles $user has on $eprint.
 
Return the @roles $user has on $eprint.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_datestamp -->==datestamp==
 
<!-- Pod2Wiki=item_datestamp -->==datestamp==
Line 359: Line 447:
  
 
DEPRECATED.
 
DEPRECATED.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_in_editorial_scope_of -->==in_editorial_scope_of==
 
<!-- Pod2Wiki=item_in_editorial_scope_of -->==in_editorial_scope_of==
Line 364: Line 453:
 
   $boolean = $eprint-&gt;in_editorial_scope_of( $possible_editor )
 
   $boolean = $eprint-&gt;in_editorial_scope_of( $possible_editor )
  
Returns true if $possible_editor can edit this eprint. This isaccording to the user editperms.  
+
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 theydo then they may edit the given item.
+
 
 +
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 -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_has_owner -->==has_owner==
 
<!-- Pod2Wiki=item_has_owner -->==has_owner==
Line 371: Line 462:
 
   $boolean = $eprint-&gt;has_owner( $possible_owner )
 
   $boolean = $eprint-&gt;has_owner( $possible_owner )
  
Returns true if $possible_owner can edit this eprint. This isaccording to the user editperms.  
+
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 theydo then they may edit the given item.
+
Uses the callback "does_user_own_eprint" if available.
+
<!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki=item_obtain_lock -->==obtain_lock==
+
  
  $boolean = $eprint-&gt;obtain_lock( $user )
+
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 -->
+
Uses the callback "does_user_own_eprint" if available.
<!-- Pod2Wiki=item_could_obtain_lock -->==could_obtain_lock==
+
 
+
  $boolean = $eprint-&gt;could_obtain_lock( $user )
+
 
+
<!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki=item_is_locked -->==is_locked==
+
 
+
  $boolean = $eprint-&gt;is_locked()
+
 
+
<!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki=item_render_edit_lock -->==render_edit_lock==
+
 
+
  $xhtml = render_edit_lock( $session, $value )
+
  
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=head_callbacks -->=CALLBACKS=
 
<!-- Pod2Wiki=head_callbacks -->=CALLBACKS=
 
Callbacks may optionally be defined in the ArchiveConfig.
 
Callbacks may optionally be defined in the ArchiveConfig.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_validate_field -->==validate_field==
 
<!-- Pod2Wiki=item_validate_field -->==validate_field==
  
 
   validate_field( $field, $value, $session, [$for_archive] )
 
   validate_field( $field, $value, $session, [$for_archive] )
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_validate_eprint -->==validate_eprint==
 
<!-- Pod2Wiki=item_validate_eprint -->==validate_eprint==
  
 
   validate_eprint( $eprint, $session, [$for_archive] )
 
   validate_eprint( $eprint, $session, [$for_archive] )
   <!-- End of Pod2Wiki -->
+
    
 +
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_set_eprint_defaults -->==set_eprint_defaults==
 
<!-- Pod2Wiki=item_set_eprint_defaults -->==set_eprint_defaults==
  
 
   set_eprint_defaults( $data, $session )
 
   set_eprint_defaults( $data, $session )
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_set_eprint_automatic_fields -->==set_eprint_automatic_fields==
 
<!-- Pod2Wiki=item_set_eprint_automatic_fields -->==set_eprint_automatic_fields==
  
 
   set_eprint_automatic_fields( $eprint )
 
   set_eprint_automatic_fields( $eprint )
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_eprint_render -->==eprint_render==
 
<!-- Pod2Wiki=item_eprint_render -->==eprint_render==
  
 
   eprint_render( $eprint, $session )
 
   eprint_render( $eprint, $session )
See L!ArchiveRenderConfig/eprint_render!.
+
 
 +
See {{API:PodLink|file=ArchiveRenderConfig|package_name=ArchiveRenderConfig|section=eprint_render|text=ArchiveRenderConfig/eprint_render}}.
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=head_undocumented_methods -->=UNDOCUMENTED METHODS=
 
<!-- Pod2Wiki=head_undocumented_methods -->=UNDOCUMENTED METHODS=

Revision as of 18:28, 11 August 2009

Latest Source Code (3.3, 3.2) | Revision Log | Before editing this page please read Pod2Wiki

NAME

EPrints::DataObj::EPrint - Class representing an actual EPrint

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):

SYSTEM METADATA

eprintid

 eprintid (int)

The unique numerical ID of this eprint.

rev_number

 rev_number (int)

The number of the current revision of this record.

userid

 userid (itemref)

The id of the user who deposited this eprint (if any). Scripted importing could cause this not to be set.

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.

datestamp

 datestamp (time)

The date this record first appeared live in the repository.

lastmod

 lastmod (time)

The date this record was last modified.

status_changes

 status_changes (time)

The date/time this record was moved between inbox, buffer, archive, etc.

type

 type (namedset)

The type of this record, one of the types of the "eprint" dataset.

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.

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.

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.

METHODS

get_system_field_info

 $metadata = EPrints::DataObj::EPrint->get_system_field_info

Return an array describing the system metadata of the EPrint dataset.

new

 $eprint = EPrints::DataObj::EPrint->new( $session, $eprint_id )

Return the eprint with the given eprint_id, or undef if it does not exist.

new_from_data

 $eprint = EPrints::DataObj::EPrint->new_from_data( $session, $data, $dataset )

Construct a new EPrints::DataObj::EPrint object based on the $data hash reference of metadata.

get_gid

 $dataset = $eprint->get_gid

Returns the OAI identifier for this eprint.

get_dataset

 $dataset = $eprint->get_dataset

Return the dataset to which this object belongs. This will return one of the virtual datasets: inbox, buffer, archive or deletion.

get_defaults

 $defaults = EPrints::DataObj::EPrint->get_defaults( $session, $data )

Return default values for this object based on the starting data.

clone

 $eprint = $eprint->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.

log_mail_owner

 $eprint->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.

get_editorial_contact

 $user = $eprint->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

remove

 $success = $eprint->remove

Erase this eprint and any associated records from the database and filesystem.

This should only be called on eprints in "inbox" or "buffer".

commit

 $success = $eprint->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 /set_eprint_automatic_fields just before the $eprint is committed.

write_revision

 $eprint->write_revision

Write out a snapshot of the XML describing the current state of the eprint.

validate

 $problems = $eprint->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 /validate_eprint for the $eprint.

get_warnings

 $warnings = $eprint->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 /eprint_warnings for the $eprint.

skip_validation

 $boolean = $eprint->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.

prune_documents

 $eprint->prune_documents

Remove any documents associated with this eprint which don't actually have any files.

get_all_documents

 @documents = $eprint->get_all_documents

Return an array of all EPrint::Document objects associated with this eprint.

required_formats

 @formats =  $eprint->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.

move_to_deletion

 $success = $eprint->move_to_deletion

Transfer the EPrint into the "deletion" dataset. Should only be called in eprints in the "archive" dataset.

move_to_inbox

 $success = $eprint->move_to_inbox

Transfer the EPrint into the "inbox" dataset. Should only be called in eprints in the "buffer" dataset.

move_to_buffer

 $success = $eprint->move_to_buffer

Transfer the EPrint into the "buffer" dataset. Should only be called in eprints in the "inbox" or "archive" dataset.

move_to_archive

 $success = $eprint->move_to_archive

Move this eprint into the main "archive" dataset. Normally only called on eprints in "deletion" or "buffer" datasets.

local_path

 $path = $eprint->local_path

Return the full path of the EPrint directory on the local filesystem. No trailing slash.

url_stem

 $url = $eprint->url_stem

Return the URL to this EPrint's directory. Note, this INCLUDES the trailing slash, unlike the local_path method.

generate_static

 $eprint->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.

generate_static_all_related

 $eprint->generate_static_all_related

Generate the static pages for this eprint plus any it's related to, by succession or commentary.

remove_static

 $eprint->remove_static

Remove the static web page or pages.

render

 ( $description, $title, $links ) = $eprint->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 <head> of this page.

Calls /eprint_render to actually render the $eprint, if it isn't deleted.

render_history

 ( $html ) = $eprint->render_history

Render the history of this eprint as XHTML DOM.

get_control_url

 $url = $eprint->get_control_url

Return the URL of the control page for this eprint.

get_url

 $url = $eprint->get_url

Return the public URL of this eprints abstract page.

get_user

 $user = $eprint->get_user

Return the EPrints::User to whom this eprint belongs (if any).

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.

get_all_related

 @eprints = $eprint->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.

in_thread

 $boolean = $eprint->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".

first_in_thread

 $eprint = $eprint->first_in_thread( $field )

Return the first (earliest) version or first paper in the thread of commentaries of this paper in the repository.

later_in_thread

 @eprints = $eprint->later_in_thread( $field )

Return a list of the immediately later items in the thread.

all_in_thread

 @eprints = $eprint->all_in_thread( $field )

Return all of the EPrints in the given thread.

last_in_thread

 $eprint = $eprint->last_in_thread( $field )

Return the last item in the specified thread.

remove_from_threads

 $eprint->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.

render_version_thread

 $xhtml = $eprint->render_version_thread( $field )

Render XHTML DOM describing the entire thread as nested unordered lists.

loop_error

 $eprint->loop_error( $field, @looped_ids )

This eprint is part of a threading loop which is not allowed. Log a warning.

get_type

 $type = $eprint->get_type

Return the type of this eprint.

render_export_links

 $xhtml_ul_list = $eprint->render_export_links( [$staff] )

Return a <ul> 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.

user_roles

 @roles = $eprint->user_roles( $user )

Return the @roles $user has on $eprint.

datestamp

 $eprint->datestamp

DEPRECATED.

in_editorial_scope_of

 $boolean = $eprint->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.

has_owner

 $boolean = $eprint->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.

CALLBACKS

Callbacks may optionally be defined in the ArchiveConfig.

validate_field

 validate_field( $field, $value, $session, [$for_archive] )
 

validate_eprint

 validate_eprint( $eprint, $session, [$for_archive] )
 

set_eprint_defaults

 set_eprint_defaults( $data, $session )
 

set_eprint_automatic_fields

 set_eprint_automatic_fields( $eprint )
 

eprint_render

 eprint_render( $eprint, $session )
 

See ArchiveRenderConfig/eprint_render.

UNDOCUMENTED METHODS

Warning These methods were found in the source code but didn't have any POD associated with them. This may be because we haven't got around to documenting them yet or it could be because they are internal to the API and not intended for use by other parts of EPrints.

create

create_from_data

order_issues_newest_open_timestamp

render_box_list

render_fileinfo

render_issues

render_preview

succeed_thread_modified