is_visitable 0.1.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Jonas Grimfelt
+
+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.textile

@@ -0,0 +1,266 @@
+h1. IS_VISITABLE
+
+_Rails: Track unique and total visits/viewings of an ActiveRecord resource based on user/account or IP._
+
+h2. Installation
+
+*Gem:*
+
+<pre>sudo gem install is_visitable</pre>
+
+and in @config/environment.rb@:
+
+<pre>config.gem 'is_visitable'</pre>
+
+*Plugin:*
+
+<pre>./script/plugin install git://github.com/grimen/is_visitable.git</pre>
+
+h2. Usage
+
+h3. 1. Generate migration:
+
+<pre>
+$ ./script/generate is_visitable_migration
+</pre>
+
+Generates @db/migrations/{timestamp}_is_visitable_migration@ with:
+
+<pre>
+class IsVisitableMigration < ActiveRecord::Migration
+  def self.up
+    create_table :visits do |t|
+      t.references  :visitable,     :polymorphic => true
+      
+      t.references  :visitor,       :polymorphic => true
+      t.string      :ip,            :limit => 24
+      
+      t.integer     :visits,        :default => 1
+      
+      # created_at <=> first_visited_at
+      # updated_at <=> last_visited_at
+      t.timestamps
+    end
+    
+    add_index :visits, [:visitor_id, :visitor_type]
+    add_index :visits, [:visitable_id, :visitable_type]
+  end
+  
+  def self.down
+    drop_table :visits
+  end
+end
+</pre>
+
+h3. 2. Make your model count visits:
+
+<pre>
+class Post < ActiveRecord::Base
+  is_visitable
+end
+</pre>
+
+or, with explicit visitor (or visitors):
+
+<pre>
+class Post < ActiveRecord::Base
+  # Setup associations for the visitor class(es) automatically.
+  is_visitable :by => [:users, :ducks]
+end
+</pre>
+
+h3. 3. ...and here we go:
+
+Examples:
+
+<pre>
+@post = Post.create
+
+@post.visited?          # => false
+@post.unique_visits     # => 0
+@post.total_visits      # => 0
+
+@post.visit!(:visitor => '128.0.0.0')
+@post.visit!(:visitor => @user)      # aliases: :user, :account
+
+@post.visited?          # => true
+@post.unique_visits     # => 2
+@post.total_visits      # => 2
+
+@post.visit!(:visitor => '128.0.0.0')
+@post.visit!(:visitor => @user)
+@post.visit!(:visitor => '128.0.0.1')
+
+@post.unique_visits     # => 3
+@post.total_visits      # => 5
+
+@post.visited_by?('128.0.0.0')     # => true
+@post.visited_by?(@user)           # => true
+@post.visited_by?('128.0.0.2')     # => false
+@post.visited_by?(@another_user)   # => false
+
+@post.reset_visits!
+@post.unique_visits     # => 0
+@post.total_visits      # => 0
+
+# Note: See documentation for more info.
+
+</pre>
+
+h2. Mixin Arguments
+
+The @is_visitable@ mixin takes some hash arguments for customization:
+
+* @:by@ - the visitor model(s), e.g. User, Account, etc. (accepts either symbol or class, i.e. @User@ <=> @:user@ <=> @:users@, or an array of suchif there are more than one visitor model). The visitor model will be setup for you. Note: Polymorhic, so it accepts any model. Default: @nil@.
+* @:accept_ip@ - accept anonymous users uniquely identified by IP (well...you handle the bots =D). See examples below how to use this as your visitor object. Default: @false@.
+
+h2. Aliases
+
+To make the usage of IsVistable a bit more generic (similar to other plugins you may use), there are two useful aliases for this purpose:
+
+* @Visit#owner@     <=>   @Visit#visitor@
+* @Visit#object@    <=>   @Visit#visitable@
+
+Example:
+
+<pre>
+@post.visits.first.owner == post.visits.first.visitor      # => true
+@post.visits.first.object == post.visits.first.visitable   # => true
+</pre>
+
+h2. Finders (Named Scopes)
+
+IsVisitable has plenty of useful finders implemented using named scopes. Here they are:
+
+h3. @Visit@
+
+*Order:*
+
+* @in_order@ - most recent visits last (order by creation date).
+* @most_recent@ - most recent visits first (opposite of @in_order@ above).
+* @least_visits@ - visits with least total visits first.
+* @most_rating@ - visits with most total visits first.
+
+*Filter:*
+
+* @limit(<number_of_items>)@ - maximum @<number_of_items>@ visits.
+* @since(<created_at_datetime>)@ - visits since @<created_at_datetime>@.
+* @recent(<datetime_or_size>)@ - if DateTime: visits since @<datetime_or_size>@, else if Fixnum: pick last @<datetime_or_size>@ number of visits.
+* @between_dates(<from_date>, to_date)@ - visits between two datetimes.
+* @with_visits(<visits_value_or_range>)@ - visits with(in) visits value (or range) @<visits_value_or_range>@.
+* @of_visitable_type(<visitable_type>)@ - visits of @<visitable_type>@ type of visitable models.
+* @by_visitor_type(<visitor_type>)@ - visits of @<visitor_type>@ type of visitor models.
+* @on(<visitable_object>)@ - visits on the visitable object @<visitable_object>@ .
+* @by(<visitor_object>)@ - visits by the @<visitor_object>@ type of visitor models.
+
+h3. @Visitable@
+
+_TODO: Documentation on named scopes for Visitable._
+
+h3. @Visitor@
+
+_TODO: Documentation on named scopes for Visitor._
+
+h3. Examples using finders:
+
+<pre>
+@user = User.first
+@post = Post.first
+
+@post.visits.recent(10)           # => [10 most recent visits]
+@post.visits.recent(1.week.ago)   # => [visits since 1 week ago]
+
+@post.visits.with_visits(100..500)    # => [all visits on @post with total visits between 100 and 500]
+
+@post.visits.by_visitor_type(:user)   # => [all visits on @post by User-objects]
+# ...or:
+@post.visits.by_visitor_type(:users)  # => [all visits on @post by User-objects]
+# ...or:
+@post.visits.by_visitor_type(User)    # => [all visits on @post by User-objects]
+
+@user.visits.on(@post)  # => [all visits by @user on @post]
+@post.visits.by(@user)  # => [all visits by @user on @post] (equivalent with above)
+
+Visit.on(@post)  # => [all visits on @user] <=> @post.visits
+Visit.by(@user)  # => [all visits by @user] <=> @user.visits
+
+# etc, etc. It's all named scopes, so it's really no new hokus-pokus you have to learn.
+</pre>
+
+h2. Additional Methods
+
+*Note:* See documentation (RDoc).
+
+h2. Extend the Visit model
+
+This is optional, but if you wanna be in control of your models (in this case @Visit@) you can take control like this:
+
+<pre>
+class Visit < IsVisitable::Visit
+  
+  # Do what you do best here... (stating the obvious: core IsVisitable associations, named scopes, etc. will be inherited)
+  
+end
+</pre>
+
+h2. Caching
+
+If the visitable class table - in the sample above @Post@ - contains a columns @cached_total_visits_count@ and @cached_unique_visits@, then a cached value will be maintained within it for the number of unique and total visits the object have got. This will save a database query for counting the number of visits, which is a common task.
+
+Additional caching fields:
+
+<pre>
+class AddTrackVisitsCachingToPostsMigration < ActiveRecord::Migration
+  def self.up
+    # Enable is_visitable-caching.
+    add_column :posts, :cached_unique_visits, :integer
+    add_column :posts, :cached_total_visits, :integer
+  end
+  
+  def self.down
+    remove_column :posts, :cached_unique_visits
+    remove_column :posts, :cached_total_visits
+  end
+end
+</pre>
+
+h2. Example
+
+h3. In your "visitable resource" controller:
+
+Example: @app/controllers/posts_controller.rb@:
+
+<pre>
+class PostsController < ApplicationController
+  
+  def show
+    ...
+    @post.visit!(:visitor => (current_user.present? ? current_user : request.try(:remote_ip)))
+    ...
+  end
+  
+end
+</pre>
+
+h2. Dependencies
+
+For testing: "shoulda":http://github.com/thoughtbot/shoulda, "redgreen":http://gemcutter.org/gems/redgreen, "acts_as_fu":http://github.com/nakajima/acts_as_fu, and "sqlite3-ruby":http://gemcutter.org/gems/sqlite3-ruby.
+
+h2. Notes
+
+* Tested with Ruby 1.8.6 - 1.9.1 and Rails 2.3.2 - 2.3.4.
+* Let me know if you find any bugs; not used in production yet so consider this a concept version.
+
+h2. TODO
+
+* documentation: A few more README-examples.
+* helper: Controller helper taking arguments for DRYer controller code. Example (in controller): handle_visits :by => current_user
+* feature: Useful finders for @Visitable@.
+* feature: Useful finders for @Visitor@.
+* testing: More thorough tests for more complex scenarios.
+* refactor: Refactor generic stuff to new gem, @is_base@, and add as gem dependency. Reason: Share the same patterns for my very similar ActiveRecord plugins: is_reviewable, is_visitable, is_commentable, and future additions.
+
+h2. License
+
+Released under the MIT license.
+Copyright (c) "Jonas Grimfelt":http://github.com/grimen

