custom_change_messages 0.2.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 [Jeremy Olliver]
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README

@@ -0,0 +1,105 @@
+CustomChangeMessages
+====================
+
+CustomChangeMessages is a rails plugin for providing a nicely formatted log message recording any edits made to an active record object.
+This is based off of the ActiveRecord::Dirty module, making this plugin compatible with rails versions 2.1 and up. There is little to no configuration required, with all columns included by default (except for id, and created_at, updated_at timestamps), and belongs_to associations handled nicely with the default options configurable.
+
+Usage
+=====
+
+# In a controllers #update action
+
+def update
+	@post = Post.find(params[:id])
+	@post.attributes = params[:post]
+	@changes = @post.change_messages
+	# Use this array to either log history, display in a flash message, or in a mailer.
+	# => ["Title has changed from 'Ruby on Rails plugin' to '[Update] Ruby on Rails plugin'", "Category has changed from 'Ruby' to 'Ruby on Rails'"]
+	@post.save!
+end
+
+API
+===
+
+ActiveRecord extensions:
+
+change_message_for(attribute) # Returns a string message representation of the attribute that has changed
+change_messages # Returns an array of the messages for each changed attribute
+
+Installation
+============
+
+gem install custom_change_messages
+
+Rails 2.X
+# config/environment.rb
+config.gem "custom_change_messages"
+
+Rails 3.X
+# Gemfile
+gem "custom_change_messages"
+
+
+Requirements: active record, version 2.1 or greater, if you use an earlier version you can try using http://code.bitsweat.net/svn/dirty which backports the ActiveRecord::Dirty code that this gem depends on to earlier rails versions.
+
+
+Detailed Example
+================
+
+The main use of this is to help clean up controller actions, such as:
+
+class ItemsController < ApplicationController
+
+  def update
+    @item.attributes = params[:item]
+    Mailer.deliver_item_update(@item, @item.change_messages.to_sentence)
+    @item.save!
+
+  rescue ActiveRecord::RecordInvalid => e
+    flash[:error] = e.reord.error_messages
+    redirect_to item_url(@item)
+  end
+  #...
+end
+
+
+@item.change_messages.to_sentence will return human readable mesages such as:
+=> "Description has changed from 'Nice and easy' to 'This task is now rather long and arduous', User has changed from 'Jeremy' to 'Guy', and Due Date has been rescheduled from '09/11/2008' to '10/11/2008'"
+
+The messages for each attribute are also customizable, which is especially handy for dealing with belongs_to
+assocations. Here's a more complicated example:
+
+Use the custom_message_for method to customize the message for the attribute, specifying :display => :name
+will use the method/attribute :name for displaying the record that the item belongs_to
+
+The skip_message_for method can be used to prevent stop any changes to a particular attribute showing up
+
+class Item < ActiveRecord::Base
+  belongs_to :person
+  
+  custom_message_for :person, :display => :username # display the person's username instead of the id
+  custom_message_for :due_on, :as => "Due Date", :message => "has been rescheduled", :format => :pretty_print_date
+  # change the syntax of the message for working with dates, because it makes more sense that way
+  
+  # this method is used for formatting the due_on field when it changes
+  def pretty_print_date(value = self.due_on)
+    value.strftime("%d/%m/%Y")
+  end
+end
+
+class Person < ActiveRecord::Base
+  custom_message_for :username, :as => "Name"
+  skip_message_for :internal_calculation    
+end
+
+p = Person.create!(:username => "Jeremy")
+p2 = Person.create!(:username => "Optimus Prime")
+i = Item.create!(:name => "My Task", :description => nil, :person => p, :due_on => Date.today)
+i.attributes = {:person => p2, :description => "This task is difficult, might need some help"}
+
+i.change_messages
+=> ["Due Date has been rescheduled from '4/12/2008' to '5/12/2008'", "Person has changed from 'Jeremy' to 'Optimus Prime'", "Description has changed from '' to 'This task is difficult, might need some help'"]
+
+
+
+Copyright (c) 2008 Jeremy Olliver, released under the MIT license

