hound 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: dbbb90e55615005651013a007a49add63ba47920
-  data.tar.gz: 6b477231c8ac9307b8e6b6a8a6aa0a3a0a66044c
+  metadata.gz: 17ce6502740de85ef5dcb728028205418d81af11
+  data.tar.gz: 142481253159ae0d10042948213a469f4cc763e6
 SHA512:
-  metadata.gz: cc5d8f271aabddb48373cfcee959c9e3d0848c1f018719cb9dc3bc96d250b56d701e15ef939f7b06df9bf0a6f87fe3d695ea30e14231d66356e674b6568dd04c
-  data.tar.gz: 635412aa1c93cacef0b7ba2d687682b2827619da9a00b0e4f27f21b19c18166287a0ffa12b64b59ba0cb97c5c5aedafec695b65922def8860058b9f514caee97
+  metadata.gz: a4d5e99ef5d62b26d0a88cb67a773438e1fe311ab11f49a06b3b50a5b427e1fdb2e2652268f58b34671467f5cbd3f453a1a91666564fc919fdf374861a1791d9
+  data.tar.gz: 05c6ce2f13cccce70557a3cc855bb57e3f5a3c7ea5894e4db90d83dc0d4c0887b420ed4cebd25601bdb6a3feba78ea71588a4873355d69d2c20da1b760becafd

data/.travis.yml

@@ -1,9 +1,17 @@
 language: ruby
-before_script: 'cd test/dummy && bundle exec rake db:migrate'
+
 rvm:
-  - 1.9.2
   - 1.9.3