data/Rakefile

@@ -0,0 +1,63 @@
+# coding: utf-8
+require 'rubygems'
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+NAME = "is_visitable"
+SUMMARY = %Q{Rails: Track unique and total visits/viewings of an ActiveRecord resource based on user/account or IP.}
+HOMEPAGE = "http://github.com/grimen/#{NAME}"
+AUTHOR = "Jonas Grimfelt"
+EMAIL = "grimen@gmail.com"
+SUPPORT_FILES = %w(README.textile)
+
+begin
+  gem 'jeweler', '>= 1.0.0'
+  require 'jeweler'
+  
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = NAME
+    gemspec.summary = SUMMARY
+    gemspec.description = SUMMARY
+    gemspec.homepage = HOMEPAGE
+    gemspec.author = AUTHOR
+    gemspec.email = EMAIL
+    
+    gemspec.require_paths = %w{lib}
+    gemspec.files = SUPPORT_FILES << %w(MIT-LICENSE Rakefile) << Dir.glob(File.join(*%w[{generators,lib,test} ** *]).to_s)
+    gemspec.executables = %w[]
+    gemspec.extra_rdoc_files = SUPPORT_FILES
+    
+    gemspec.add_dependency 'activerecord', '>= 1.2.3'
+    gemspec.add_dependency 'activesupport', '>= 1.2.3'
+    
+    gemspec.add_development_dependency 'test-unit', '= 1.2.3'
+    gemspec.add_development_dependency 'shoulda', '>= 2.10.0'
+    gemspec.add_development_dependency 'redgreen', '>= 0.10.4'
+    gemspec.add_development_dependency 'sqlite3-ruby', '>= 1.2.0'
+    gemspec.add_development_dependency 'acts_as_fu', '>= 0.0.5'
+  end
+  
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler - or one of it's dependencies - is not available. Install it with: sudo gem install jeweler -s http://gemcutter.org"
+end
+
+desc %Q{Run unit tests for "#{NAME}".}
+task :default => :test
+
+desc %Q{Run unit tests for "#{NAME}".}
+Rake::TestTask.new(:test) do |test|
+  test.libs << %w[lib test]
+  test.pattern = File.join(*%w[test ** *_test.rb])
+  test.verbose = true
+end
+
+desc %Q{Generate documentation for "#{NAME}".}
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = NAME
+  rdoc.options << '--line-numbers' << '--inline-source' << '--charset=UTF-8'
+  rdoc.rdoc_files.include(SUPPORT_FILES)
+  rdoc.rdoc_files.include(File.join(*%w[lib ** *.rb]))
+end