data/Rakefile

@@ -0,0 +1,23 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Run tests for custom_change_messages'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the custom_change_messages gem.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Custom Change Messages'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/lib/custom_change_messages.rb

@@ -0,0 +1 @@
+require 'custom_change_messages/active_record'

data/lib/custom_change_messages/active_record.rb

@@ -0,0 +1,184 @@
+ActiveRecord::Base.class_eval do
+  
+  # hash and array to keep track of the customised messages, belongs_to associations, and any skipped attributes
+  class_inheritable_hash :custom_dirty_messages # The watched attributes with configuration options {:field_name => options, ...}
+  class_inheritable_hash :belongs_to_key_mapping
+  
+  CUSTOM_CHANGE_MESSAGE_DEFAULTS = {:message => "has changed", :prefix => "from", :suffix => "to"}
+  DEFAULT_SKIPPED_COLUMNS = [:updated_at, :created_at, :id]
+  
+  DEFAULT_BELONGS_TO_DISPLAY_OPTIONS = [:name, :title, :display, :description]
+  
+  class << self
+  
+    def initialise_default_change_messages
+      unless self.custom_dirty_messages
+        self.custom_dirty_messages = {}
+        self.belongs_to_key_mapping = {}
+        
+        model_columns = self.column_names.collect(&:to_sym)
+        
+        # Don't include foreign keys for belongs_to associations by default, they must be added manually
+        self.reflect_on_all_associations(:belongs_to).each do |association|
+          # model_columns -= [association.primary_key_name.to_sym] # Remove the key name from the attributes that will be watched by default
+          self.belongs_to_key_mapping.merge!(association.primary_key_name.to_sym => association.name)
+        end
+        
+        # Register each column with default options
+        model_columns.each do |column_name|
+          key = key_name_for(column_name)
+          next if DEFAULT_SKIPPED_COLUMNS.include?(key)
+          # custom_dirty_messages[key] = CUSTOM_CHANGE_MESSAGE_DEFAULTS.clone
+          custom_message_for(key)
+        end
+      end
+    end
+  
+    def custom_message_for(*attr_names)
+      initialise_default_change_messages
+      
+      options = attr_names.extract_options!
+      options.symbolize_keys!
+
+      attr_names.each do |attribute|
+        key = key_name_for(attribute)
+        
+        if is_association?(key)
+          association = self.reflect_on_association(key)
+          display_method = options[:display]
+          raise "Incorrect :display option. #{display_method} is undefined for #{association.class_name}" if display_method && !method_or_attribute_exists(association, display_method)
+          display_method ||= find_default_display_method(association)
+          puts "***Warning*** couldn't detect a display method for #{key.to_s}, please set a display option e.g. custom_message_for :#{key.to_s}, :display => :my_display_method (where #{association.class_name}#my_display_method) is defined otherwise #to_s will be used as the default" unless display_method
+          display_method ||= :to_s
+          
+          defaults = CUSTOM_CHANGE_MESSAGE_DEFAULTS.merge({:as => association.name.to_s.humanize.titleize, :display => :to_s})
+          options = defaults.merge(options).merge({:type => :belongs_to})
+        end
+        
+        if self.custom_dirty_messages[key]
+          # override defaults
+          self.custom_dirty_messages[key].merge!(options)
+        else
+          # Set values for any not already being watched
+          self.custom_dirty_messages.merge!({key => options})
+        end
+      end
+    end
+  
+    def skip_message_for(*attr_names)
+      initialise_default_change_messages
+      
+      attr_names.extract_options!
+      attr_names.each do |column_name|
+        key = key_name_for(column_name)
+        self.custom_dirty_messages.delete(key)
+      end
+    end
+    
+    def is_association?(attribute)
+      belongs_to_key_mapping.keys.include?(attribute.to_sym) || belongs_to_key_mapping.values.include?(attribute.to_sym)
+    end
+  
+    def key_name_for(attribute)
+      attribute = attribute.to_sym
+      if is_association?(attribute)
+        # Use the association name for belongs_to (could be already passed in)
+        belongs_to_key_mapping[attribute] || attribute
+      else
+        attribute
+      end
+    end
+    
+    private
+    
+    def method_or_attribute_exists(association, method)
+      klass = association.class_name.constantize
+      (klass.column_names + klass.instance_methods).include?(method.to_s)
+    end
+    
+    def find_default_display_method(association)
+      DEFAULT_BELONGS_TO_DISPLAY_OPTIONS.each do |meth_name|
+        return meth_name if method_or_attribute_exists(association, meth_name)
+      end
+      nil
+    end
+    
+  end
+  
+  def change_messages
+    self.class.initialise_default_change_messages
+    
+    messages = []
+    changes.each do |attribute, diff|
+      key = self.class.key_name_for(attribute) # belongs_to association name, or column_name
+      
+      if self.class.custom_dirty_messages.keys.include?(key)
+        messages << change_message_for(key, diff)
+      end
+    end
+    messages
+  end
+  
+  def change_message_for(attribute, changes = nil)
+    self.class.initialise_default_change_messages
+    
+    column_name = column_name_for(attribute)
+    changes ||= self.send((column_name.to_s + "_change").to_sym)
+    
+    key = self.class.key_name_for(attribute)
+    
+    val = "#{attr_name(key)} #{message_option_value(key, :message)}"
+    val += " #{message_option_value(key, :prefix)} \'#{attr_display(key, changes.first)}\'" unless message_option_value(key, :no_prefix)
+    val += " #{message_option_value(key, :suffix)} \'#{attr_display(key, changes.last)}\'" unless message_option_value(key, :no_suffix)
+    val
+  end
+  
+  private
+  
+  def column_name_for(attribute)
+    attribute = attribute.to_sym
+    if self.class.belongs_to_key_mapping.values.include?(attribute)
+      self.class.belongs_to_key_mapping.to_a.select {|col, assoc_name| assoc_name == attribute }.first.first
+    else
+      attribute
+    end
+  end
+  
+  # check if it's an association name, or if the attribute is being watched
+  def attr_name(key)
+    value = if self.class.custom_dirty_messages[key]
+      if (name = self.class.custom_dirty_messages[key][:as])
+        name
+      else
+        key
+      end
+    else
+      key
+    end
+    value.to_s.humanize.titleize
+  end
+  
+  def attr_display(key, value)
+    if self.class.custom_dirty_messages[key]
+      if (meth = self.class.custom_dirty_messages[key][:format])
+        return self.send(meth, value)
+      elsif (meth = self.class.custom_dirty_messages[key][:display]) && self.class.is_association?(key)
+        assoc = self.class.reflect_on_association(key)
+        raise "must set the :display option for belongs_to associations e.g. :display => :name where name is a method on the parent object" unless meth
+        finder = ("find_by_" + assoc.klass.primary_key).to_sym
+        return assoc.klass.send(finder, value).send(meth.to_sym)
+      end
+    end
+    return value.to_s
+  end
+  
+  def message_option_value(key, option)
+    if self.class.custom_dirty_messages[key]
+      self.class.custom_dirty_messages[key][option] || CUSTOM_CHANGE_MESSAGE_DEFAULTS[option]
+    else
+      CUSTOM_CHANGE_MESSAGE_DEFAULTS[option]
+    end
+  end
+  
+  
+end

