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

When we read a Change record, we simply ask if the current user can read the corresponding record.

Otherwise, when we create (or update or delete) Change records, we demand that the current user is a superuser. In our after_set and before_delete hooks, we perform these operations as superuser.

We require superuser so that ordinary users cannot use Jifty::Plugin::REST or similar to inject forged Change entries.

Also, when we create a Change record, we do it as the superuser because if by updating a record the ordinary user loses access to update the record, then they will get a permission error when we go to create the corresponding Change. So not only does that change never end up in the record's history, but also Jifty complains permission denied to the user directly.

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.

cpanm Jifty::Plugin::RecordHistory

perl -MCPAN -e shell
install Jifty::Plugin::RecordHistory