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

From EPrints Documentation
Jump to: navigation, search
Line 18: Line 18:
 
==DESCRIPTION==
 
==DESCRIPTION==
 
This class describes a single item in the history dataset. A history object describes a single action taken on a single item in another dataset.
 
This class describes a single item in the history dataset. A history object describes a single action taken on a single item in another dataset.
 +
 +
This class inherits from [[API:EPrints/DataObj/SubObject|EPrints::DataObj::SubObject]], which in  turn inherits from [[API:EPrints/DataObj|EPrints::DataObj]].
  
 
Changes to document are considered part of changes to the eprint it belongs to.
 
Changes to document are considered part of changes to the eprint it belongs to.
 +
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 +
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=head_instance_variables -->
 +
==INSTANCE VARIABLES==
 +
See &lt;EPrints::DataObj#INSTANCE_VARIABLES&gt;.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 156: Line 169:
 
<!-- Pod2Wiki=head_methods -->
 
<!-- Pod2Wiki=head_methods -->
 
==METHODS==
 
==METHODS==
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 +
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=head_constructor_methods -->
 +
===Constructor Methods===
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 +
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_create -->
 +
====create====
 +
 +
EPrints::DataObj::History::create( $session, $data );
 +
Create a new history data object from this <tt>$data</tt>. Unlike other create methods this one does not return the new object as it is never needed, and would increase the load when modifying other data objects.
 +
 +
Also, this does not queue the fields for indexing.
 +
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 +
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=head_class_methods -->
 +
===Class Methods===
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
<span style='display:none'>User Comments</span>
Line 164: Line 210:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_get_system_field_info -->
 
<!-- Pod2Wiki=item_get_system_field_info -->
===get_system_field_info===
+
====get_system_field_info====
  
 
  $field_info = EPrints::DataObj::History-&gt;get_system_field_info
 
  $field_info = EPrints::DataObj::History-&gt;get_system_field_info
Line 177: Line 223:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_get_dataset_id -->
 
<!-- Pod2Wiki=item_get_dataset_id -->
===get_dataset_id===
+
====get_dataset_id====
  
 
  $dataset = EPrints::DataObj::History-&gt;get_dataset_id
 
  $dataset = EPrints::DataObj::History-&gt;get_dataset_id
Line 189: Line 235:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_commit -->
+
<!-- Pod2Wiki=head_object_methods -->
===commit===
+
===Object Methods===
 
 
$history-&gt;commit
 
History cannot be altered. So if somehow this is called it just logs a warning message.
 
 
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
<span style='display:none'>User Comments</span>
Line 202: Line 244:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_remove -->
+
<!-- Pod2Wiki=item_commit -->
===remove===
+
====commit====
  
  $history-&gt;remove
+
  $history-&gt;commit
History cannot be removed. So if somehow this is called it just logs a warning message.
+
History cannot be altered. So if somehow this is called it just logs a warning message.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 215: Line 257:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_create -->
+
<!-- Pod2Wiki=item_remove -->
===create===
+
====remove====
  
  EPrints::DataObj::History::create( $session, $data );
+
  $history-&gt;remove
Create a new history data object from this <tt>$data</tt>. Unlike other  create methods this one does not return the new object as it is never  needed, and would increase the load when modifying other data objects.
+
History cannot be removed. So if somehow this is called it just logs a warning message.
 
 
Also, this does not queue the fields for indexing.
 
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 231: Line 271:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_get_defaults -->
 
<!-- Pod2Wiki=item_get_defaults -->
===get_defaults===
+
====get_defaults====
  
  $defaults = EPrints::DataObj::History-&gt;get_defaults( $session, $data )
+
  $defaults = EPrints::DataObj::History-&gt;get_defaults( $session, $data, [ $dataset ] )
Return default values for this history data object based on the  starting <tt>$data</tt>.
+
Returns default values for this history data object based on the  starting <tt>$data</tt> and for ths <tt>$dataset</tt> if specified.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 244: Line 284:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_render -->
 
<!-- Pod2Wiki=item_render -->
===render===
+
====render====
  
 
  $xhtml = $history-&gt;render
 
  $xhtml = $history-&gt;render
Line 257: Line 297:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_get_dataobj -->
 
