publishable 0.3.0 → 1.0.0

data/.document

@@ -1,5 +1,6 @@
 README.rdoc
 lib/**/*.rb
 bin/*
+- 
 features/**/*.feature
-LICENSE
+LICENSE.txt

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format documentation

data/Gemfile

@@ -0,0 +1,43 @@
+source "http://rubygems.org"
+
+# Add dependencies required to use your gem here.
+# Example:
+#   gem "activesupport", ">= 2.3.5"
+
+#==============================================================================
+# Gems used in both development and testing environments.
+#==============================================================================
+group :development, :test do
+
+  # Use YARD documentation format
+  gem "yard", "~> 0.7"
+  gem "rdoc", "~> 3.12"
+  gem "bundler", "~> 1.0"
+
+  # Use Jeweler to build our gem
+  gem "jeweler", "~> 1.8.4"
+
+  # RSpec for our testing framework
+  gem "rspec", "~> 2.8.0"
+end
+
+#==============================================================================
+# Gems just needed for testing.
+#==============================================================================
+group :test do
+
+  # Faker generates names, email addresses, and other placeholders for factories
+  gem 'ffaker'
+
+  # For testing ActiveRecord extensions
+  gem 'acts_as_fu'
+
+  # Test time-dependent functionality
+  gem 'timecop'
+
+  if RUBY_VERSION > '1.9'
+    gem "simplecov", :require => false
+  else
+    gem "rcov", ">= 0"
+  end
+end

data/Gemfile.lock