data/test/active_record_test.rb

@@ -0,0 +1,115 @@
+require File.dirname(__FILE__) + '/test_helper.rb'
+
+load_schema
+
+class Person < ActiveRecord::Base
+  custom_message_for :username, :as => "Name"
+  skip_message_for :internal_calculation
+end
+
+class Category < ActiveRecord::Base
+  def to_s
+    name
+  end
+end
+
+class Item < ActiveRecord::Base
+  DATEFORMAT = "%d/%m/%Y"
+  belongs_to :person
+  belongs_to :category
+  
+  custom_message_for :person, :display => :username
+  custom_message_for :due_on, :as => "Due Date", :message => "has been rescheduled", :format => :pretty_print_date
+  
+  def pretty_print_date(value = self.due_on)
+    value.strftime(DATEFORMAT)
+  end
+end
+
+
+class ActiveRecordTest < Test::Unit::TestCase
+  
+  def test_active_record_extension
+    i = Item.create!
+    assert i.respond_to?(:change_messages)
+    assert i.respond_to?(:change_message_for)
+  end
+  
+  def test_ignores_timestamps
+    i = Item.create!
+    i.attributes = {:created_at => Date.tomorrow, :updated_at => Date.tomorrow}
+    
+    assert i.change_messages.empty?
+  end
+  
+  def test_belongs_to_and_keys_ignored_by_default
+    c1 = Category.create(:name => "Updates")
+    c2 = Category.create(:name => "Posts")
+    i = Item.create!(:category => c1)
+    
+    i.category = c2
+    
+    assert_equal ["Category has changed from 'Updates' to 'Posts'"], i.change_messages # The belongs_to association (and it's foreign key) should be ignored by default
+  end
+  
+  def test_unwatching
+    p = Person.create!(:username => "Robot", :internal_calculation => 1)
+    p.internal_calculation = 42
+    assert p.change_messages.empty?
+  end
+  
+  def test_labeling_attributes
+    # ensure associations are given the correct name. In this case username has been renamed to 'Name'
+    u = Person.create!(:username => "Jeremy")
+    u.username = "Jeremy O"
+    
+    assert_equal "Name has changed from \'Jeremy\' to \'Jeremy O\'", u.change_message_for(:username)
+  end
+  
+  def test_associations_loaded
+    i = Item.create!(:name => "My Cool Task")
+    assert i.class.custom_dirty_messages[:person]
+    assert_equal :belongs_to, i.class.custom_dirty_messages[:person][:type]
+  end
+  
+  def test_display_of_associations
+    u = Person.create!(:username => "Jeremy")
+    u2 = Person.create!(:username => "Guy")
+    i = Item.create!(:name => "My Task", :description => "super", :person => u)
+    i.person = u2
+    
+    assert_equal "Person has changed from \'Jeremy\' to \'Guy\'", i.change_message_for(:person)
+  end
+  
+  def test_handling_of_nil_attrs
+    i = Item.create!(:name => "Namae wa", :description => nil)
+    i.description = "Japanese sentence"
+    
+    assert_nothing_raised do
+      i.change_messages
+    end
+  end
+  
+  def test_formatting_attributes
+    i = Item.create!(:name => "Task", :due_on => Date.today)
+    i.due_on = Date.tomorrow
+    
+    today = Date.today.strftime(Item::DATEFORMAT)
+    tomorrow = Date.tomorrow.strftime(Item::DATEFORMAT)
+    assert_equal "Due Date has been rescheduled from '#{today}' to '#{tomorrow}'", i.change_message_for(:due_on)
+  end
+  
+  def test_full_sentence_changes
+    p = Person.create!(:username => "Jeremy")
+    p2 = Person.create!(:username => "Optimus")
+    i = Item.create!(:name => "My Task", :description => "Nice and easy", :person => p, :due_on => Date.today)
+    i.attributes = {:person => p2, :description => "This task is difficult, might need some help", :due_on => Date.tomorrow }
+    
+    today = Date.today.strftime(Item::DATEFORMAT)
+    tomorrow = Date.tomorrow.strftime(Item::DATEFORMAT)
+    
+    assert_equal "Due Date has been rescheduled from '#{today}' to '#{tomorrow}', Person has changed from 'Jeremy' to 'Optimus', and Description has changed from 'Nice and easy' to 'This task is difficult, might need some help'", \
+    i.change_messages.to_sentence
+  end
+  
+end

