attr_publish 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 987c18de5f5bed476683cae2628e4742c069e130
+  data.tar.gz: 87a8c39cedb1bbc000ccc711f044fe5d2d8d1c54
+SHA512:
+  metadata.gz: c941855591f4af93280483bf83f97f2f066b5b6819e1fd0fb86b158b1870011b4d4c17bb21ad72a100345dbb513487141ccee1bbc1de8137b40efbd2f1c6b232
+  data.tar.gz: a2df86692d6996fd2d8ed6d040fc34729a721b82615cd953f5cde710b5e5e05ce23e08db15e1b4dbc8a21f4d25b59ac376ca1388c3acf585cf5142504ed68d88

data/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Change Log
+
+## v1.0.0
+- Initial release.

data/README.md

@@ -0,0 +1,136 @@
+# AttrPublish
+
+Provides scopes for finding published and unpublished items, and (for date/datetime published columns) for returning recent or upcoming items. Also provides a set of convenient instance methods for publishing and unpublishing a record.
+
+Allows a given boolean, date, or datetime column to indicate whether a model object is published. A boolean published column is just an on/off flag. A date/datetime column requires the value of published column to be before "current" for the object to be published.
+
+AttrPublish is extracted from the Brightcommerce platform and is in use by several projects.
+
+## Installation
+
+To install add the line to your Gemfile:
+
+``` ruby
+gem 'attr_publish'
+```
+
+And `bundle install`.
+
+## How To Use
+
+To add AttrPublish to a model, include the concern:
+
+``` ruby
+class Post < ActiveRecord::Base
+  include AttrPublish
+
+  attr_publish
+end
+```
+
+This will automatically default to look for a column named ':published'.
+
+To autoload AttrPublish for all models, add the following to an initializer:
+
+``` ruby
+require 'attr_publish/active_record'
+```
+
+You then don't need to `include AttrPublish` in any model, but you still need to add the `attr_publish` class method.
+
+### Class Methods
+
+AttrPublish adds the following scopes to your model (using the previous example model `Post`):
+
+``` ruby
+Post.published
+Post.unpublished
+```
+
+By default these scopes uses the current date or current time to limit the query. However, you can pass any date or datetime to these scopes to limit the records it returns:
+
+``` ruby
+Post.published(DateTime.yesterday)
+```
+
+If the published column is of type `:date` or `:datetime` the following additional scopes are provided:
+
+``` ruby
+Post.recent
+Post.upcoming
+```
+
+By default these scopes return all matching records. You can limit the number of records returned by passing a number to the scope:
+
+``` ruby
+Post.recent(10) # returns the 10 most recent published posts (ordered by date or datetime)
+Post.upcoming(3) # returns 3 next unpublished posts (ordered by date or datetime)
+```
+
+### Instance Methods
+
+AttrPublish automatically provides the following class instance methods:
+
+- `published?`
+- `unpublished?`
+- `publish`
+- `publish!`
+- `unpublish`
+- `unpublish!`
+
+If the column type is specified as a Date or Time, you can pass a datetime parameter to the `publish` and `publish!` instance methods. `publish` and `unpublish` methods will change the instance's publish value, but won't save the object. Using the `publish!` and `unpublish!` bang methods will call save (commit) after changing the value.
+
+### Setup
+
+Add the model attribute you want to use with AttrPublish in your migration:
+
+``` ruby
+class CreatePosts < ActiveRecord::Migration[5.2]
+  def change
+    create_table :posts do |table|
+      table.column :published, :datetime
+      table.timestamps
+    end
+  end
+end
+```
+
+You can change the column used by AttrPublish by adding the column name to the `attr_publish` class method:
+
+``` ruby
+class Post < ApplicationRecord
+  include AttrPublish
+
+  attr_publish :published_on
+end
+```
+
+## Dependencies
+
+AttrPublish gem has the following runtime dependencies:
+- activerecord >= 5.1.4
+- activesupport >= 5.1.4
+
+## Compatibility
+
+Tested with MRI 2.4.2 against Rails 5.2.2.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## Credit
+
+This gem was written and is maintained by [Jurgen Jocubeit](https://github.com/JurgenJocubeit), CEO and President Brightcommerce, Inc.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+
+## Copyright
+
+Copyright 2018 Brightcommerce, Inc.

data/lib/attr_publish.rb

@@ -0,0 +1,3 @@
+require 'active_record'
+require 'attr_publish/attr_publish'
+require 'attr_publish/version'

data/lib/attr_publish/active_record.rb

@@ -0,0 +1 @@
+ActiveRecord::Base.send :include, AttrPublish

data/lib/attr_publish/attr_publish.rb

@@ -0,0 +1,226 @@
+require 'active_support/concern'
+
+module AttrPublish
+  extend ::ActiveSupport::Concern
+
+  class_methods do
+    def attr_publish(column)
+      return unless table_exists?
+
+      column_name = column.to_sym || :published
+
+      # Silently ignore a missing column - since bombing on a missing
+      # column can make re-running migrations very hard.
+      return unless self.columns_hash[column_name.to_s].present?
+
+      column_type = self.columns_hash[column_name.to_s].type
+
+      if respond_to?(:scope)
+        # 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
+
+        # 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
+      end
+
+      case column_type
+      when :datetime
+        class_eval <<-EVIL, __FILE__, __LINE__ + 1
+          def published?(_when = Time.current)
+            #{column_name} ? #{column_name} <= _when : false
+          end
+          def unpublished?(_when = Time.current)
+            !published?(_when)
+          end
+          def publish(_when = Time.current)
+            self.#{column_name} = _when unless published?(_when)
+          end
+          def publish!(_when = Time.current)
+            publish(_when) && (!respond_to?(:save) || save)
+          end
+          def unpublish()
+            self.#{column_name} = nil
+            true
+          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} = nil
+          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 AttrPublish 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 cleared.
+    #   @!scope instance
+
+    # @!method unpublish!
+    #   Un-publish this object, then immediately save it to the database.
+    #   @!scope instance
+
+    # @!endgroup
+  end
+end

data/lib/attr_publish/version.rb

@@ -0,0 +1,16 @@
+module AttrPublish
+  module Version
+    Major       = 1
+    Minor       = 0
+    Revision    = 0
+    Prerelease  = nil
+    Compact     = [Major, Minor, Revision, Prerelease].compact.join('.')
+    Summary     = "AttrPublish v#{Compact}"
+    Description = "ActiveRecord convenience methods and scopes for publishing and finding published, unpublished and returning recent or upcoming items."
+    Author      = "Jurgen Jocubeit"
+    Email       = "support@brightcommerce.com"
+    Homepage    = "https://github.com/brightcommerce/attr_publish"
+    Metadata    = {'copyright' => 'Copyright 2018 Brightcommerce, Inc. All Rights Reserved.'}
+    License     = "MIT"
+  end
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: attr_publish
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Jurgen Jocubeit
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-12-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.1.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.1.4
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.1.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.1.4
+description: ActiveRecord convenience methods and scopes for publishing and finding
+  published, unpublished and returning recent or upcoming items.
+email: support@brightcommerce.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- lib/attr_publish.rb
+- lib/attr_publish/active_record.rb
+- lib/attr_publish/attr_publish.rb
+- lib/attr_publish/version.rb
+homepage: https://github.com/brightcommerce/attr_publish
+licenses:
+- MIT
+metadata:
+  copyright: Copyright 2018 Brightcommerce, Inc. All Rights Reserved.
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.13
+signing_key: 
+specification_version: 4
+summary: AttrPublish v1.0.0
+test_files: []