[Bps-public-commit] jifty-plugin-recordhistory branch, master, updated. f64e41793ec64db46a9436c4af7ba4e62a3fd004

[Shawn Moore]

The branch, master has been updated
       via  f64e41793ec64db46a9436c4af7ba4e62a3fd004 (commit)
      from  ea96093513a7adfffb8835d45a6a9ebcef0be410 (commit)

Summary of changes:
 lib/Jifty/Plugin/RecordHistory.pm                  |   28 ++++++++++++++++++++
 .../RecordHistory/Mixin/Model/RecordHistory.pm     |    4 ++-
 2 files changed, 31 insertions(+), 1 deletions(-)

- Log -----------------------------------------------------------------
commit f64e41793ec64db46a9436c4af7ba4e62a3fd004
Author: Shawn M Moore <sartak at bestpractical.com>
Date:   Wed Feb 9 21:47:10 2011 -0500

    Doc

diff --git a/lib/Jifty/Plugin/RecordHistory.pm b/lib/Jifty/Plugin/RecordHistory.pm
index 26cd262..0a437f6 100644
--- a/lib/Jifty/Plugin/RecordHistory.pm
+++ b/lib/Jifty/Plugin/RecordHistory.pm
@@ -13,8 +13,36 @@ __END__
 
 Jifty::Plugin::RecordHistory - track all changes made to a record class
 
+=head1 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;
+
 =head1 DESCRIPTION
 
+When you use L<Jifty::Plugin::RecordHistory::Mixin::Model::RecordHistory> in a
+record class, we add a C<changes> method which returns an
+L<Jifty::Plugin::RecordHistory::Model::ChangeCollection>. These changes describe
+the updates made to the record, including its creation. Some changes also have
+C<change_fields> which describe updates to the individual fields of the record.
+
+You do not need to do anything beyond adding C<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.
+
+By default, the only mechanism that groups together change_fields onto a single
+change object is L<Jifty::Action::Record::Update> (and its subclasses that do
+not override C<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
+C<start_change> and C<end_change> yourself on the record object.
 
 =head1 SEE ALSO
 
diff --git a/lib/Jifty/Plugin/RecordHistory/Mixin/Model/RecordHistory.pm b/lib/Jifty/Plugin/RecordHistory/Mixin/Model/RecordHistory.pm
index c73390c..d01622e 100644
--- a/lib/Jifty/Plugin/RecordHistory/Mixin/Model/RecordHistory.pm
+++ b/lib/Jifty/Plugin/RecordHistory/Mixin/Model/RecordHistory.pm
@@ -50,7 +50,7 @@ sub import {
         );
     });
 
-    # we hook into before_delete so we can still access changes etc
+    # we hook into before_delete so we can still access ->changes etc
     $caller->add_trigger(before_delete => sub {
         my $self = shift;
 
@@ -65,6 +65,8 @@ sub import {
         }
     });
 
+    # wrap update actions in a change so we can group them as one change with
+    # many field changes
     $caller->add_trigger(start_update_action => sub {
         my $self = shift;
         $self->start_change;

-----------------------------------------------------------------------