data/test/custom_change_messages_test.rb

@@ -0,0 +1,25 @@
+require File.dirname(__FILE__) + '/test_helper.rb'
+
+class CustomChangeMessagesTest < Test::Unit::TestCase
+
+  class Item < ActiveRecord::Base
+  end
+  
+  class Person < ActiveRecord::Base
+  end
+  
+  def setup
+    # schema needs to be loaded in the other test, so don't load it here a second time, unless this is run first or isolated
+    unless Item.connected? && Person.connected?
+      load_schema
+    end
+  end
+
+  def test_schema_has_loaded_correctly
+    assert_nothing_raised do
+      Item.first
+      Person.first
+    end
+  end
+
+end

data/test/database.yml

@@ -0,0 +1,3 @@
+sqlite3:
+  adapter: sqlite3
+  database: test/custom_change_messages.sqlite3.db

data/test/schema.rb

@@ -0,0 +1,20 @@
+ActiveRecord::Schema.define(:version => 0) do
+  create_table :items, :force => true do |t|
+    t.string :name
+    t.string :description
+    t.integer :person_id
+    t.integer :category_id
+    t.date :due_on
+    t.timestamps
+  end
+  create_table :people, :force => true do |t|
+    t.string :username
+    t.string :role
+    t.string :internal_calculation
+    t.timestamps
+  end
+  create_table :categories, :force => true do |t|
+    t.string :name
+    t.timestamps
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,35 @@
+require 'test/unit'
+
+require 'rubygems'
+require 'active_record'
+
+
+def load_schema
+  config = YAML::load(IO.read(File.dirname(__FILE__) + '/database.yml'))
+  # ActiveRecord::Base.logger = Logger.new(File.dirname(__FILE__) + "/debug.log")
+
+  db_adapter = ENV['DB']
+
+  # no db passed, try one of these fine config-free DBs before bombing.
+  db_adapter ||=
+    begin
+      require 'rubygems'
+      require 'sqlite'
+      'sqlite'
+    rescue LoadError
+      begin
+        require 'sqlite3'
+        'sqlite3'
+      rescue LoadError
+        puts "could not load sqlite for running the tests"
+      end
+    end
+
+  if db_adapter.nil?
+    raise "No DB Adapter selected. Pass the DB= option to pick one, or install Sqlite or Sqlite3."
+  end
+
+  ActiveRecord::Base.establish_connection(config[db_adapter])
+  load(File.dirname(__FILE__) + "/schema.rb")
+  require File.dirname(__FILE__) + '/../rails/init.rb'
+end

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification 
+name: custom_change_messages
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: 
+  segments: 
+  - 0
+  - 2
+  - 0
+  version: 0.2.0
+platform: ruby
+authors: 
+- Jeremy Olliver
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-02-26 00:00:00 +13:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 11
+        segments: 
+        - 2
+        - 1
+        - 0
+        version: 2.1.0
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: sqlite3-ruby
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 21
+        segments: 
+        - 1
+        - 2
+        - 5
+        version: 1.2.5
+  type: :development
+  version_requirements: *id002
+description: Change history for ActiveRecord models in a customisable format, making user friendly logging for change history simple
+email: jeremy.olliver@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README
+- Rakefile
+- MIT-LICENSE
+- lib/custom_change_messages.rb
+- lib/custom_change_messages/active_record.rb
+- test/active_record_test.rb
+- test/custom_change_messages_test.rb
+- test/database.yml
+- test/schema.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://github.com/jeremyolliver/custom_change_messages
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.5.2
+signing_key: 
+specification_version: 3
+summary: Change history for ActiveRecord models
+test_files: 
+- test/active_record_test.rb
+- test/custom_change_messages_test.rb
+- test/database.yml
+- test/schema.rb
+- test/test_helper.rb