<!-- Pod2Wiki=item_get_dataobj -->
===get_dataobj===
+
====get_dataobj====
  
 
  $object = $history-&gt;get_dataobj
 
  $object = $history-&gt;get_dataobj
Line 270: Line 310:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_get_user -->
 
<!-- Pod2Wiki=item_get_user -->
===get_user===
+
====get_user====
  
 
  $user = $history-&gt;get_user
 
  $user = $history-&gt;get_user
Line 283: Line 323:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_get_previous -->
 
<!-- Pod2Wiki=item_get_previous -->
===get_previous===
+
====get_previous====
  
 
  $history = $history-&gt;get_previous
 
  $history = $history-&gt;get_previous
Line 290: Line 330:
 
Returns <tt>undef</tt> if no such history event exists.
 
Returns <tt>undef</tt> if no such history event exists.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
 
 
<!-- Pod2Wiki= -->
 
</div>
 
<!-- Pod2Wiki=head_rendering_methods -->
 
===Rendering Methods===
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
<span style='display:none'>User Comments</span>
Line 351: Line 382:
 
Returns a XHTML DOM rendering of a <tt>modify</tt> history event.
 
Returns a XHTML DOM rendering of a <tt>modify</tt> history event.
  
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 +
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_set_dataobj_xml -->
 +
====set_dataobj_xml====
 +
 +
$history-&gt;set_dataobj_xml( $dataobj )
 +
Stores the XML serialisation for <tt>$dataobj</tt> to a file.
 +
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 +
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=head_utility_methods -->
 +
===Utility Methods===
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
<span style='display:none'>User Comments</span>
Line 442: Line 495:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_set_dataobj_xml -->
+
<!-- Pod2Wiki=head_see_alsol_eprints_dataobj_subobject_l_eprints_dataobj_and_l_eprints_dataset -->
====set_dataobj_xml====
+
==SEE ALSO[[API:EPrints/DataObj:SubObject|EPrints::DataObj:SubObject]], [[API:EPrints/DataObj|EPrints::DataObj]] and [[API:EPrints/DataSet|EPrints::DataSet]].==
 
 
$history-&gt;set_dataobj_xml( $dataobj )
 
Stores the XML serialisation for <tt>$dataobj</tt> to a file.
 
 
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
<span style='display:none'>User Comments</span>

Revision as of 00:31, 4 January 2022

EPrints 3 Reference: Directory Structure - Metadata Fields - Repository Configuration - XML Config Files - XML Export Format - EPrints data structure - Core API - Data Objects


API: Core API

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


NAME

EPrints::DataObj::History - An element in the history of the arcvhive.

User Comments


DESCRIPTION

This class describes a single item in the history dataset. A history object describes a single action taken on a single item in another dataset.

This class inherits from EPrints::DataObj::SubObject, which in turn inherits from EPrints::DataObj.

Changes to document are considered part of changes to the eprint it belongs to.

User Comments


INSTANCE VARIABLES

See <EPrints::DataObj#INSTANCE_VARIABLES>.

User Comments


CORE METADATA FIELDS

User Comments


historyid (counter)

The unique numerical ID of this history event.

User Comments


actor (text)

A text representation of the actor reponsible for the action for this history event. This may be the name of a script or application or a user's name.

User Comments


datasetid (id)

The name of the dataset to which the modified item belongs. eprint is used for eprints, rather than the inbox, buffer etc.

User Comments


objectid (int)

The numerical ID of the object in the dataset.

User Comments


revision (int)

The revision of the object. This is the revision number after the action occured. Not all actions increase the revision number.

User Comments


timestamp (timestamp)

The moment at which this thing happened.

User Comments


action (set)

The type of event. Provisionally, this is a subset of the new list of privileges.

User Comments


details (longtext)

If this is a rejection then the details contain the message sent to the user.

User Comments


REFERENCES AND RELATED OBJECTS

User Comments


userid (itemref)

The ID of the user who caused this event. A value of zero or undefined indicates that there was no user responsible (ie. a script did it).

User Comments


METHODS

User Comments


Constructor Methods

User Comments


create

EPrints::DataObj::History::create( $session, $data );

Create a new history data object from this $data. Unlike other create methods this one does not return the new object as it is never needed, and would increase the load when modifying other data objects.