data/generators/is_visitable_migration/is_visitable_migration_generator.rb

@@ -0,0 +1,12 @@
+# coding: utf-8
+
+class IsVisitableMigrationGenerator < Rails::Generator::Base
+  
+  def manifest
+    record do |m|
+      m.migration_template 'migration.rb',
+        File.join('db', 'migrate'), :migration_file_name => 'is_visitable_migration'
+    end
+  end
+  
+end

data/generators/is_visitable_migration/templates/migration.rb

@@ -0,0 +1,25 @@
+# coding: utf-8
+
+class IsVisitableMigration < ActiveRecord::Migration
+  def self.up
+    create_table :visits do |t|
+      t.references  :visitable,     :polymorphic => true
+      
+      t.references  :visitor,       :polymorphic => true
+      t.string      :ip,            :limit => 24
+      
+      t.integer     :visits,        :default => 1
+      
+      # created_at <=> first_visited_at
+      # updated_at <=> last_visited_at
+      t.timestamps
+    end
+    
+    add_index :visits, [:visitor_id, :visitor_type]
+    add_index :visits, [:visitable_id, :visitable_type]
+  end
+  
+  def self.down
+    drop_table :visits
+  end
+end

data/lib/is_visitable.rb

@@ -0,0 +1,38 @@
+# coding: utf-8
+require File.join(File.dirname(__FILE__), *%w[is_visitable visit])
+require File.join(File.dirname(__FILE__), *%w[is_visitable visitor])
+require File.join(File.dirname(__FILE__), *%w[is_visitable visitable])
+require File.join(File.dirname(__FILE__), *%w[is_visitable support])
+
+module IsVisitable
+  
+  extend self
+  
+  class IsVisitableError < ::StandardError
+    def initialize(message)
+      ::IsVisitable.log message, :debug
+      super message
+    end
+  end
+  
+  InvalidConfigValueError = ::Class.new(IsVisitableError)
+  InvalidVisitorError = ::Class.new(IsVisitableError)
+  InvalidVisitValueError = ::Class.new(IsVisitableError)
+  RecordError = ::Class.new(IsVisitableError)
+  
+  mattr_accessor :verbose
+  
+  @@verbose = ::Object.const_defined?(:RAILS_ENV) ? (::RAILS_ENV.to_sym == :development) : true
+  
+  def log(message, level = :info)
+    return unless @@verbose
+    level = :info if level.blank?
+    @@logger ||= ::Logger.new(::STDOUT)
+    @@logger.send(level.to_sym, message)
+  end
+  
+  def root
+    @@root ||= File.expand_path(File.join(File.dirname(__FILE__), *%w[..]))
+  end
+  
+end

data/lib/is_visitable/support.rb

