simple_audit 0.0.1 → 0.0.2

data/{MIT-LICENSE → LICENSE}

@@ -1,4 +1,4 @@
-Copyright (c) 2010 [name of plugin creator]
+Copyright (c) 2010 [Gabriel Târnovan]
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.markdown

@@ -1,18 +1,122 @@
-# SimpleAudit
+# simple_audit
 
+Simple auditing solution for ActiveRecord models. Provides an easy way of creating audit logs for complex model associations.
+Instead of storing audits for all data aggregated by the audited model, you can specify a serializable representation of the model.
+    
+  * a helper method is provided to easily display the audit log
+  * the Audit object provides a #delta method which computs the differences between two audits
 
-Simple auditing solution for ActiveRecord models. 
+In a nutshell:
 
+    class Booking < ActiveRecord::Base
+      simple_audit
+      
+      # data to be audited
+      def audit_changes
+        {
+            :price => self.price,
+            :period => self.period, 
+            ...
+        }
+      end
+    end
+    
+    # in your view
+    <%= render_audits(@booking) %>
 
-# Installation
+# Why ?
+
+simple_audit is intended as a straightforward auditing solution for complex model associations. 
+In a normalized data structure (which is usually the case when using SQL), a core business model will aggregate data from several associated entities.
+More often than not in such cases, only the core model is of interest from an auditing point of view. 
+
+So instead of auditing every entity sepparately, with simple_audit you decide for each audited model what data needs to be audited. 
+This data will be serialized on every model update and the available helper methods will render a clear audit trail.
+
+![Screenshot of helper result](http://github.com/gtarnovan/simple_audit/raw/master/screenshot.png)s
+
+# Installation & Configuration
+
+## As a gem
+    
+    gem install simple_audit
+
+and require it
+    
+    config.gem 'simple_audit'
 
 ## As a plugin
-  ./script/plugin install http://github.com/gtarnovan/simple_audit
+  
+    ./script/plugin install http://github.com/gtarnovan/simple_audit
+
+## Database
+
+Generate and run migration
+
+    ./script/generate simple_audit_migration create_audits
+    rake db:migrate    
+
+# Usage
+
+Audit ActiveRecord models. Somewhere in your (backend) views show the audit logs.
+    
+    # in your model
+    # app/models/booking.rb
+    
+    class Booking < ActiveRecord::Base
+        simple_audit
+        ...
+    end
+    
+    # in your view
+    # app/views/bookings/booking.html.erb
+    
+    ...
+    <%= render_audits(@booking) %>
+    ...     
+
+# Assumptions and limitations
+
+  * Your user model is called User and the current user User.current
+    See [sentient_user](http://github.com/bokmann/sentient_user) for more information.
+
+  * You have to write your own tests (fow now)
+  
+
+    
+## Customize auditing
+
+By default after each save, all model's attributes are saved in the audits table.
+You can customize the data which is saved by overriding the audit_changes method. All relevant data for the audited model should be included here.
 
-# Example
+    # app/models/booking.rb
+    
+    class Booking < ActiveRecord::Base
+        simple_audit
+    
+        def audit_changes
+          {
+            :state  => self.state, 
+            :price  => self.price.format,
+            :period => self.period.to_s,
+            :housing_units => housing_units.collect(&:name).join('; '),
+            ...
+            }
+        end
+        ...
+    end
+    
+You can also customize the attribute of the User model which will be stored in the audit.
 
+    # default is :name
+    simple_audit :username_method => :email
+    
+## Rendering audit 
 
-Example goes here.
+A helper method for displaying a list of audits is provided. It will render a decorated list of the provided audits;
+only the differences between revisions will be shown, thus making the audit information easily readable.
 
+![Screenshot of helper result](http://github.com/gtarnovan/simple_audit/raw/master/screenshot.png)
+    
 
-Copyright (c) 2010 [name of plugin creator], released under the MIT license
+Copyright (c) 2010 [Gabriel Târnovan, Cubus Arts](http://cubus.ro "Cubus Arts"), released under the MIT license

data/Rakefile

@@ -43,7 +43,7 @@ begin
     gemspec.email = "gabriel.tarnovan@cubus.ro"
     gemspec.homepage = "http://github.com/gtarnovan/simple_audit"
     gemspec.authors = ["Gabriel Tarnovan"]
-    gemspec.version = "0.0.1"
+    gemspec.version = "0.0.2"
     gemspec.files = gem_files.to_a
     
     gemspec.rubyforge_project = 'simple_audit'

data/TODO

@@ -0,0 +1,3 @@
+* migration generator
+* customizable method for getting the current user
+* tests

data/lib/app/helpers/simple_audit_helper.rb

@@ -1,7 +1,8 @@
 module SimpleAuditHelper
 
-  def render_audits(audits)
-    audits = audits.dup.sort{|a, b| b.created_at <=> a.created_at}
+  def render_audits(audited_model)
+    return '' unless audited_model.respond_to?(:audits)
+    audits = (audited_model.audits || []).dup.sort{|a,b| b.created_at <=> a.created_at}
     res = ''
     audits.each_with_index do |audit, index|
       older_audit = audits[index + 1]

data/simple_audit.gemspec

@@ -5,23 +5,27 @@
 
 Gem::Specification.new do |s|
   s.name = %q{simple_audit}
-  s.version = "0.0.1"
+  s.version = "0.0.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Gabriel Tarnovan"]
-  s.date = %q{2010-06-02}
+  s.date = %q{2010-06-04}
   s.email = %q{gabriel.tarnovan@cubus.ro}
   s.extra_rdoc_files = [
-    "README.markdown"
+    "LICENSE",
+     "README.markdown",
+     "TODO"
   ]
   s.files = [
-    "MIT-LICENSE",
+    "LICENSE",
      "README.markdown",
      "Rakefile",
+     "TODO",
      "lib/app/helpers/simple_audit_helper.rb",
      "lib/app/models/audit.rb",
      "lib/simple_audit.rb",
      "rails/init.rb",
+     "screenshot.png",
      "simple_audit.gemspec",
      "tasks/simple_audit_tasks.rake",
      "test/simple_audit_test.rb",

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 0
-  - 1
-  version: 0.0.1
+  - 2
+  version: 0.0.2
 platform: ruby
 authors: 
 - Gabriel Tarnovan
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-06-02 00:00:00 +03:00
+date: 2010-06-04 00:00:00 +03:00
 default_executable: 
 dependencies: []
 
@@ -25,15 +25,19 @@ executables: []
 extensions: []
 
 extra_rdoc_files: 
+- LICENSE
 - README.markdown
+- TODO
 files: 
-- MIT-LICENSE
+- LICENSE
 - README.markdown
 - Rakefile
+- TODO
 - lib/app/helpers/simple_audit_helper.rb
 - lib/app/models/audit.rb
 - lib/simple_audit.rb
 - rails/init.rb
+- screenshot.png
 - simple_audit.gemspec
 - tasks/simple_audit_tasks.rake
 - test/simple_audit_test.rb