imperator-ext 0.2.0

data/.document

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

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -0,0 +1,16 @@
+source :rubygems
+
+gem 'virtus',    :git => 'git://github.com/kristianmandrup/virtus.git'
+gem 'imperator' #, :git => 'git://github.com/kristianmandrup/imperator.git'
+
+group :test do
+  gem 'mongoid', '~> 3.0'
+end
+
+group :development do
+  gem "rspec",    ">= 2.8.0"
+  gem "rdoc",     ">= 3.12"
+  gem "bundler",  ">= 1.0.0"
+  gem "jeweler",  "~> 1.8.4"
+  gem "simplecov",">= 0.5"
+end

data/Gemfile.lock

@@ -0,0 +1,69 @@
+GIT
+  remote: git://github.com/kristianmandrup/virtus.git
+  revision: 4b0d2cb9c5ec937b940dad0048fb7396f0e05466
+  specs:
+    virtus (0.5.1)
+      backports (~> 2.6.1)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activemodel (3.2.7)
+      activesupport (= 3.2.7)
+      builder (~> 3.0.0)
+    activesupport (3.2.7)
+      i18n (~> 0.6)
+      multi_json (~> 1.0)
+    backports (2.6.2)
+    builder (3.0.0)
+    diff-lcs (1.1.3)
+    git (1.2.5)
+    i18n (0.6.0)
+    imperator (0.2.0)
+      activemodel
+      uuidtools
+      virtus
+    jeweler (1.8.4)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+      rdoc
+    json (1.7.4)
+    mongoid (3.0.3)
+      activemodel (~> 3.1)
+      moped (~> 1.1)
+      origin (~> 1.0)
+      tzinfo (~> 0.3.22)
+    moped (1.2.0)
+    multi_json (1.3.6)
+    origin (1.0.4)
+    rake (0.9.2.2)
+    rdoc (3.12)
+      json (~> 1.4)
+    rspec (2.11.0)
+      rspec-core (~> 2.11.0)
+      rspec-expectations (~> 2.11.0)
+      rspec-mocks (~> 2.11.0)
+    rspec-core (2.11.1)
+    rspec-expectations (2.11.2)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.11.1)
+    simplecov (0.6.4)
+      multi_json (~> 1.0)
+      simplecov-html (~> 0.5.3)
+    simplecov-html (0.5.3)
+    tzinfo (0.3.33)
+    uuidtools (2.1.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (>= 1.0.0)
+  imperator
+  jeweler (~> 1.8.4)
+  mongoid (~> 3.0)
+  rdoc (>= 3.12)
+  rspec (>= 2.8.0)
+  simplecov (>= 0.5)
+  virtus!

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Kristian Mandrup
+
+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,339 @@
+## Imperator extensions
+
+This gem includes some extensions and integrations for the [imperator](https://github.com/Agowan/imperator) gem.
+
+The current integrations are for:
+
+* [mongoid](https://github.com/mongoid/mongoid)
+
+The gem is designed to simplify designing commands for REST actions and includes some useful macros to facilitate common patterns.
+
+## Mongoid imperator
+
+The Mongoid integration provides the class method `#attributes_for`, 
+which can be used to define Command attributes that match the fields of the Mongoid object that the command is designed to operate on.
+
+`attributes_for Post`
+
+Will create Command attributes for all fields defined by the Post class (model).
+You can finetune the Command attributes to be created by using the `:except` and `:only options`.
+
+```ruby
+class UpdatePostCommand < Imperator::Mongoid::Command
+  attributes_for Post, only: [:subject, :body]
+
+  # OR
+  attributes_for Post, except: [:state]
+end
+```
+
+In addition this gem extends the `Imperator::Command` class with the attributes 
+`object` and `initiator`. The initiator is meant to be set to the object that initiates the command, typically a Controller instance. The `initiator` can then be used to define delegation methods to the controller etc. 
+
+## Rest Commands
+
+If you inherit from the `Imperator::Command::Rest` class, you gain access to the
+REST convenience methods: `update`, `delete` and `create_new` which creates action methods with some default appropriate REST logic for the particular action.
+See the code for more info on how to use this for your own needs.
+
+```ruby
+class UpdatePostCommand < Imperator::Command::Rest
+  attribute :some_object_id
+  attribute :some_value
+
+  validates_presence_of :some_object_id
+
+  update do
+    puts "updated OK"
+  end
+end
+```
+
+## Mongoid integration
+
+Imperator also comes with a little Mongodi adaptor class, which provides the `attributes_for` method in order to easily redefine Mongoid model fields as Command attributes. Similar adaptors could be created for other ORMs such as Active Record etc.
+
+```ruby
+class UpdatePostCommand < Imperator::Mongoid::Command::Rest
+
+  attributes_for Post, except: [:status, :rating]
+
+  validates :name, presence: true
+
+  update do    
+    puts "#{object} was updated"
+  end
+
+  on_error do
+    puts "The Post could not be updated: #{object}"
+  end
+end
+```
+
+## Class Factory
+
+The `Imperator::Command::ClassFactory` can be used to easily create Command wrappers for your model classes.
+
+```ruby
+Imperator::Command::ClassFactory.create :publish, Post do
+  action do
+    find_object.publish!
+  end
+end
+```
+
+It is especially handy for creating Rest Command wrappers. Here we include the `macros` to simplify the code.
+
+```ruby
+require 'imperator/command/macros'
+
+imperator_command_factory.use do |factory|
+  # put common/shared logic in this REST base class
+  factory.default_rest_class = Imperator::Mongoid::Command::Rest
+
+  factory.create_rest :all, Post do
+    on_error do
+      puts "Oops! There was an error!"
+    end
+  end
+
+  factory.create_rest :update, Article do
+    attributes_for Article, only: [:title, :body] 
+
+    on_error do
+      puts "Oops! There was an error!"
+    end
+  end
+
+  # Same using :auto_attributes option
+  factory.create_rest :update, Article, auto_attributes: true, except: [:status] do
+    on_error do
+      puts "Oops! There was an error!"
+    end
+  end
+end
+```
+
+## ClassFactory macros
+
+If you include the macros, the following macros are exposed:
+
+* `#create_command` 
+* `#create_rest_command`
+* `#imperator_class_factory
+
+Usage example:
+
+```ruby
+# ensure all attributes of model are reflected in Command (if adaptor makes it possible)
+Imperator::Command::ClassFactory.default_options = {auto_attributes: true}
+
+module PostController
+  class Update < Action
+
+    command do
+      @command ||= create_rest_command(:update, Post).new object_hash
+    end
+  end
+end
+```
+## Command Method Factory
+
+By including the `Imperator::Command::MethodFactory` you get access to the `#command_method` macro, which lets you easily define Imperator Command methods.
+This is typically used in a Controller.
+
+```ruby
+class ServicesController
+  include Imperator::Command::MethodFactory
+
+  command_method :sign_in
+end
+```
+
+Focused Controller usage example:
+
+```ruby
+module ServicesController
+
+  class SignIn < Action
+    include Imperator::Command::MethodFactory
+
+    def run
+      sign_in.perform
+    end
+
+    command_method :sign_in
+  end
+end
+```
+
+Often you will want commands namespace scoped however. This is supported via the `:ns` option.
+
+```ruby
+module ServicesController
+
+  class SignIn < Action
+    include Imperator::Command::MethodFactory
+
+    def run
+      sign_in.perform
+    end
+
+    command_method :sign_in, ns: self.parent
+  end
+end
+```
+
+Creates a `#sign_in_command` with namespaced scoping:
+
+```ruby
+module ServicesController
+  class SignIn < Action
+    def sign_in_command
+      @sign_in_command ||= Services::SignInCommand.new initiator: self
+    end
+  end
+end
+```
+
+This is the recommended pattern for linking Focused Controller actions to Imperator commands.
+
+## Rest Commands
+
+The class `Imperator::Command::Rest` can be used as a base class for REST CUD commands (Create, Update, Delete). This class includes the module `Imperator::Command::RestHelper` which includes a number of useful methods for defining typical REST action behavior for an Imperator Command.
+
+Usage example:
+
+```ruby
+class UpdatePostCommand < Imperator::Command::Rest
+  update_action do
+    notify :updated
+  end
+end
+```
+
+Mongoid example:
+
+```ruby
+class UpdatePostCommand < Imperator::Mongoid::Command::Rest
+  update_action do
+    notify :updated
+  end
+end
+```
+
+## Controllers, Actions and Commands
+
+An analysis of the current MVC design pattern in Rails, in particular how the Controllers
+are designed and can be improved by employing different Design Patterns to ensure better
+decoupling, single responsibility and how to aovid the typical Rails anti-pattern of flat classes, bloated with methods.
+
+## Using Imperator Commands in the current Controller pattern
+
+Demonstrates just how ugly the current Controller convention is!!!
+
+```ruby
+class PostController < ApplicationController
+  def update    
+    update_command.valid? ? update_valid : update_invalid
+  end
+
+  protected
+
+  def update_valid
+    update_command.perform and redirect_to(root_url)
+  end
+
+  def update_invalid
+    render edit_post_path(command.object)
+  end
+
+  def update_command
+    @update_command ||= UpdatePostCommand.new(params[:post])
+  end
+end
+```
+
+## Using Imperator Commands with Focused Controllers
+
+Much nicer encapsulated logic using FocusedController :)
+
+```ruby
+module PostController
+  class Update < Action
+    invalid_path do
+      root_url
+    end
+
+    # generated by naming convention
+    # command { @command ||= UpdatePostCommand.new post_hash }
+  end
+end
+```
+
+Demonstrating some customization of Controller logic
+
+```ruby
+module PostController
+  class Update < Action
+    valid do
+      command.perform
+      redirect_to root_url
+    end
+
+    def invalid
+      flash_msg "#{command.object} was invalid!", :error
+      super
+    end
+
+    command { @command ||= command_class.new object_hash.merge(:status => :complete) }
+  end
+end
+```
+
+And more...
+
+```ruby
+module PostController
+  class Update < Action
+    valid do
+      flash_msg "#{command.object} was valid!"
+      command.perform
+      puts "#{command} was performed!"
+      valid_redirect
+    end
+
+    valid_redirect_path do
+      root_url
+    end
+
+    def invalid
+      flash_msg "#{command.object} was invalid!", :error
+      super
+    end
+
+    command do
+      @command ||= begin
+        c = UpdatePostCommand.new post_hash
+        c.complete_it!
+      end
+    end
+  end
+end
+```
+
+## Contributing to imperator-ext
+ 
+* 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) 2012 Kristian Mandrup. See LICENSE.txt for
+further details.
+

data/Rakefile

@@ -0,0 +1,49 @@
+# 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'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "imperator-ext"
+  gem.homepage = "http://github.com/kristianmandrup/imperator-ext"
+  gem.license = "MIT"
+  gem.summary = %Q{Various extensions for Imperator}
+  gem.description = %Q{Factories, Macros, REST helpers and Mongoid integration}
+  gem.email = "kmandrup@gmail.com"
+  gem.authors = ["Kristian Mandrup"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :default => :spec
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "imperator-ext #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.2.0

data/docs/Design.md

@@ -0,0 +1,197 @@
+## Controllers, Actions and Commands
+
+An analysis of the current MVC design pattern in Rails, in particular how the Controllers
+are designed and can be improved by employing different Design Patterns to ensure better
+decoupling, single responsibility and how to aovid the typical Rails anti-pattern of flat classes, bloated with methods.
+
+## Using Imperator Commands in the current Controller pattern
+
+Demonstrates just how ugly the current Controller convention is!!!
+
+```ruby
+class PostController < ApplicationController
+  def update    
+    update_command.valid? ? update_valid : update_invalid
+  end
+
+  protected
+
+  def update_valid
+    update_command.perform and redirect_to(root_url)
+  end
+
+  def update_invalid
+    render edit_post_path(command.object)
+  end
+
+  def update_command
+    @update_command ||= UpdatePostCommand.new(params[:post])
+  end
+end
+```
+
+## Using Imperator Commands with Focused Controllers
+
+Much nicer encapsulated logic using FocusedController :)
+
+```ruby
+module PostController
+  class Update < UpdateCommandAction
+    invalid_path do
+      root_url
+    end
+
+    # generated by naming convention
+    # command { @command ||= UpdatePostCommand.new post_hash }
+  end
+end
+```
+
+Demonstrating some customization of Controller logic
+
+```ruby
+module PostController
+  class Update < UpdateCommandAction
+    valid do
+      command.perform
+      redirect_to root_url
+    end
+
+    def invalid
+      flash_msg "#{command.object} was invalid!", :error
+      super
+    end
+
+    command { @command ||= command_class.new object_hash.merge(:status => :complete) }
+  end
+end
+```
+
+And more...
+
+```ruby
+module PostController
+  class Update < UpdateCommandAction
+    valid do
+      flash_msg "#{command.object} was valid!"
+      command.perform
+      puts "#{command} was performed!"
+      valid_redirect
+    end
+
+    valid_redirect_path do
+      root_url
+    end
+
+    def invalid
+      flash_msg "#{command.object} was invalid!", :error
+      super
+    end
+
+    command do
+      @command ||= begin
+        c = UpdatePostCommand.new post_hash
+        c.complete_it!
+      end
+    end
+  end
+end
+```
+
+## Restfull Commands
+
+If you inherit from the `Imperator::Command::Restfull` class, you gain access to the
+REST convenience methods: `update`, `delete` and `create_new` which creates action methods with some default appropriate REST logic for the particular action.
+See the code for more info on how to use this for your own needs.
+
+```ruby
+class UpdatePostCommand < Imperator::Command::Restfull
+  attribute :some_object_id
+  attribute :some_value
+
+  validates_presence_of :some_object_id
+
+  update do
+    puts "updated OK"
+  end
+end
+```
+
+## Mongoid integration
+
+Imperator also comes with a little Mongodi adaptor class, which provides the `attributes_for` method in order to easily redefine Mongoid model fields as Command attributes. Similar adaptors could be created for other ORMs such as Active Record etc.
+
+```ruby
+class UpdatePostCommand < Imperator::Mongoid::RestCommand
+
+  attributes_for Post, except: [:status, :rating]
+
+  validates :name, presence: true
+
+  update do    
+    puts "#{object} was updated"
+  end
+
+  on_error do
+    puts "The Post could not be updated: #{object}"
+  end
+end
+```
+
+## Class Factory
+
+The `Imperator::Command::ClassFactory` can be used to easily create Command wrappers for your model classes.
+
+```ruby
+Imperator::Command::ClassFactory.create :publish, Post do
+  action do
+    find_object.publish!
+  end
+end
+```
+
+It is especially handy for creating Rest Command wrappers.
+
+```ruby
+Imperator::Command::ClassFactory.use do |factory|
+  factory.default_rest_class = Imperator::Mongoid::RestCommand
+  factory.create_rest :all, Post do
+    on_error do
+      puts "Oops! There was an error!"
+    end
+  end
+
+  factory.create_rest :update, Article do
+    attributes_for Article, only: [:title, :body] 
+
+    on_error do
+      puts "Oops! There was an error!"
+    end
+  end
+
+  # Same using :auto_attributes option
+  factory.create_rest :update, Article, auto_attributes: true, except: [:status] do
+    on_error do
+      puts "Oops! There was an error!"
+    end
+  end
+end
+```
+
+## Using ClassFactory macros
+
+There are also two global macros `create_command` and `create_rest_command` available.
+
+```ruby
+# ensure all attributes of model are reflected in Command (if adaptor makes it possible)
+Imperator::Command::ClassFactory.default_options = {auto_attributes: true}
+
+module PostController
+  class Update < UpdateCommandAction
+
+    command do
+      @command ||= create_rest_command(:update, Post).new object_hash
+    end
+  end
+end
+```