@@ -0,0 +1,49 @@
+module IsVisitable
+  module Support
+    
+    extend self
+    
+    # Shortcut method for generating conditions hash for polymorphic belongs_to-associations.
+    #
+    def polymorphic_conditions_for(object_or_type, field, *match)
+      match = [:id, :type] if match.blank?
+      # Note: {} is equivalent to Hash.new which takes a block, so we must do: ({}) or (Hash.new)
+      returning({}) do |conditions|
+        conditions.merge!(:"#{field}_id" => object_or_type.id) if object_or_type.is_a?(::ActiveRecord::Base) && match.include?(:id)
+        
+        if match.include?(:type)
+          type = case object_or_type
+          when ::Class
+            object_or_type.name
+          when ::Symbol, ::String
+            object_or_type.to_s.singularize.classify
+          else # Object - or raise NameError as usual
+            object_or_type.class.name
+          end
+          
+          conditions.merge!(:"#{field}_type" => type)
+        end
+      end
+    end
+    
+    # Check if object is a valid activerecord object.
+    #
+    def is_active_record?(object)
+      object.present? && object.is_a?(::ActiveRecord::Base) # TODO: ::ActiveModel if Rails 3?
+    end
+    
+    # Check if input is a valid format of IP, i.e. "#.#.#.#". Note: Just basic validation.
+    #
+    def is_ip?(object)
+      (object =~ /^\d{1,3}.\d{1,3}.\d{1,3}.\d{1,3}$/) rescue false
+    end
+    
+    # Hash conditions to array conditions converter, 
+    # e.g. {:key => value} will be turned to: ['key = :key', {:key => value}]
+    #
+    def hash_conditions_as_array(conditions)
+      [conditions.keys.collect { |key| "#{key} = :#{key}" }.join(' AND '), conditions]
+    end
+    
+  end
+end

data/lib/is_visitable/visit.rb

@@ -0,0 +1,49 @@
+# coding: utf-8
+
+module IsVisitable
+  class Visit < ::ActiveRecord::Base
+    
+    ASSOCIATIVE_FIELDS = [
+        :visitable_id,
+        :vistable_type,
+        :visitor_id,
+        :visitor_type,
+        :ip
+      ].freeze
+    CONTENT_FIELDS = [
+        :visits
+      ].freeze
+      
+    # Associations.
+    belongs_to :visitable, :polymorphic => true
+    belongs_to :visitor, :polymorphic => true
+    
+    # Aliases.
+    alias :object :visitable
+    alias :owner  :visitor
+    
+    # Named scopes: Order.
+    named_scope :in_order,            :order => 'created_at ASC'
+    named_scope :most_recent,         :order => 'created_at DESC'
+    named_scope :lowest_visits,       :order => 'visits ASC'
+    named_scope :highest_visits,      :order => 'visits DESC'
+    
+    # Named scopes: Filters.
+    named_scope :limit,               lambda { |number_of_items|      {:limit => number_of_items} }
+    named_scope :since,               lambda { |created_at_datetime|  {:conditions => ['created_at >= ?', created_at_datetime]} }
+    named_scope :recent,              lambda { |arg|
+                                        if [::ActiveSupport::TimeWithZone, ::DateTime].any? { |c| c.is_a?(arg) }
+                                          {:conditions => ['created_at >= ?', arg]}
+                                        else
+                                          {:limit => arg.to_i}
+                                        end
+                                      }
+    named_scope :between_dates,       lambda { |from_date, to_date|     {:conditions => {:created_at => (from_date..to_date)}} }
+    named_scope :with_visits,         lambda { |visits_value_or_range|  {:conditions => {:visits => visits_value_or_range}} }
+    named_scope :of_visitable_type,   lambda { |type|       {:conditions => Support.polymorphic_conditions_for(type, :visitable, :type)} }
+    named_scope :by_visitor_type,     lambda { |type|       {:conditions => Support.polymorphic_conditions_for(type, :visitor, :type)} }
+    named_scope :on,                  lambda { |visitable|  {:conditions => Support.polymorphic_conditions_for(visitable, :visitable)} }
+    named_scope :by,                  lambda { |visitor|    {:conditions => Support.polymorphic_conditions_for(visitor, :visitor)} }
+    
+  end
+end

data/lib/is_visitable/visitable.rb

