paper_trail 1

API 简要！

当你在 model 里声明 has_paper_trail

class Widget < ActiveRecord::Base
  has_paper_trail   # you can pass various options here
end

你就可以有以下方法：

# Returns this widget's versions.  You can customise the name of the association.
widget.versions

# Return the version this widget was reified from, or nil if it is live.
# You can customise the name of the method.
widget.version

# Returns true if this widget is the current, live one; or false if it is from a previous version.
widget.live?

# Returns who put the widget into its current state.
widget.originator

# Returns the widget (not a version) as it looked at the given timestamp.
widget.version_at(timestamp)

# Returns the widget (not a version) as it was most recently.
widget.previous_version

# Returns the widget (not a version) as it became next.
widget.next_version

# Turn PaperTrail off for all widgets.
Widget.paper_trail_off

# Turn PaperTrail on for all widgets.
Widget.paper_trail_on

并且每一个 Version 实例变量也可以有如下方法：

# Returns the item restored from this version.
version.reify(options = {})

# Returns who put the item into the state stored in this version.
version.originator

# Returns who changed the item from the state it had in this version.
version.terminator
version.whodunnit

# Returns the next version.
version.next

# Returns the previous version.
version.previous

# Returns the index of this version in all the versions.
version.index

# Returns the event that caused this version (create|update|destroy).
version.event

当然了，在‘控制器’里使用时，你可以 ‘重载’ 这 两个 方法：

# Returns the user who is responsible for any changes that occur.
# Defaults to current_user.
user_for_paper_trail

# Returns any information about the controller or request that you want
# PaperTrail to store alongside any changes that occur.
info_for_paper_trail

基本使用

PaperTrail 使用简单，只要 ‘敲’ 15 个字符，你就可以跟踪每一个 create, update, 和 destroy 改变：

class Widget < ActiveRecord::Base
  has_paper_trail
end

每一次改变，都是一个版本 ‘versions’，因此你可以有 versions 方法：

>> widget = Widget.find 42
>> widget.versions             # [<Version>, <Version>, ...]

每一个版本又有自己的 ‘特点’

>> v = widget.versions.last
>> v.event                     # 'update' (or 'create' or 'destroy')
>> v.whodunnit                 # '153'  (if the update was via a controller and
                               #         the controller has a current_user method,
                               #         here returning the id of the current user)
>> v.created_at                # when the update occurred
>> widget = v.reify            # the widget as it was before the update;
                               # would be nil for a create event

再次强调

PaperTrail 记录模型对象的每一次改动，这对于已经存在于 ‘DB’ 中的对象也一样适用！

>> widget = Widget.find 153
>> widget.name                                 # 'Doobly'

# Add has_paper_trail to Widget model.

>> widget.versions                             # []
>> widget.update_attributes :name => 'Wotsit'
>> widget.versions.first.reify.name            # 'Doobly'
>> widget.versions.first.event                 # 'update'

这也意味着 PaperTrail 不会浪费空间去‘存储’ 当前版本(这没意义，也没必要)。因为对于‘当前’版本，你可以像平常一样去获得其 ‘信息’。