NAME

Jifty::Plugin::RecordHistory - track all changes made to a record class

SYNOPSIS

Add the following to your config:

framework:
    Plugins:
        - RecordHistory: {}

Add the following to one or more record classes:

use Jifty::Plugin::RecordHistory::Mixin::Model::RecordHistory;

DESCRIPTION

When you use Jifty::Plugin::RecordHistory::Mixin::Model::RecordHistory in a record class, we add a changes method which returns an Jifty::Plugin::RecordHistory::Model::ChangeCollection. These changes describe the updates made to the record, including its creation. Some changes also have change_fields which describe updates to the individual fields of the record.

You do not need to do anything beyond adding RecordHistory to your plugins and using the mixin to your record class(es) to enjoy transaction history. The mixin even hooks into Jifty itself to observe record creation, updates, and deletions.

Configuration

When you're importing the mixin you have several options to control the behavior of history. Here are the defaults:

use Jifty::Plugin::RecordHistory::Mixin::Model::RecordHistory (
    cascaded_delete => 1,
    delete_change   => 0,
);

If cascaded_delete is true, then Jifty::Plugin::RecordHistory::Model::Change and Jifty::Plugin::RecordHistory::Model::ChangeField records are deleted at the same time the original record they refer to is deleted. If cascaded_delete is false, then the Change and ChangeField records persist even if the original record is deleted.

If delete_change is true, then when your record is deleted we create a Jifty::Plugin::RecordHistory::Model::Change record whose type is delete. If delete_change is false, then we do not record the deletion. If both cascaded_delete and delete_change are true, then you will end up with only one change after the record is deleted -- the delete.

Grouping

By default, the only mechanism that groups together change_fields onto a single change object is Jifty::Action::Record::Update (and its subclasses that do not override take_action). But if you want to make a number of field updates that need to be grouped into a single logical change, you can call start_change and end_change yourself on the record object.

Views

If you want to display changes for a record class, mount the following into your view tree to expose a default view at /foo/history?id=42 (or you can of course set id via dispatcher rule).

use Jifty::Plugin::RecordHistory::View;
alias Jifty::Plugin::RecordHistory::View under '/foo/history', {
    object_type => 'Foo',
};

Alternatively, if you want to extend the default templates, you can subclass Jifty::Plugin::RecordHistory::View in the same way as Jifty::View::Declare::CRUD.

Access control

By default, we delegate "current_user_can" in Jifty::Plugin::RecordHistory::Model::Change and "current_user_can" in Jifty::Plugin::RecordHistory::Model::ChangeField to the record class. The logic is if you can read the record, you can read its changes and its change fields. If you can change the record you can create, update, and delete changes and their change fields. If you want more fine-grained control over this, you can implement a current_user_can_for_change method in your record class which, if present, we will use instead of this logic.

SEE ALSO

Jifty::Plugin::ActorMetadata

AUTHOR

Shawn M Moore <sartak@bestpractical.com>

LICENSE

Jifty::Plugin::RecordHistory is Copyright 2011 Best Practical Solutions, LLC. Jifty::Plugin::RecordHistory is distributed under the same terms as Perl itself.