@@ -0,0 +1,354 @@
+# coding: utf-8
+require File.join(File.dirname(__FILE__), 'visit')
+require File.join(File.dirname(__FILE__), 'visitor')
+
+unless defined?(::Visit)
+  class Visit < ::IsVisitable::Visit
+  end
+end
+
+module IsVisitable #:nodoc:
+  module Visitable
+    
+    ASSOCIATION_CLASS = ::Visit
+    CACHABLE_FIELDS = [
+        :total_visits_count,
+        :unique_visits_count
+      ].freeze
+    DEFAULTS = {
+        :accept_ip => false
+      }.freeze
+    
+    def self.included(base) #:nodoc:
+      base.class_eval do
+        extend ClassMethods
+      end
+      
+      # Checks if this object visitable or not.
+      #
+      def visitable?; false; end
+      alias :is_visitable? :visitable?
+    end
+    
+    module ClassMethods
+      
+      # Make the model visitable, i.e. count/track visits by user/account of IP.
+      # 
+      # * Adds a <tt>has_many :visits</tt> association to the model for easy retrieval of the detailed visits.
+      # * Adds a <tt>has_many :visitors</tt> association to the object.
+      # * Adds a <tt>has_many :visits</tt> associations to the visitor class.
+      #
+      # === Options
+      # * <tt>:options[:visit_class]</tt> - class of the model used for the visits. Defaults to Visit. 
+      #   This class will be dynamically created if not already defined. If the class is predefined, 
+      #   it must have in it the following definitions:
+      #   <tt>belongs_to :visitable, :polymorphic => true</tt>
+      #   <tt>belongs_to :visitor, :class_name => 'User', :foreign_key => :visitor_id</tt> replace user with
+      #   the visitor class if needed.
+      # * <tt>:options[:visitor_class]</tt> - class of the model that creates the visit.
+      #   Defaults to User or Account - auto-detected. This class will NOT be created, so it must be defined in the app.
+      #   Use the IP address to prevent multiple visits from the same client.
+      #
+      def is_visitable(*args)
+        options = args.extract_options!
+        options.reverse_merge!(
+            :by         => nil,
+            :accept_ip  => options[:anonymous] || DEFAULTS[:accept_ip] # i.e. also accepts unique IPs as visitor
+          )
+          
+        # Assocations: Visit class (e.g. Visit).
+        options[:visit_class] = ASSOCIATION_CLASS
+        
+        # Had to do this here - not sure why. Subclassing Review be enough? =S
+        options[:visit_class].class_eval do
+          belongs_to :visitable, :polymorphic => true unless self.respond_to?(:visitable)
+          belongs_to :visitor,   :polymorphic => true unless self.respond_to?(:visitor)
+        end
+        
+        # Visitor class(es).
+        options[:visitor_classes] = [*options[:by]].collect do |class_name|
+          begin
+            class_name.to_s.singularize.classify.constantize
+          rescue NameError => e
+            raise InvalidVisitorError, "Visitor class #{class_name} not defined, needs to be defined. #{e}"
+          end
+        end
+        
+        # Assocations: Visitor class(es) (e.g. User, Account, ...).
+        options[:visitor_classes].each do |visitor_class|
+          if ::Object.const_defined?(visitor_class.name.to_sym)
+            visitor_class.class_eval do
+              has_many :visits,
+                :foreign_key => :visitor_id,
+                :class_name => options[:visit_class].name
+                
+              # Polymorphic has-many-through not supported (has_many :visitables, :through => :visits), so:
+              # TODO: Implement with :join
+              def vistables(*args)
+                query_options = args.extract_options!
+                query_options[:include] = [:visitable]
+                query_options.reverse_merge!(:conditions => Support.polymorphic_conditions_for(self, :visitor))
+                
+                ::Visit.find(:all, query_options).collect! { |visit| visit.visitable }
+              end
+            end
+          end
+        end
+        
+        # Assocations: Visitable class (e.g. Page).
+        self.class_eval do
+          has_many :visits, :as => :visitable, :dependent  => :delete_all
+          
+          # Polymorphic has-many-through not supported (has_many :visitors, :through => :visits), so:
+          # TODO: Implement with :join
+          def visitors(*args)
+            query_options = args.extract_options!
+            query_options[:include] = [:visitor]
+            query_options.reverse_merge!(:conditions => Support.polymorphic_conditions_for(self, :visitable))
+              
+            ::Visit.find(:all, query_options).collect! { |visit| visit.visitor }
+          end
+          
+          # Hooks.
+          before_create :init_visitable_caching_fields
+          
+          include ::IsVisitable::Visitable::InstanceMethods
+          extend  ::IsVisitable::Visitable::Finders
+        end
+        
+        # Save the initialized options for this class.
+        self.write_inheritable_attribute :is_visitable_options, options.slice
+        self.class_inheritable_reader :is_visitable_options
+      end
+      
+      # Does this class count/track visits?
+      #
+      def visitable?
+        @@visitable ||= self.respond_do?(:is_visitable_options, true)
+      end
+      alias :is_visitable? :visitable?
+      
+      protected
+        
+        # Check if the requested visitor object is a valid visitor.
+        #
+        def validate_visitor(identifiers)
+          raise InvalidVisitorError, "Argument can't be nil: no visitor object or IP provided." if identifiers.blank?
+          visitor = identifiers[:visitor] || identifiers[:user] || identifiers[:account] || identifiers[:ip]
+          is_ip = Support.is_ip?(visitor)
+          visitor = visitor.to_s.strip if is_ip
+          unless Support.is_active_record?(visitor) || is_ip
+            raise InvalidVisitorError, "Visitor is of wrong type: #{visitor.inspect}."
+          end
+          #raise InvalidVisitorError, "Visit based on IP is disabled." if is_ip && !self.is_visitable_options[:accept_ip]
+          visitor
+        end
+        
+    end
+    
+    module InstanceMethods
+      
+      # Does this object count/track visits?
+      #
+      def visitable?
+        self.class.visitable?
+      end
+      alias :is_visitable? :visitable?
+      
+      # first_visit = created_at.
+      #
+      def first_visited_at
+        self.created_at if self.respond_to?(:created_at)
+      end
+      
+      # last_visit = updated_at.
+      #
+      def last_visited_at
+        self.updated_at if self.respond_to?(:updated_at)
+      end
+      
+      # Get the unique number of visits for this object based on the visits field, 
+      # or with a SQL query if the visited objects doesn't have the visits field
+      #
+      def unique_visits(recalculate = false)
+        if !recalculate && self.visitable_caching_fields?(:unique_visits)
+          self.unique_visits || 0
+        else
+          ::Visit.count(:conditions => self.visitable_conditions)
+        end
+      end
+      alias :number_of_visitors :unique_visits
+      
+      # Get the total number of visits for this object.
+      #
+      def total_visits(recalculate = false)
+        if !recalculate && self.visitable_caching_fields?(:total_visits)
+          self.total_visits || 0
+        else
+          ::Visit.sum(:visits, :conditions => self.visitable_conditions)
+        end
+      end
+      alias :number_of_visits :total_visits
+      
+      # Is this object visited by anyone?
+      #
+      def visited?
+        self.unique_visits > 0
+      end
+      alias :is_visited? :visited?
+      
+      # Check if an item was already visited by the given visitor or ip.
+      #
+      # === Identifiers hash:
+      # * <tt>:ip</tt> - identify with IP
+      # * <tt>:visitor</tt> - identify with a visitor-model (e.g. User, ...)
+      # * <tt>:user</tt> - (same as above)
+      # * <tt>:account</tt> - (same as above)
+      #
+      def visited_by?(identifiers)
+        self.visits.exists?(:conditions => visitor_conditions(identifiers))
+      end
+      alias :is_visited_by? :visited_by?
+      
+      def visit_by(identifiers)
+        self.visits.find(:first, :conditions => visitor_conditions(identifiers))
+      end
+      
+      # Delete all tracked visits for this visitable object.
+      #
+      def reset_visits!
+        self.visits.delete_all
+        self.total_visits = 0 if self.visitable_caching_fields?(:total_visits)
+        self.unique_visits = 0 if self.visitable_caching_fields?(:unique_visits)
+      end
+      
+      # View the object with and identifier (user or ip) - create new if new visitor.
+      #
+      # === Identifiers hash:
+      # * <tt>:visitor/:user/:account</tt> - identify with a visitor-model or IP (e.g. User, Account, ..., "128.0.0.1")
+      # * <tt>:*</tt> - Any custom visit field, e.g. :visitor_type => "duck" (optional)
+      #
+      def visit!(identifiers_and_options)
+        begin
+          visitor = self.validate_visitor(identifiers_and_options)
+          visit = self.visit_by(identifiers_and_options)
+          
+          # Except for the reserved fields, any Visit-fields should be be able to update.
+          visit_values = identifiers_and_options.except(*::IsVisitable::Visit::ASSOCIATIVE_FIELDS)
+          
+          unless visit.present?
+            # An un-existing visitor of this visitable object => Create a new visit.
+            visit = ::Visit.new do |v|
+              v.visitable_id    = self.id
+              v.visitable_type  = self.class.name
+              
+              if Support.is_active_record?(visitor)
+                v.visitor_id   = visitor.id
+                v.visitor_type = visitor.class.name
+              else
+                v.ip = visitor
+              end
+              
+              v.visits = 0
+            end
+            self.visits << visit
+          else
+            # An existing visitor of this visitable object => Update the existing visit.
+          end
+          is_new_record = visit.new_record?
+          
+          # Update non-association attributes and any custom fields.
+          visit.attributes = visit_values.slice(*visit.attribute_names.collect { |an| an.to_sym })
+          
+          visit.visits += 1
+          visit.save && self.save_without_validation
+          
+          if self.visitable_caching_fields?(:total_visits)
+            begin
+              self.cached_total_visits += 1 if is_new_record
+            rescue
+              self.cached_total_visits = self.total_visits(true)
+            end
+          end
+          
+          if self.visitable_caching_fields?(:unique_visits)
+            begin
+              self.cached_unique_visits += 1 if is_new_record
+            rescue
+              self.cached_unique_visits = self.unique_visits(true)
+            end
+          end
+          
+          visit
+        rescue InvalidVisitorError => e
+          raise e
+        rescue Exception => e
+          raise RecordError, "Could not create/update visit #{visit.inspect} by #{visitor.inspect}: #{e}"
+        end
+      end
+      
+      def unvisit!
+        raise "Not implemented"
+      end
+      
+      protected
+        
+        # Cachable fields for this visitable class.
+        #
+        def visitable_caching_fields
+          CACHABLE_FIELDS
+        end
+        
+        # Checks if there are any cached fields for this visitable/trackable class.
+        #
+        def visitable_caching_fields?(*fields)
+          fields = CACHABLE_FIELDS if fields.blank?
+          fields.all? { |field| self.attributes.has_key?(:"cached_#{field}") }
+        end
+        alias :has_visitable_caching_fields? :visitable_caching_fields?
+        
+        # Initialize any cached fields.
+        #
+        def init_visitable_caching_fields
+          self.cached_total_visits = 0 if self.visitable_caching_fields?(:total_visits)
+          self.cached_unique_visits = 0 if self.visitable_caching_fields?(:unique_visits)
+        end
+        
+        def visitable_conditions(as_array = false)
+          conditions = {:visitable_id => self.id, :visitable_type => self.class.name}
+          as_array ? Support.hash_conditions_as_array(conditions) : conditions
+        end
+        
+        # Generate query conditions.
+        #
+        def visitor_conditions(identifiers, as_array = false)
+          visitor = self.validate_visitor(identifiers)
+          if Support.is_active_record?(visitor)
+            conditions = {:visitor_id => visitor.id, :visitor_type => visitor.class.name}
+          else
+            conditions = {:ip => visitor.to_s}
+          end
+          as_array ? Support.hash_conditions_as_array(conditions) : conditions
+        end
+        
+        def validate_visitor(identifiers)
+          self.class.send(:validate_visitor, identifiers)
+        end
+        
+    end
+    
+    module Finders
+      
+      # TODO: Finders
+      #
+      # * users that visited this, also visited [...]
+      
+    end
+    
+  end
+end
+
+# Extend ActiveRecord.
+::ActiveRecord::Base.class_eval do
+  include ::IsVisitable::Visitable
+end