Also, this does not queue the fields for indexing.

User Comments


Class Methods

User Comments


get_system_field_info

$field_info = EPrints::DataObj::History->get_system_field_info

Returns an array describing the system metadata of the history dataset.

User Comments


get_dataset_id

$dataset = EPrints::DataObj::History->get_dataset_id

Returns the ID of the EPrints::DataSet object to which this record belongs.

User Comments


Object Methods

User Comments


commit

$history->commit 

History cannot be altered. So if somehow this is called it just logs a warning message.

User Comments


remove

$history->remove

History cannot be removed. So if somehow this is called it just logs a warning message.

User Comments


get_defaults

$defaults = EPrints::DataObj::History->get_defaults( $session, $data, [ $dataset ] )

Returns default values for this history data object based on the starting $data and for ths $dataset if specified.

User Comments


render

$xhtml = $history->render

Return a rendering of this history event as XHTML DOM.

User Comments


get_dataobj

$object = $history->get_dataobj

Returns the data object to which this history event relates.

User Comments


get_user

$user = $history->get_user

Returns the user data object of the user who caused this history event.

User Comments


get_previous

$history = $history->get_previous

Returns the previous history event for this history event's data object.

Returns undef if no such history event exists.

User Comments


render_removal_request

$xhtml = $history->render_removal_request

Returns a XHTML DOM rendering of a removal request history event.

User Comments


render_with_details

$xhtml = $history->render_with_details

Returns a XHTML DOM rendering of a mail_owner (i.e. email was sent to the owner of the data object) history event.

User Comments


render_create

$xhtml = $history->render_create( $action )

Returns a XHTML DOM rendering of a create history event.

User Comments


render_modify

$xhtml = $history->render_modify( $action )

Returns a XHTML DOM rendering of a modify history event.

User Comments


set_dataobj_xml

$history->set_dataobj_xml( $dataobj )

Stores the XML serialisation for $dataobj to a file.

User Comments


Utility Methods

User Comments


empty_tree

$boolean = EPrints::DataObj::History::empty_tree( $domtree )

Returns true if there is no text in the XHTML $domtree other than whitespace. Otherwise, returns false.

This method is liable to being moveded to EPrints::XML> or EPrints::Utils.

User Comments


render_xml_diffs

( $f1, $f2 ) = EPrints::DataObj::History::render_xml_diffs( $tree1, $tree2, $indent, $width )

Returns two XHTML DOM trees. The first for the older version, highlighting lines that are changed or removed and the second for the newer version, highlighting libes that are changed or added.

User Comments


render_domtree

($xhtml, [$xhtml_padding]) = EPrints::DataObj::History::render_domtree( $session, $tree, $indent, $make_padded, $width )

Returns a rendering of the given tree as XHTML (showing the actual XML structure).

If $make_padded is true then also generate another element, which is empty but the same height to be used in the other column to keep things level.

User Comments


diff

$boolean = EPrints::DataObj::History::diff( $tree1, $tree2 )

Returns true if the XML trees $tree1 and $tree2 are not the same, otherwise returns false.

User Comments


mktext

@lines = EPrints::DataObj::History::mktext( $session, $text, $offset, $endw, $width )

Returns the $text string broken into an array of lines which are $width long or less.

Inserts a 90 degree arrow at the end of each broken line to indicate that it has been broken.

User Comments


mkpad

$xhtml = EPrints::DataObj::History::mkpad( $session, $text, $offset, $endw, $width )

Return XHTML DOM of vertical padding equivalent to the lines that would be needed to render $text.

User Comments


SEE ALSOEPrints::DataObj:SubObject, EPrints::DataObj and EPrints::DataSet.

User Comments


COPYRIGHT

© Copyright 2023 University of Southampton.

EPrints 3.4 is supplied by EPrints Services.

http://www.eprints.org/eprints-3.4/

LICENSE

This file is part of EPrints 3.4 http://www.eprints.org/.

EPrints 3.4 and this file are released under the terms of the GNU Lesser General Public License version 3 as published by the Free Software Foundation unless otherwise stated.

EPrints 3.4 is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with EPrints 3.4. If not, see http://www.gnu.org/licenses/.

User Comments