NAME

Krang::History - records historical events for krang objects

SYNOPSIS

    use Krang::ClassLoader History => qw( add_history );

    # record that a story was created (user_id pulled from session, 
    # object id and type from object passed in)
    add_history(    object => $story, 
                    action => 'new',
               );

    # record that story was saved (user_id pulled from session, 
    # object id, type and version from object passed in)
    add_history(    object => $story, 
                    action => 'save',
               );

    # record that story was checked in to desk 2 (user_id pulled 
    # from session, object id and type from object passed in)
    add_history(    object => $story, 
                    action => 'checkin'
                    desk_id => '2' 
                );

    # record that template was deployed (user_id pulled from session, 
    # object id and type from object passed in)
    add_history(    object => $template,
                    action => 'deploy',
               );
    
    # find and return all events for story 
    # (object id and type from object passed in)
    my @events = pkg('History')->find(  object => $story
                                     );

    # delete all history for media object 
    pkg('History')->delete( object => $media,
                          );

DESCRIPTION

This class handles the storage and retrieval of historical events in a Krang object's life. Three interface methods exist- add_history, find, and delete.

INTERFACE

METHODS

• $history->fields()
  
Returns a list of the DB table fields. Override this method to extend the list
• add_history()
  
This method adds an entry into the database of an action taken on an object.

The valid trackable objects are: Krang::Story, Krang::Media, and Krang::Template. These are passed in as 'object' - 'object_type', and 'object_id' are derived from the object. The valid actions (specified by 'action') performed on an object are listed in the actions() method at the bottom of this module.

In addition to tracking actions on objects, the user who performed the action is tracked by 'user_id', which is found in the session object. If the 'action' is 'save' or 'revert', version is also derived from the object. 'desk_id' can be used to track which desk an action was performed on. A timestamp is added to each history event, and will appear in the field 'timestamp' on objects returned from find.

• find()
  
Find and return Krang::History objects with parameters specified. Supported paramter keys:
object - Krang::Story, Krang::Media, or Krang::Template object (required)
user_id
order_by - field to order search by, defaults to timestamp
order_desc - results will be in ascending order unless this is set to 1 (making them descending).
limit - limits result to number passed in here, else no limit.
offset - offset results by this number, else no offset.
count - return only a count if this is set to true.

• delete()
  
Deletes all entries from history with object_id and object_type from passed in $object.
• $history->object_types()
  
Returns a list of asset types. Override this method to extend the list.
• $history->actions()
  
Returns a list of actions to be logged. Override this method to extend the list.