data/lib/is_visitable/visitor.rb

@@ -0,0 +1,7 @@
+# coding: utf-8
+
+module IsVisitable #:nodoc:
+  module Visitor
+    
+  end
+end

data/test/is_visitable_test.rb

@@ -0,0 +1,109 @@
+# coding: utf-8
+require 'test_helper'
+
+class IsVisitableTest < Test::Unit::TestCase
+  
+  def setup
+    @visit = ::Visit.new
+    @user_1 = ::User.create
+    @user_2 = ::User.create
+    @tracked_post = ::TrackedPost.create
+    @tracked_post_with_ip = ::TrackedPostWithIp.create
+  end
+  
+  context "initialization" do
+    
+    should "extend ActiveRecord::Base" do
+      assert_respond_to ::ActiveRecord::Base, :is_visitable
+    end
+    
+    should "declare is_visitable instance methods for visitable objects" do
+      methods = [
+          :first_visited_at,
+          :first_visited_at,
+          :last_visited_at,
+          :unique_visits,
+          :total_visits,
+          :visited_by?,
+          :reset_visits!,
+          :visitable?,
+          :visit!
+        ]
+        
+      assert methods.all? { |m| @tracked_post.respond_to?(m) }
+      # assert !methods.any? { |m| @tracked_post.respond_to?(m) }
+    end
+    
+    # Don't work for some reason... =S
+    # should "be enabled only for specified models" do
+    #   assert @tracked_post.visitable?
+    #   assert_not @untracked_post.visitable?
+    # end
+    
+  end
+  
+  context "visitable" do
+    should "have zero visits from the beginning" do
+      assert_equal(@tracked_post_with_ip.visits.size, 0)
+    end
+    
+    should "count visits based on IP correctly" do
+      number_of_unique_visits = @tracked_post_with_ip.unique_visits
+      number_of_total_visits = @tracked_post_with_ip.total_visits
+      
+      @tracked_post_with_ip.visit!(:visitor => '128.0.0.0')
+      @tracked_post_with_ip.visit!(:visitor => '128.0.0.1')
+      @tracked_post_with_ip.visit!(:visitor => '128.0.0.1')
+      
+      assert_equal number_of_unique_visits + 2, @tracked_post_with_ip.unique_visits
+      assert_equal number_of_total_visits + 3, @tracked_post_with_ip.total_visits
+    end
+    
+    should "count visits based on visitor object (user/account) correctly" do
+      number_of_unique_visits = @tracked_post_with_ip.unique_visits
+      number_of_total_visits = @tracked_post_with_ip.total_visits
+      
+      @tracked_post_with_ip.visit!(:visitor => @user_1)
+      @tracked_post_with_ip.visit!(:visitor => @user_2)
+      @tracked_post_with_ip.visit!(:visitor => @user_2)
+      
+      assert_equal number_of_unique_visits + 2, @tracked_post_with_ip.unique_visits
+      assert_equal number_of_total_visits + 3, @tracked_post_with_ip.total_visits
+    end
+    
+    should "count visits based on both IP and visitor object (user/account) correctly" do
+      number_of_unique_visits = @tracked_post_with_ip.unique_visits
+      number_of_total_visits = @tracked_post_with_ip.total_visits
+      
+      @tracked_post_with_ip.visit!(:visitor => '128.0.0.0')
+      @tracked_post_with_ip.visit!(:visitor => '128.0.0.0')
+      @tracked_post_with_ip.visit!(:visitor => @user_1)
+      @tracked_post_with_ip.visit!(:visitor => @user_2)
+      @tracked_post_with_ip.visit!(:visitor => @user_2)
+      
+      assert_equal number_of_unique_visits + 3, @tracked_post_with_ip.unique_visits
+      assert_equal number_of_total_visits + 5, @tracked_post_with_ip.total_visits
+    end
+    
+    should "delete all visits upon reset" do
+      @tracked_post_with_ip.visit!(:visitor => '128.0.0.0')
+      @tracked_post_with_ip.reset_visits!
+      
+      assert_equal 0, @tracked_post_with_ip.unique_visits
+      assert_equal 0, @tracked_post_with_ip.total_visits
+    end
+  end
+  
+  context "visitor" do
+    
+    # Nothing
+    
+  end
+  
+  context "visit" do
+    
+    # Nothing
+    
+  end
+  
+end