@@ -0,0 +1,60 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activemodel (3.2.12)
+      activesupport (= 3.2.12)
+      builder (~> 3.0.0)
+    activerecord (3.2.12)
+      activemodel (= 3.2.12)
+      activesupport (= 3.2.12)
+      arel (~> 3.0.2)
+      tzinfo (~> 0.3.29)
+    activesupport (3.2.12)
+      i18n (~> 0.6)
+      multi_json (~> 1.0)
+    acts_as_fu (0.0.8)
+      activerecord
+      sqlite3
+    arel (3.0.2)
+    builder (3.0.4)
+    diff-lcs (1.1.3)
+    ffaker (1.15.0)
+    git (1.2.5)
+    i18n (0.6.1)
+    jeweler (1.8.4)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+      rdoc
+    json (1.7.7)
+    multi_json (1.6.1)
+    rake (10.0.3)
+    rcov (1.0.0)
+    rdoc (3.12.1)
+      json (~> 1.4)
+    rspec (2.8.0)
+      rspec-core (~> 2.8.0)
+      rspec-expectations (~> 2.8.0)
+      rspec-mocks (~> 2.8.0)
+    rspec-core (2.8.0)
+    rspec-expectations (2.8.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.8.0)
+    sqlite3 (1.3.7)
+    timecop (0.5.9.2)
+    tzinfo (0.3.35)
+    yard (0.8.4.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  acts_as_fu
+  bundler (~> 1.0)
+  ffaker
+  jeweler (~> 1.8.4)
+  rcov
+  rdoc (~> 3.12)
+  rspec (~> 2.8.0)
+  timecop
+  yard (~> 0.7)

data/{LICENSE → LICENSE.txt}

@@ -1,4 +1,5 @@
 Copyright (c) 2010 Martin Linkhorst
+Copyright (c) 2013 тιηуηυмвєяѕ
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.rdoc

@@ -0,0 +1,87 @@
+= publishable
+
+*Publishable* allows a given Boolean, Date, or DateTime column to indicate whether an ActiveRecord
+model object is "published".  This can be used, for example, to schedule a news post to be published
+at some later date on a website, or to hide work-in-progress content until it is ready to be released
+to the public.
+
+Methods are provided to publish and unpublish the model object, and scopes are added for filtering
+your records.
+
+* When publishing via a Boolean column, the value of the column determines whether (+true+) or not (+false+)
+  the model object is published.
+* When publishing via a Date or DateTime column, the value of the published column must be before "now"
+  (or "today" for Date columns) for the object to be published.  Date or DateTime publishables also have
+  scopes for returning recent or upcoming records, i.e. records that have already been published, or records
+  that will be published in the future.
+
+== Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'publishable'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install publishable
+
+== Setup
+
+1. Create the publishable column via a migration:
+
+    rails generate migration add_published_to_post published:date
+    rails generate migration add_published_to_story published:datetime
+    rails generate migration add_released_to_album released:boolean
+
+2. Declare that your models are publishable:
+
+    class Post < ActiveRecord::Base
+      publishable
+    end
+
+    class Story < ActiveRecord::Base
+      publishable
+    end
+
+    class Album < ActiveRecord::Base
+      publishable :on => :released
+    end
+
+The column name used by *publishable* can be specified via the +:on+ option. The default used (if +:on+
+is not specified) is +:published+.
+
+== Usage
+
+    published_posts = Post.recent(5) # Returns the five most recently-published Posts, in descending order by publish-date
+
+    album = Album.new
+    album.published?  # false - by default, records are not published
+    album.publish     # sets the 'released' column to true, but does not save it back to the database
+    album.publish!    # publishes AND saves the record to the database
+    album.published?  # true
+    album.unpublish!  # sets the 'released' column back to false and saves the record
+
+    story = Story.new
+    story.publish!(2.hours.from_now)    # Sets the story to go live in two hours
+    story.unpublish!                    # Sets the 'published' column to nil
+    upcoming_stories = Story.upcoming   # Get all stories that will be published in the future, in ascending order by publish-date
+
+== Contributing to publishable
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
+* Fork the project.
+* Start a feature/bugfix branch.
+* Commit and push until you are happy with your contribution.
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+== Copyright
+
+Copyright (c) 2010 Martin Linkhorst, released under the MIT license.
+Copyright (c) 2013 тιηуηυмвєяѕ. See LICENSE.txt for further details.
+

data/Rakefile

@@ -1,46 +1,48 @@
+# encoding: utf-8
+
 require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts 'Run `bundle install` to install missing gems'
+  exit e.status_code
+end
 require 'rake'
 
 begin
   require 'jeweler'
+  require './lib/publishable/version.rb'
   Jeweler::Tasks.new do |gem|
-    gem.name = "publishable"
-    gem.summary = "Adds publishing functionality to your active record model"
-    gem.description = "Provides methods to publish and unpublish your active record models based on a datetime. Also adds named scopes to nicely filter your records. Does not touch any controller or views."
-    gem.email = "m.linkhorst@googlemail.com"
-    gem.homepage = "http://github.com/linki/publishable"
-    gem.authors = ["Martin Linkhorst"]
-    gem.add_development_dependency "rspec", ">= 1.2.9"
-    gem.files.include 'lib/**/*.rb'
-    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+    gem.name = 'publishable'
+    gem.license = 'MIT'
+    gem.summary = 'Adds publishing functionality to your active record model'
+    gem.description = 'Provides methods to publish and unpublish your active record models based on a boolean flag, a date, or a datetime. Also adds named scopes to nicely filter your records. Does not touch any controller or views.'
+    gem.email = ['m.linkhorst@googlemail.com', 'info@tinynumbers.com']
+    gem.homepage = 'http://github.com/linki/publishable'
+    gem.authors = ['Martin Linkhorst', 'тιηуηυмвєяѕ']
+    gem.version = "#{Publishable::VERSION}"
+    # dependencies defined in Gemfile
+    # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
   end
-  Jeweler::GemcutterTasks.new
+  Jeweler::RubygemsDotOrgTasks.new
 rescue LoadError
-  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+  puts 'Jeweler (or a dependency) not available. Install it with: gem install jeweler'
 end
 
-require 'spec/rake/spectask'
-Spec::Rake::SpecTask.new(:spec) do |spec|
-  spec.libs << 'lib' << 'spec'
-  spec.spec_files = FileList['spec/**/*_spec.rb']
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
 end
 
-Spec::Rake::SpecTask.new(:rcov) do |spec|
-  spec.libs << 'lib' << 'spec'
+RSpec::Core::RakeTask.new(:rcov) do |spec|
   spec.pattern = 'spec/**/*_spec.rb'
   spec.rcov = true
 end
 
-task :spec => :check_dependencies
-
 task :default => :spec
 
-require 'rake/rdoctask'
-Rake::RDocTask.new do |rdoc|
-  version = File.exist?('VERSION') ? File.read('VERSION') : ""
-
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "publishable #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
+require 'yard'
+YARD::Rake::YardocTask.new

data/lib/publishable.rb

@@ -1,37 +1,269 @@
+# encoding: utf-8
+
 require 'publishable/railtie' if defined?(Rails)
 
+# Allows a given boolean, date, or datetime column to indicate whether a model object is published.
+# Boolean published column just is an on/off flag.
+# Date/datetime column requires value of published column to be before "now" for the object to be published.
+# Specify the column name via the :on option (defaults to :published) and make sure to create the column
+# in your migrations.
+#
+# Provides scopes for finding published and unpublished items, and (for date/datetime published columns) for returning
+# recent or upcoming items.
+#
+# @author Martin Linkhorst <m.linkhorst@googlemail.com>
+# @author David Daniell / тιηуηυмвєяѕ <info@tinynumbers.com>
 module Publishable
+
+  # Add our features to the base class.
+  # @see ClassMethods#publishable
+  # @param [Object] base
   def self.extended(base)
     base.extend ClassMethods
   end
-  
+
+  # Define scopes and methods for querying and manipulating Publishables.
   module ClassMethods
+
+    # DSL method to link this behavior into your model.  In your ActiveRecord model class, add +publishable+ to include
+    # the scopes and methods for publishable objects.
+    #
+    # @example
+    #   class Post < ActiveRecord::Base
+    #     publishable
+    #   end
+    #
+    # @param [Hash] options The publishable options.
+    # @option options [String, Symbol] :on (:publishable) The name of the publishable column on the model.
     def publishable(options = {})
-      column_name = (options[:on] || :published_at).to_s
+      return unless table_exists?
+      column_name = (options[:on] || :published).to_sym
+      unless self.columns_hash[column_name.to_s].present?
+        raise ActiveRecord::ConfigurationError, "No '#{column_name}'column available for Publishable column on model #{self.name}"
+      end
+      column_type = self.columns_hash[column_name.to_s].type
 
       if respond_to?(:scope)
-        scope :published, lambda { |time = Time.now|
-          where("#{column_name} IS NOT NULL AND #{column_name} <= ?", time.utc)
-        }
 
-        scope :unpublished, lambda { |time = Time.now|
-          where("#{column_name} IS NULL OR #{column_name} > ?", time.utc)
-        }
-      end
-      
-      class_eval <<-EVIL, __FILE__, __LINE__ + 1
-        def published?(time = Time.now)
-          #{column_name} ? #{column_name} <= time : false
+        # define published/unpublished scope
+        case column_type
+          when :date
+            scope :published, lambda { |*args|
+              on_date = args[0] || Date.current
+              where(arel_table[column_name].not_eq(nil)).where(arel_table[column_name].lteq(on_date))
+            }
+
+            scope :unpublished, lambda { |*args|
+              on_date = args[0] || Date.current
+              where(arel_table[column_name].not_eq(nil)).where(arel_table[column_name].gt(on_date))
+            }
+
+          when :datetime
+            scope :published, lambda { |*args|
+              at_time = args[0] || Time.now
+              where(arel_table[column_name].not_eq(nil)).where(arel_table[column_name].lteq(at_time.utc))
+            }
+
+            scope :unpublished, lambda { |*args|
+              at_time = args[0] || Time.now
+              where(arel_table[column_name].not_eq(nil)).where(arel_table[column_name].gt(at_time.utc))
+            }
+
+          when :boolean
+            scope :published, lambda {
+              where(column_name => true)
+            }
+
+            scope :unpublished, lambda {
+              where(column_name => false)
+            }
+
+          else
+            raise ActiveRecord::ConfigurationError, "Invalid column_type #{column_type} for Publishable column on model #{self.name}"
         end
 
-        def publish(time = Time.now)
-          self.#{column_name} = time unless published?(time)
+        # define recent/upcoming scopes
+        if [:date, :datetime].include? column_type
+          scope :recent, lambda { |*args|
+            how_many = args[0] || nil
+            col_name = arel_table[column_name].name
+            published.limit(how_many).order("#{col_name} DESC")
+          }
+          scope :upcoming, lambda { |*args|
+            how_many = args[0] || nil
+            col_name = arel_table[column_name].name
+            unpublished.limit(how_many).order("#{col_name} ASC")
+          }
         end
 
-        def publish!(time = Time.now)
-          publish(time) && (!respond_to?(:save) || save)
-        end        
-      EVIL
+      end
+
+      case column_type
+        when :datetime
+          class_eval <<-EVIL, __FILE__, __LINE__ + 1
+            def published?(_when = Time.now)
+              #{column_name} ? #{column_name} <= _when : false
+            end
+
+            def unpublished?(_when = Time.now)
+              !published?(_when)
+            end
+
+            def publish(_when = Time.now)
+              self.#{column_name} = _when unless published?(_when)
+            end
+
+            def publish!(_when = Time.now)
+              publish(_when) && (!respond_to?(:save) || save)
+            end
+
+            def unpublish()
+              self.#{column_name} = null
+            end
+
+            def unpublish!()
+              unpublish() && (!respond_to?(:save) || save)
+            end
+          EVIL
+
+        when :date
+          class_eval <<-EVIL, __FILE__, __LINE__ + 1
+            def published?(_when = Date.current)
+              #{column_name} ? #{column_name} <= _when : false
+            end
+
+            def unpublished?(_when = Date.current)
+              !published?(_when)
+            end
+
+            def publish(_when = Date.current)
+              self.#{column_name} = _when unless published?(_when)
+            end
+
+            def publish!(_when = Date.current)
+              publish(_when) && (!respond_to?(:save) || save)
+            end
+
+            def unpublish()
+              self.#{column_name} = null
+            end
+
+            def unpublish!()
+              unpublish() && (!respond_to?(:save) || save)
+            end
+          EVIL
+
+        when :boolean
+          class_eval <<-EVIL, __FILE__, __LINE__ + 1
+            def published?()
+              #{column_name}
+            end
+
+            def unpublished?()
+              !published?()
+            end
+
+            def publish()
+              self.#{column_name} = true
+            end
+
+            def publish!()
+              publish()
+              save if respond_to?(:save)
+            end
+
+            def unpublish()
+              self.#{column_name} = false
+            end
+
+            def unpublish!()
+              unpublish()
+              save if respond_to?(:save)
+            end
+          EVIL
+
+        else
+          raise ActiveRecord::ConfigurationError, "Invalid column_type #{column_type} for Publishable column on model #{self.name}"
+      end
+
     end
+
+    # @!group Query scopes added to publishable models
+
+    # @!method published
+    #   Query scope added to publishables that can be used to find published records. For Date/DateTime publishables,
+    #   you can pass a specific date on which the results should be published.
+    #   @example Find only records that are currently published
+    #     published_posts = Post.published
+    #   @example Find only records that will be published in two days
+    #     future_posts = Post.published(Date.current + 2.days)
+    #   @param [Date, Time, nil] when Specify a date/time for Date/DateTime publishables - defaults to the current date/time
+    #   @!scope class
+
+    # @!method unpublished
+    #   Query scope added to publishables that can be used find records which are not published. For Date/DateTime
+    #   publishables, you can pass a specific date on which the results should not have been published.
+    #   @example Find only records that are not currently published
+    #     unpublished_posts = Post.unpublished
+    #   @param [Date, Time, nil] when Specify a date/time for Date/DateTime publishables - defaults to the current date/time
+    #   @!scope class
+
+    # @!method recent
+    #   Query scope added to publishables that can be used to lookup records which are currently published. The results
+    #   are returned in descending order based on the published date/time.
+    #   @example Get the 10 most recently-published records
+    #     recent_posts = Post.recent(10)
+    #   @param [Integer, nil] how_many Specify how many records to return
+    #   @!scope class
+
+    # @!method upcoming
+    #   Query scope added to publishables that can be used to lookup records which are not currently published. The
+    #   results are returned in ascending order based on the published date/time.
+    #   @example Get all posts that will be published in the future
+    #     upcoming_posts = Post.upcoming
+    #   @param [Integer, nil] how_many Specify how many records to return
+    #   @!scope class
+
+    # @!endgroup
+
+    # @!group Instance methods added to publishable models
+
+    # @!method published?
+    #   Is this object published?
+    #   @param [Date, Time, nil] when For Date/DateTime publishables, a date/time can be passed to determine if the
+    #     object was / will be published on the given date.
+    #   @return [Boolean] true if published, false if not published.
+    #   @!scope instance
+
+    # @!method unpublished?
+    #   Is this object not published?
+    #   @param [Date, Time, nil] when For Date/DateTime publishables, a date/time can be passed to determine if the
+    #     object was not / will not be published on the given date.
+    #   @return [Boolean] false if published, true if not published.
+    #   @!scope instance
+
+    # @!method publish
+    #   Publish this object.  For a Boolean publish field, the field is set to true; for a Date/DateTime field, the
+    #   field is set to the given Date/Time or to the current date/time.
+    #   @param [Date, Time, nil] when For Date/DateTime publishables, a date/time can be passed to specify when the
+    #     record will be published. Defaults to +Date.current+ or +Time.now+.
+    #   @!scope instance
+
+    # @!method publish!
+    #   Publish this object, then immediately save it to the database.
+    #   @param [Date, Time, nil] when
+    #   @!scope instance
+
+    # @!method unpublish
+    #   Un-publish this object, i.e. set it to not be published.  For a Boolean publish field, the field is set to
+    #   false; for a Date/DateTime field, the field is set to null.
+    #   @!scope instance
+
+    # @!method unpublish!
+    #   Un-publish this object, then immediately save it to the database.
+    #   @!scope instance
+
+    # @!endgroup
+
   end
-end
+end