kennethkalmer / acts_as_audited forked from collectiveidea/acts_as_audited

= acts_as_audited

acts_as_audited is an ActiveRecord extension that logs all changes to your models in an audits table.

== Installation

* Install the plugin into your rails app
  If you are using Rails 2.1:

    script/plugin install git://github.com/collectiveidea/acts_as_audited.git

  For versions prior to 2.1:

    git clone git://github.com/collectiveidea/acts_as_audited.git vendor/plugins/acts_as_audited

* Generate the migration
    script/generate audited_migration add_audits_table
    rake db:migrate

== Usage

If you're using acts_as_audited within Rails, you can simply declare which models should be audited.  acts_as_audited 
can also automatically record the user that made the change if your controller has a <tt>current_user</tt> method.

  class ApplicationController < ActionController::Base
    audit User, List, Item => {:except => :password}
  protected
    def current_user
      @user ||= User.find(session[:user])
    end
  end

To get auditing outside of Rails you can explicitly declare <tt>acts_as_audited</tt> on your models:

    class User < ActiveRecord::Base
      acts_as_audited :except => [:password, :mistress]
    end

To record a user in the audits when the sweepers are not available, you can use <tt>as_user</tt>:

    Audit.as_user( user ) do
      # Perform changes on audited models
    end

See http://opensoul.org/2006/07/21/acts_as_audited for more information.

== Parent record tracking

To track the parent record of the record being audited, you pass an optional parent option in the model being audited:

    class Author < ActiveRecord::Base
      has_many :books
    end
    class Book < ActiveRecord::Base
      belongs_to :author
      acts_as_audited :parent => :author
    end

Each audit entry on a book will be associated to an author through <tt>auditable_parent</tt>, and each author will have 
a <tt>book_audits</tt> association for tracking the collective changes to an authors' books. This becomes really 
valuable to track when a book has been removed from the catalog.

The association name on the parent is built using the singular of the <tt>has_many</tt> association name, with 
<tt>_audits</tt> appended, in the example yielding <tt>book_audits</tt> and not <tt>books_audits</tt>.

== Caveats

If your model declares +attr_accessible+ after +acts_as_audited+, you need to set +:protect+ to false. acts_as_audited 
uses +attr_protected+ internally to prevent malicious users from unassociating your audits, and Rails does not allow 
both +attr_protected+ and +attr_accessible+. It will default to false if +attr_accessible+ is called before 
+acts_as_audited+, but needs to be explicitly set if it is called after.

  class User < ActiveRecord::Base
    acts_as_audited :protect => false
    attr_accessible :name
  end

=== ActiveScaffold

Many users have also reported problems with acts_as_audited and ActiveScaffold, which appears to be caused by a 
limitation in ActiveScaffold not supporting polymorphic associations. To get it to work with ActiveScaffold:

  class ApplicationController < ActionController::Base
    audit MyModel, :only => [:create, :update, :destroy]
  end

== Compatability

acts_as_audited works with Rails 2.1 or later.

== Contributing

Contributions are always welcome. Checkout the latest code on GitHub:
  http://github.com/collectiveidea/acts_as_audited

Please include tests with your patches. There are a few gems required to run the tests:
  $ gem install multi_rails
  $ gem install thoughtbot-shoulda jnunemaker-matchy --source http://gems.github.com

Make sure the tests pass against all versions of Rails since 2.1:

  $ rake test:multi_rails:all

Please report bugs or feature suggestions on GitHub:
  http://github.com/collectiveidea/acts_as_audited/issues