data/test/test_helper.rb

@@ -0,0 +1,57 @@
+# coding: utf-8
+require 'rubygems'
+
+def smart_require(lib_name, gem_name, gem_version = '>= 0.0.0')
+  begin
+    require lib_name if lib_name
+  rescue LoadError
+    if gem_name
+      gem gem_name, gem_version
+      require lib_name if lib_name
+    end
+  end
+end
+
+smart_require 'test/unit', 'test-unit', '= 1.2.3'
+smart_require 'shoulda', 'thoughtbot-shoulda', '>= 2.10.0'
+smart_require 'redgreen', 'redgreen', '>= 0.10.4'
+smart_require 'sqlite3', 'sqlite3-ruby', '>= 1.2.0'
+smart_require 'acts_as_fu', 'nakajima-acts_as_fu', '>= 0.0.5'
+
+require 'test_helper'
+
+require 'is_visitable'
+
+build_model :visits do
+  references  :visitable,     :polymorphic => true
+  
+  references  :visitor,       :polymorphic => true
+  string      :ip,            :limit => 24
+  
+  integer     :visits,        :default => 1
+  
+  timestamps
+end
+
+build_model :guests
+build_model :users
+build_model :accounts
+build_model :posts
+
+build_model :untracked_posts do
+end
+
+build_model :tracked_posts do
+  is_visitable :by => :users, :accept_ip => false
+end
+
+build_model :tracked_post_with_ips do
+  is_visitable :by => [:accounts, :users], :accept_ip => true
+end
+
+build_model :cached_tracked_posts do
+  integer :cached_unique_visits
+  integer :cached_total_visits
+  
+  is_visitable :by => :users, :accept_ip => true
+end

