Auditable
=========

Auditable is a simple rails plugin that let's you keep audit logs about
whom is making what changes to your models.
You can always get the latest version of this plugin from Github:
  - http://github.com/jamesotron/Auditable [web url]
  - git://github.com/jamesotron/Auditable.git [clone url]

If you're using Auditable in production please email me and give me your
feedback to james@mashd.cc.  Feel free to fork Auditable on github and
or send me patches, I'm always interested in use cases.

Auditable is released under the Mozilla MPL 1.1, all code is copyright
2009 James Harton.

Example
=======

Install Auditable using the plugin script:

  $ ./script/plugin install git://github.com/jamesotron/Auditable.git
  Initialized empty Git repository in /Users/jnh/tmp/test/vendor/plugins/Auditable/.git/
  remote: Counting objects: 22, done.
  remote: Compressing objects: 100% (19/19), done.
  remote: Total 22 (delta 4), reused 0 (delta 0)
  Unpacking objects: 100% (22/22), done.
  From git://github.com/jamesotron/Auditable
   * branch            HEAD       -> FETCH_HEAD
  * Generating model and migration...
	exists  app/models/
	exists  test/unit/
	exists  test/fixtures/
	create  app/models/audit.rb
	create  test/unit/audit_test.rb
	create  test/fixtures/audits.yml
	create  db/migrate
	create  db/migrate/20091208005219_create_audits.rb
  * Making model polymorphic...
  * You probably want to run rake db:migrate now.
  * Done.

Auditable will generate a model and migration called Audit, which you can
safely remove if you don't want to use the default model.
If you want to use the default Audit model then run

  $ rake db:migrate
  (in /Users/jnh/tmp/test)
  ==  CreateAudits: migrating ===================================================
  -- create_table(:audits)
     -> 0.0032s
  ==  CreateAudits: migrated (0.0035s) ==========================================

to create the table in your database.

Now on any models you want you can simply add an acts_as_auditable line:

class WorrisomeData < ActiveRecord::Base

  acts_as_auditable

end

acts_as_auditable defaults to paranoid, so you may wish to change it, options
available are:

  :using =>
     - symbol pointing to the polymorphic model to use for storing audit
       logs. Defaults to :auditable. Only useful if you are defining your
       own Audit model.
  :relation => 
     - symbol pointing to the relationship mapping for audit logs. Defaults
       to :audits. Useful if you want to access the audit log by a method
       other than Model.audits()
  :when => []
     - an array containing symbols describing on which actions to write
       audit logs. Defaults to 
         [ :accessed, :modified, :saved, :created, :deleted ].
     - opposite :except => []
       speficially exclude an action from auditing.
  :identity =>
     - Auditable also adds an around_filter to your ApplicationController 
       to make sure that it has access to the currently logged in user 
       if at all possible.  All you need to do is make sure you set 
       session[:current_user] and Auditable will do the rest. Otherwise
       you can set :identity to a lambda or Proc block containing any code 
       needed to retrieve whatever identifier you wish to use.
  :for => []
     - an array of symbols naming the model fields you wish to audit.
       Defaults to [ :all ] (:all is a special name meaning all fields).
       Note that you can never audit :id because it will cause an infinite
       loop.
     - opposite :not => []
       specifically exclude a field from auditing.
  :log_field =>
     - A symbol naming the text field in the auditor model to store the
       log information in. Only useful if you need something more than the
       default Audit model.
  :identity_field =>
     - A symbol naming the string field in the auditor model to store the
       user's identity information in. Only useful if you need something
       more than the default Audit model.

Copyright (c) 2009 James Harton, released under the Mozilla Public License version 1.1