-notifications:
-  email:
-    on_success: change
-    on_failure: always
+
+env:
+  - DB=sqlite
+  - DB=mysql
+  - DB=postgresql
+
+before_script:
+  - rake app:db:create
+  - rake app:db:migrate
+  - rake app:db:test:prepare
+
+after_script:
+  - rake app:db:rollback

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+## v0.3.0 - March 14, 2013
+
+* Implement `hound_user` and polymorphic user association (#3).
+* Hook into user model and add `has_many :actions`.
+* Ensure Hound does not raise an exception if a user class does not exist.
+
+## v0.2.0 - March 10, 2013
+
+* Support tracking changes made to hounded models.
+
+## v0.1.0 - March 8, 2013
+
+* Support limiting actions.
+* Added `hound_action` helper to controllers.
+* Support for a custom User class.
+* Support travis CI.
+* Lower Rails dependency version.
+
+## v0.0.1 - March 7, 2013
+
+* Initial Release of Hound. Support tracking actions made to models.

data/Gemfile

@@ -15,3 +15,8 @@ gem "jquery-rails"
 
 # To use debugger
 # gem 'debugger'
+group :development, :test do
+  gem 'sqlite3'
+  gem 'mysql2'
+  gem 'pg'
+end

data/README.md

@@ -1,5 +1,19 @@
 # Hound
 
+[![Build Status](https://travis-ci.org/injekt/hound.png?branch=master)](https://travis-ci.org/injekt/hound)
+
+Hound is designed to track activity on models. It'll track your usual
+`create` `update` and `destroy` actions as well as custom activity.
+
+At [Allur](https://www.allur.com) or more specifically the
+[Spark CRM](http://allurspark.com) we've built, we use Hound for implementing
+activity tabs on our popular models. These activity tabs display
+the last x amount of actions taken out upon these models. We have a lot
+of custom associations so we can't simply track the `update` to models.
+With Hound we can build custom actions on the fly.
+
+If you need something similar, Hound could be a good fit.
+
 ## Installation
 
 Add Hound to your `Gemfile` and run `bundle install`:
@@ -58,13 +72,22 @@ end
 ```
 
 For this to work successfully you must tell Hound about your user class
-(note that this value defaults to 'User' already).
+using the `hound_user` method. The `user` association on the `Hound::Action`
+class is polymorphic, so you can use `hound_user` in more than one class.
 
 ```ruby
-Hound.config.user_class = 'CustomUser'
-Hound.config.user_class = AdminUser # String or constant
+class User
+  hound_user
+end
+
+class Admin
+  hound_user
+end
 ```
 
+Now `hound_user` can return either an instance of `User` or an instance of
+`Admin`.
+
 You can also disable Hound on a model instance basis:
 
 ```ruby
@@ -75,7 +98,7 @@ article.save
 article.actions #=> []
 ```
 
-## Changes
+## Tracking Changes
 
 Hound also tracks the changes made when updating your hounded records. You
 can access the change updates through the `changeset` attribute:
@@ -87,6 +110,55 @@ article.actions.last.changeset
   #=> {"title" => ["Hello, World!", "Salut, World!"]}
 ```
 
+## Displaying model activity
+
+Because Hound hooks into your existing user model as well as any models
+you tell it to track, you can display activity from either side. In fact,
+your user object doesn't even need to belong to the object you're tracking.
+
+```ruby
+current_user.name #=> "Lee"
+article = Article.create! title: 'Hello, World!'
+
+article.actions.each do |action|
+  puts "#{action.user.name} #{action + 'ed'} the " \
+    "#{action.actionable_type} #{action.actionable.title}"
+end
+
+current_user.actions.each do |action|
+  puts "#{action.user.name} #{action + 'ed'} the " \
+    "#{action.actionable_type} #{action.actionable.title}"
+end
+```
+
+Both of the above snippets will print the same thing:
+
+```
+Lee created the Article Hello, World!
+```
+
+## Console
+
+Hound implements a storage facility on the current thread for storing
+the id of the current user. This is how we make it available to the model
+data without sending it via the controller itself. This means when
+creating records via the console, there will be no `current_user` available.
+
+```ruby
+>> Article.create! title: 'Foo'
+>> _.actions.last.user
+=> nil
+```
+
+You can solve this by setting `Hound.store[:current_user_id]`:
+
+```ruby
+>> Hound.store[:current_user_id] = User.create!(name: 'Lee').id
+>> Article.create! title: 'Foo'
+>> _.actions.last.user.name
+=> "Lee"
+```
+
 ## Cleaning Up
 
 With all this action creating we're doing, your database is bound to start
@@ -114,6 +186,20 @@ will not only create a new action, it will check and destroy any actions
 outside of this limit. This requires an extra call to the database, so if
 that could be an issue, using a rake task might be a better idea.
 
+## But we already have Paper Trail?
+
+Yes, and Paper Trail is awesome. Hound is not designed to replace it. They
+do different things. Hound is designed to track activity (in the form of
+actions) on a model. Paper Trail does the same thing but it stores snapshots
+of your model at certain times (when they change). Hound is not just for
+tracking changes to your model, but you can attach custom activity to it, too.
+
+* Do I want custom actions and activity attached to my models? Use Hound.
+* Do I need to restore my model to an earlier time? Use Paper Trail.
+
+At [Allur](https://www.allur.com) we use them both for different things,
+and they work great.
+
 ## TODO
 
 * Implement action grouping

data/Rakefile

@@ -21,6 +21,8 @@ RDoc::Task.new(:rdoc) do |rdoc|
 end
 
 Bundler::GemHelper.install_tasks
+APP_RAKEFILE = File.expand_path('../test/dummy/Rakefile', __FILE__)
+load 'rails/tasks/engine.rake'
 
 require 'rake/testtask'
 

data/lib/generators/hound/templates/create_hound_actions.rb

@@ -5,14 +5,17 @@ class CreateHoundActions < ActiveRecord::Migration
       t.string   :actionable_type, null: false
       t.integer  :actionable_id,   null: false
       t.integer  :user_id
+      t.string   :user_type
       t.datetime :created_at
       t.text     :changeset
     end
     add_index :hound_actions, [:actionable_type, :actionable_id]
+    add_index :hound_actions, [:user_type, :user_id]
   end
 
   def self.down
     remove_index :hound_actions, [:actionable_type, :actionable_id]
+    remove_index :hound_actions, [:user_type, :user_id]
     drop_table :hound_actions
   end
 end

data/lib/hound/action.rb

@@ -1,9 +1,13 @@
 module Hound
   class Action < ActiveRecord::Base
     self.table_name = 'hound_actions'
-    attr_accessible :action, :actionable_id, :actionable_type, :user_id, :changeset
+
+    attr_accessible :action, :actionable_id, :actionable_type,
+      :user_id, :user_type, :changeset
+
     belongs_to :actionable, polymorphic: true
-    belongs_to :user, class_name: Hound.config.user_class
+    belongs_to :user, polymorphic: true
+
     serialize :changeset, Hash
 
     scope :created,   -> { where(action: 'create')  }

data/lib/hound/config.rb

@@ -7,21 +7,13 @@ module Hound
     # An Array of actions Hound should track.
     attr_accessor :actions
 
-    # The String used to represent a User class (defaults to 'User').
-    attr_reader :user_class
-
     # Limit actions on a global basis.
     attr_accessor :limit
 
     def initialize
       @actions = %w'create update destroy'
-      @user_class = 'User'
       @limit = nil
     end
 
-    def user_class=(klassname)
-      @user_class = klassname.to_s
-    end
-
   end
 end

data/lib/hound/controller.rb

@@ -19,14 +19,20 @@ module Hound
       hound_user.try(:id)
     end
 
+    def hound_user_type
+      hound_user.class.base_class.name if hound_user
+    end
+
     private
 
     def hound_action(object, action = params[:action])
-      object.actions.create(action: action, user_id: hound_user_id)
+      object.actions.create(action: action,
+        user_id: hound_user_id, user_type: hound_user_type)
     end
 
     def set_hound_user
       Hound.store[:current_user_id] = hound_user_id
+      Hound.store[:current_user_type] = hound_user_type
     end
 
   end

data/lib/hound/model.rb

@@ -9,13 +9,15 @@ module Hound
 
       # Tell Hound to track this models actions.
       #
-      # options - a Hash of configuration options.
+      # options - a Hash of configuration options (default: {}).
+      #           :limit   - An Integer limit to restrict the maximum actions
+      #                      stored (optional, default: nil (no limit)).
+      #           :actions - An Array of actions to track.
+      #                      (default: [:create, :update, :destroy])
       def hound(options = {})
         send :include, InstanceMethods
 
-        has_many :actions,
-          as: 'actionable',
-          class_name: 'Hound::Action'
+        has_many :actions, as: :actionable, class_name: 'Hound::Action'
 
         options[:actions] ||= Hound.config.actions
         options[:actions] = Array(options[:actions]).map(&:to_s)
@@ -26,9 +28,13 @@ module Hound
         attr_accessor :hound
 
         # Add action hooks
-        after_create :hound_create if options[:actions].include?('create')
-        before_update :hound_update if options[:actions].include?('update')
-        after_destroy :hound_destroy if options[:actions].include?('destroy')
+        after_create :hound_create, if: :hound? if options[:actions].include?('create')
+        before_update :hound_update, if: :hound? if options[:actions].include?('update')
+        after_destroy :hound_destroy, if: :hound? if options[:actions].include?('destroy')
+      end
+
+      def hound_user(options = {})
+        has_many :actions, as: :user, class_name: 'Hound::Action'
       end
     end
 
@@ -47,33 +53,36 @@ module Hound
       private
 
       def hound_create
-        return unless hound?
-        attributes = default_attributes.merge(action: 'create')
-        actions.create! attributes
-        enforce_limit
+        create_action(action: 'create')
       end
 
       def hound_update
-        return unless hound?
-        attributes = default_attributes.merge(action: 'update')
-        attributes.merge!(changeset: changes)
-        actions.create! attributes
-        enforce_limit
+        create_action(action: 'update')
       end
 
       def hound_destroy
-        return unless hound?
-        attributes = default_attributes.merge(action: 'destroy')
-        attributes.merge!(
-          actionable_id: self.id,
-          actionable_type: self.class.base_class.name)
-        Hound::Action.create(attributes)
+        create_action({action: 'destroy'}, false)
+      end
+
+      def create_action(attributes, scoped = true)
+        attributes = default_attributes.merge(attributes)
+        if scoped
+          actions.create!(attributes)
+        else
+          # unscoped actions should still always save the associated data
+          Hound.actions.create(attributes.merge({
+            actionable_id: self.id,
+            actionable_type: self.class.base_class.name
+          }))
+        end
         enforce_limit
       end
 
       def default_attributes
         {
-          user_id: Hound.store[:current_user_id]
+          user_id: Hound.store[:current_user_id],
+          user_type: Hound.store[:current_user_type],
+          changeset: changes
         }
       end
 

data/lib/hound/version.rb

@@ -1,3 +1,3 @@
 module Hound
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

data/test/config_test.rb

@@ -4,11 +4,4 @@ class TestUserClass; end
 
 class ConfigTest < ActiveSupport::TestCase
 
-  test 'user_class' do
-    assert_equal 'User', Hound.config.user_class
-
-    Hound.config.user_class = TestUserClass
-    assert_equal 'TestUserClass', Hound.config.user_class
-  end
-
 end

data/test/dummy/app/models/user.rb

@@ -1,3 +1,4 @@
 class User < ActiveRecord::Base
   attr_accessible :name
+  hound_user
 end

data/test/dummy/db/migrate/{20130308110847_create_hound_actions.rb → 20130314120938_create_hound_actions.rb}

@@ -5,13 +5,17 @@ class CreateHoundActions < ActiveRecord::Migration
       t.string   :actionable_type, null: false
       t.integer  :actionable_id,   null: false
       t.integer  :user_id
+      t.string   :user_type
       t.datetime :created_at
+      t.text     :changeset
     end
     add_index :hound_actions, [:actionable_type, :actionable_id]
+    add_index :hound_actions, [:user_type, :user_id]
   end
 
   def self.down
     remove_index :hound_actions, [:actionable_type, :actionable_id]
+    remove_index :hound_actions, [:user_type, :user_id]
     drop_table :hound_actions
   end
 end

data/test/dummy/db/schema.rb

@@ -11,7 +11,7 @@
 #
 # It's strongly recommended to check this file into your version control system.
 
-ActiveRecord::Schema.define(:version => 20130310103454) do
+ActiveRecord::Schema.define(:version => 20130314120938) do
 
   create_table "articles", :force => true do |t|
     t.string   "title"
@@ -25,11 +25,13 @@ ActiveRecord::Schema.define(:version => 20130310103454) do
     t.string   "actionable_type", :null => false
     t.integer  "actionable_id",   :null => false
     t.integer  "user_id"
+    t.string   "user_type"
     t.datetime "created_at"
     t.text     "changeset"
   end
 
   add_index "hound_actions", ["actionable_type", "actionable_id"], :name => "index_hound_actions_on_actionable_type_and_actionable_id"
+  add_index "hound_actions", ["user_type", "user_id"], :name => "index_hound_actions_on_user_type_and_user_id"
 
   create_table "posts", :force => true do |t|
     t.text     "text"

data/test/hound_test.rb

@@ -36,4 +36,14 @@ class HoundTest < ActiveSupport::TestCase
     end
     assert_equal 3, @post.actions.size
   end
+
+  test 'user has many actions' do
+    user = User.create! name: 'Lee'
+    assert user.respond_to?(:actions)
+    article = Article.create! title: 'Hello, World!'
+    action = article.actions.last
+    action.user = user
+    assert action.save
+    assert_equal article.actions, user.actions
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hound
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Lee Jarvis
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-10 00:00:00.000000000 Z
+date: 2013-03-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -47,6 +47,7 @@ extra_rdoc_files: []
 files:
 - .gitignore
 - .travis.yml
+- CHANGELOG.md
 - Gemfile
 - LICENSE
 - README.md
@@ -98,8 +99,7 @@ files:
 - test/dummy/db/migrate/20130307165752_create_users.rb
 - test/dummy/db/migrate/20130307165837_create_articles.rb
 - test/dummy/db/migrate/20130307183451_create_posts.rb
-- test/dummy/db/migrate/20130308110847_create_hound_actions.rb
-- test/dummy/db/migrate/20130310103454_add_changeset_to_hound_actions.rb
+- test/dummy/db/migrate/20130314120938_create_hound_actions.rb
 - test/dummy/db/schema.rb
 - test/dummy/lib/assets/.gitkeep
 - test/dummy/log/.gitkeep
@@ -139,7 +139,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.0
+rubygems_version: 2.0.3
 signing_key: 
 specification_version: 4
 summary: Trace changes to your models
@@ -180,8 +180,7 @@ test_files:
 - test/dummy/db/migrate/20130307165752_create_users.rb
 - test/dummy/db/migrate/20130307165837_create_articles.rb
 - test/dummy/db/migrate/20130307183451_create_posts.rb
-- test/dummy/db/migrate/20130308110847_create_hound_actions.rb
-- test/dummy/db/migrate/20130310103454_add_changeset_to_hound_actions.rb
+- test/dummy/db/migrate/20130314120938_create_hound_actions.rb
 - test/dummy/db/schema.rb
 - test/dummy/lib/assets/.gitkeep
 - test/dummy/log/.gitkeep

data/test/dummy/db/migrate/20130310103454_add_changeset_to_hound_actions.rb

@@ -1,5 +0,0 @@
-class AddChangesetToHoundActions < ActiveRecord::Migration
-  def change
-    add_column :hound_actions, :changeset, :text
-  end
-end