metadata

@@ -0,0 +1,147 @@
+--- !ruby/object:Gem::Specification 
+name: is_visitable
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Jonas Grimfelt
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-11-19 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.2.3
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.2.3
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: test-unit
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        version: 1.2.3
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: shoulda
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 2.10.0
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: redgreen
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.10.4
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: sqlite3-ruby
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.2.0
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: acts_as_fu
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.0.5
+    version: 
+description: "Rails: Track unique and total visits/viewings of an ActiveRecord resource based on user/account or IP."
+email: grimen@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- MIT-LICENSE
+- README.textile
+- Rakefile
+- generators/is_visitable_migration/is_visitable_migration_generator.rb
+- generators/is_visitable_migration/templates/migration.rb
+- lib/is_visitable.rb
+- lib/is_visitable/support.rb
+- lib/is_visitable/visit.rb
+- lib/is_visitable/visitable.rb
+- lib/is_visitable/visitor.rb
+- test/is_visitable_test.rb
+- test/test_helper.rb
+files: 
+- MIT-LICENSE
+- README.textile
+- Rakefile
+- generators/is_visitable_migration/is_visitable_migration_generator.rb
+- generators/is_visitable_migration/templates/migration.rb
+- lib/is_visitable.rb
+- lib/is_visitable/support.rb
+- lib/is_visitable/visit.rb
+- lib/is_visitable/visitable.rb
+- lib/is_visitable/visitor.rb
+- test/is_visitable_test.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://github.com/grimen/is_visitable
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: "Rails: Track unique and total visits/viewings of an ActiveRecord resource based on user/account or IP."
+test_files: 
+- test/is_visitable_test.rb
+- test/test_helper.rb