mongoid-publishable 0.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rvmrc

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+if ! rvm list | grep -q ruby-1.9.3-p194 ; then
+	rvm install 1.9.3-p194
+fi
+
+rvm 1.9.3-p194@ryantownsend_mongoid_publishable --create
+
+if ! gem list | grep -q bundler ; then
+	gem install --no-ri --no-rdoc bundler
+	bundle install --without production
+fi

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+  - 1.9.3
+services:
+  - mongodb

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in mongoid_publishable.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Ryan Townsend
+
+MIT License
+
+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.md

@@ -0,0 +1,178 @@
+# Mongoid::Publishable
+
+Ever wanted to allow your users to create something (or somethings) before authenticating. For example, you might want to let them write a review, before you ask them to login and publish it. This is what Mongoid::Publishable handles.
+
+[![Build Status][2]][1]
+
+  [1]: http://travis-ci.org/ryantownsend/mongoid-publishable
+  [2]: https://secure.travis-ci.org/ryantownsend/mongoid-publishable.png?branch=master
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "mongoid-publishable"
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install mongoid-publishable
+
+## Usage
+
+Include the module in any models you want to be publishable:
+
+```ruby
+class Review
+  include Mongoid::Document
+  include Mongoid::Publishable
+  # ...
+end
+```
+
+It will use the `user_id` column by default, but you can override that by using `publisher_column`. It also assumes you're using the `id` attribute of the publisher, again you can override it using `publisher_foreign_key`, here's an example:
+
+```ruby
+class ChatMessage
+  include Mongoid::Document
+  include Mongoid::Publishable
+  
+  belongs_to :author
+ 
+  publisher_column :author_id
+  publisher_foreign_key :username
+  # ...
+end
+```
+
+In your controllers, or anywhere you save the objects, you can swap out your `save` calls for `persist_and_publish!` calls, this method accepts an optional user. If none is passed, or the object that you do pass is nil, it'll raise an exception, so you can handle your authentication there:
+
+```ruby
+class ReviewsController < ApplicationController
+  include Mongoid::Publishable::Queuing
+
+  def create
+    # create the review
+    @review = Review.new(params[:review])
+    # if persisted and published
+    if @review.persist_and_publish!(current_user)
+      # redirect as normal
+      redirect_to @review, notice: "Review created!"
+    # validation failed
+    else
+      render :new
+    end
+  # persisted, but publishing failed
+  rescue Mongoid::Publishable::UnpublishedError => exception
+    # the error actually contains the object
+    publishing_queue << exception.model
+    # send the user to the login page
+    redirect_to new_user_session_path
+  end
+end
+```
+
+An alternative without the exception handling would be:
+
+```ruby
+class ReviewsController < ApplicationController
+  include Mongoid::Publishable::Queuing
+
+  def create
+    # create the review
+    @review = Review.new(params[:review])
+    @review.publish_via(current_user)
+    # if persisted and published
+    if @review.save && @review.published?
+      # redirect as normal
+      redirect_to @review, notice: "Review created!"
+    # persisted, but publishing failed
+    elsif @review.persisted?
+      # the error actually contains the object
+      publishing_queue << @review
+      # send the user to the login page
+      redirect_to new_user_session_path
+    # validation failed
+    else
+      render :new
+    end
+  end
+end
+```
+   
+The advantage to the former style (using exceptions) is that you can handle them globally in your ApplicationController using this code:
+
+```ruby
+class ApplicationController < ActionController::Base
+  include Mongoid::Publishable::Queuing
+  
+  rescue_from Mongoid::Publishable::UnpublishedError, with: :authenticate_to_publish
+  
+  protected
+  def authenticate_to_publish(exception)
+    # add the object on to the queue
+    publishing_queue << exception.model
+    # send the user to the login page
+    redirect_to new_user_session_path
+  end
+end
+```
+
+The publishing queue is stored in the user's session. After authentication, you'll want to call `publish_via` on the queue, which will then publish all the objects it contains. Here's an example:
+
+```ruby
+class UserSessionsController < ApplicationController
+  def create
+    @user = User.authenticate(params[:user])
+    if @user
+      
+      # this is the key line:
+      publishing_queue.publish_via(@user)
+      
+      session[:user_id] = @user.id
+      redirect_to root_path, notice: "Login successful!"
+    else
+      render :new
+    end
+  end
+  
+  # ...
+end
+```
+
+Models are also provided with an `after_publish` callback that can be used like any other ActiveModel-style callback.
+
+```ruby
+class Review
+  include Mongoid::Document
+  include Mongoid::Publishable
+  
+  # it accepts a symbol referencing a method
+  after_publish :notify_item_owner
+  # it also accepts a block
+  after_publish do
+    puts "Mongoid::Publishable and it's creator are awesome!"
+  end
+  
+  private
+  def notify_item_owner
+    # do something
+  end
+end
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Run the test suite (`rake`), ensure all specs pass
+4. Commit your changes (`git commit -am 'Add some feature'`)
+5. Push to the branch (`git push origin my-new-feature`)
+6. Create new Pull Request
+
+After running specs, you can find a test coverage report at coverage/index.html

data/Rakefile

@@ -0,0 +1,12 @@
+require "bundler/gem_tasks"
+
+require "rspec/core/rake_task"
+
+desc "Runs all the specs"
+task default: %w(spec)
+
+desc "Run specs"
+RSpec::Core::RakeTask.new do |t|
+  t.pattern = "./spec/**/*_spec.rb" # don't need this, it's default.
+  # Put spec opts in a file named .rspec in root
+end

data/lib/mongoid/publishable.rb

@@ -0,0 +1,98 @@
+require "mongoid"
+require "mongoid/publishable/callbacks"
+require "mongoid/publishable/unpublished_error"
+
+module Mongoid
+  module Publishable
+    def self.included(base)
+      base.extend ClassMethods
+      base.send :include, InstanceMethods
+      base.send :include, Callbacks
+      base.class_eval do
+        # allow overwriting of the columns on an instance level
+        attr_writer :publisher_column, :publisher_foreign_key
+      end
+    end
+
+    module ClassMethods
+      # gets/sets the column that stores the user_id
+      def publisher_column(name = nil)
+        @publisher_column = name if name
+        @publisher_column || :user_id
+      end
+
+      def publisher_foreign_key(name = nil)
+        @publisher_foreign_key = name if name
+        @publisher_foreign_key || :id
+      end
+    end
+
+    module InstanceMethods
+      # saves to the db, and publishes if possible
+      def persist_and_publish(publisher = nil)
+        publish_via(publisher) && save
+      end
+
+      # saves to the db, and publishes if possible
+      # raises an UnpublishedError if unable to publish
+      def persist_and_publish!(publisher = nil)
+        # attempt save / publish
+        persist_and_publish(publisher)
+        # if it was saved to the DB
+        if persisted?
+          # return true if published, raise exception if not
+          published? || raise_unpublished_error
+        # if the save failed
+        else
+          # return false to allow traditional validation
+          false
+        end
+      end
+
+      # delegate publisher column, allow overriding
+      def publisher_column
+        @publisher_column || self.class.publisher_column
+      end
+
+      # delegate foreign key, allow overriding
+      def publisher_foreign_key
+        @publisher_foreign_key || self.class.publisher_foreign_key
+      end
+
+      # publishes this instance using the id provided
+      def publish_via(publisher)
+        # ensure this isn't published and we have a publisher
+        if !published? && publisher
+          # load the publisher's foreign key
+          value = publisher.send(publisher_foreign_key)
+          # update this instance with the key
+          self.send("#{publisher_column}=", value)
+          # mark as just published
+          run_after_publish_callbacks
+        end
+      end
+
+      # publishes this instance using the id provided
+      # and persists the publishing
+      def publish_via!(publisher)
+        publish_via(publisher) && save
+      end
+
+      # returns boolean of whether this instance has been published
+      def published?
+        persisted? && send(publisher_column)
+      end
+
+      # returns whether this instance needs publishing (persisted, not published)
+      def requires_publishing?
+        persisted? && !send(publisher_column)
+      end
+
+      # raises an UnpublishedError containing this object as a reference
+      def raise_unpublished_error
+        raise UnpublishedError.new.tap { |e| e.model = self }, "Unable to publish this #{self.class.name}"
+      end
+
+    end
+  end
+end

data/lib/mongoid/publishable/callback.rb

@@ -0,0 +1,23 @@
+module Mongoid
+  module Publishable
+    class Callback
+      def initialize(*args, &block)
+        if block_given?
+          @method = block
+        elsif args.length == 1 && args[0].kind_of?(Symbol)
+          @method = args[0]
+        else
+          raise ArgumentError, "after_publish only allows a block or a symbol method reference as arguments"
+        end
+      end
+      
+      def process(object)
+        if @method.respond_to?(:yield)
+          @method.yield(object)
+        else
+          object.send(@method)
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/publishable/callback_collection.rb

@@ -0,0 +1,11 @@
+module Mongoid
+  module Publishable
+    class CallbackCollection < Array
+      def process(object)
+        each do |callback|
+          callback.process(object)
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/publishable/callbacks.rb

@@ -0,0 +1,50 @@
+require "mongoid/publishable/callback"
+require "mongoid/publishable/callback_collection"
+
+module Mongoid
+  module Publishable
+
+    module Callbacks
+      def self.included(base)
+        base.extend ClassMethods
+        base.send :include, InstanceMethods
+        base.class_eval do
+          # handle after_publish callbacks
+          after_save :process_after_publish_callbacks, if: :run_after_publish_callbacks?
+        end
+      end
+      
+      module ClassMethods
+        # returns the list of callbacks
+        def after_publish_callbacks
+          @after_publish_callbacks ||= CallbackCollection.new
+        end
+        
+        # adds a callback to the list
+        def after_publish(*args, &block)
+          Callback.new(*args, &block).tap do |callback|
+            after_publish_callbacks << callback
+          end
+        end
+      end
+      
+      module InstanceMethods        
+        # process the callbacks
+        def process_after_publish_callbacks
+          self.class.after_publish_callbacks.process(self)
+        end
+    
+        # set to run the callbacks after save
+        def run_after_publish_callbacks
+          @run_after_publish_callbacks = true
+        end
+    
+        # returns whether the object has just been published
+        def run_after_publish_callbacks?
+          !!@run_after_publish_callbacks
+        end
+      end
+    end
+
+  end
+end