resourcelogic 0.0.11

data/.gitignore

@@ -0,0 +1,7 @@
+.DS_Store
+*.log
+*.sqlite3
+pkg/*
+coverage/*
+doc/*
+benchmarks/*

data/CHANGELOG.rdoc

@@ -0,0 +1,3 @@
+== 0.0.9
+
+* Initial release, beta.

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Ben Johnson of Binary Logic (binarylogic.com)
+
+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.rdoc

@@ -0,0 +1,167 @@
+= Resourcelogic
+
+<b>Beta warning: right now this plugin is in what I like to call a "semi-beta". The only thing left to do is write documentation and add in the tests. I have already thoroughly tested this in a separate application, and am in the process of moving over the tests without having to pull over the entire rails application.</b>
+
+The purpose of Resourcelogic is to support a development style I created called <b>"Contextual Development"</b> (see contextual development below). This is an idea I've had for a while and finally decided to give it a try on one of my projects. It worked out great, and as a result, is probably the cleanest app I've built to date. So I decided to package this idea up and release it as Resourcelogic. This library spawned out of the {resource_controller plugin}[http://github.com/giraffesoft/resource_controller] by James Gollick, which is an excellent plugin. I eventually made so many changes to it that it made more sense to rewrite my own.
+
+== Helpful links
+
+*	<b>Documentation:</b> http://rdoc.info/projects/binarylogic/resourcelogic
+* <b>Bugs / feature suggestions:</b> http://binarylogic.lighthouseapp.com/projects/28581-resourcelogic
+
+== Contextual Development
+
+The idea behind contextual development is simple: <b>an API should be a be a byproduct of good design</b>. Meaning you should never have to explicitly build an API. It should, in essence, be an "accident".
+
+=== 1. No need to namespace controllers when you have context
+
+Your interface should not dictate the structure of your controllers. Instead, your controllers should represent a collection of resources that your interface can use (AKA an API). The problem is that rails does so much magic, and makes so many assumptions, that sometimes it distorts the basics behind the MVC pattern.
+
+A good example is using {Flex}[http://www.adobe.com/products/flex/] to build your interface. This allows you to go back to the basics behind RESTful development by forcing you to separate your interface from your application. A flex interface communicates with your application via XML. As a result, when you complete your application you also have a "production ready" API. You basically completed two projects in one.
+
+That being said, why can't we accomplish the same thing with an HTML interface? For one, an HTML interface isn't as cleanly decoupled from the controllers as a Flex interface. For two, rails doesn't give us all of the tools to properly accomplish this. Instead, people create work-arounds by namespacing controllers to represent context and/or scope (Ex: Admin::CommentsController). Why not have a single controller that is <b>context aware</b>? Hence the name <b>"Contextual Development"</b>. So instead of an Admin namespace, you can use the context to modify the interface / scope. Example:
+
+  class CommentsController < ApplicationController
+    layout Proc.new { context == :admin ? "admin" : "application" }
+    
+    private
+      # context is irrelevant when determining scope
+      def scope
+        current_user.admin? ? Comment : current_user.comments
+      end
+  end
+
+=== 2. Single point of access for resources
+
+Having a <b>single</b> controller is great, because it represents a <b>single</b> resource. This means that <b>every</b> request for that resource must pass through that single controller. Think about it, what is an API essentially? Controlled access to your database. You don't go and create an entirely new model for every scope/context you use the model, do you? Why do the same for your API? Your API resources are the "models" for anyone using it, so it doesn't make sense to have /comments and /admin/comments.
+
+To bring it all home, all requests for a resource should pass through a single controller, in the same manner that all database activity for a table must pass through a single model. You can feel confident adding controller specific logic to that resource without having to worry about duplicating it across multiple controllers. A very simple example: storing the user's IP address with a record.
+
+=== 3. Relative URL and path methods
+
+Another big problem with using the same controller in various contexts is the need to specify relative paths instead of absolute paths. When you specify resources in your routes you get all kinds of useful <b>absolute</b> path methods, but where are the relative ones? Let's say you have the following paths:
+
+1. /articles
+2. /admin/articles
+
+Articles have many comments. What if you want to link to that article's comments? Do you use <b>article_comments_path</b> or <b>admin_article_comments_path</b>? You could use the <b>context</b> method described above to determine this, but this will get messy and annoying very fast. Instead why not use <b>child_collection_path(:comments)</b>? The paths are relative based on a tree structure. So you also get <b>parent</b> and <b>sibling</b> paths. Now you can easily nest resources without having to worry about linking to them. See the documentation for more details on the various URL and path methods that are available to you.
+
+== Install and use
+
+=== 1. Install the gem
+
+Install the gem / plugin (recommended)
+
+  $ sudo gem install resourcelogic
+
+Now add the gem dependency in your config:
+
+  # config/environment.rb
+  config.gem "resourcelogic"
+
+Or you install this as a plugin (for older versions of rails)
+
+  script/plugin install git://github.com/binarylogic/resourcelogic.git
+
+=== 2. Create your ResourceController
+
+  script/generate controller resource
+
+Your ResourceController should look something like:
+
+  class ResourceController < ApplicationController
+    acts_as_resource
+  end
+
+Now all of your controllers that are "resources" can extend this controller. Why do this? So you can set your default behavior for resources in one spot. This idea what brought over from the resource_controller plugin. The DSL resource_controller came up with is pretty cool:
+
+  class ResourceController < ApplicationController
+    acts_as_resource
+    
+    create.flash { # code to evaluate to create the flash message for a successful create }
+    create.before { # code you want to execute before the create action }
+    create.wants.js { # code you want to execute in the wants.js for a successful create }
+    create.failure.flash { # code to evaluate to create the flash message for an unsuccessful create }
+    create.failure.js { # code you want to execute in the wants.js for an unsuccessful create }
+    # etc...See Resourcelogic::ActionOptions and Resourcelogic::FailableActionOptions for more details
+  end
+
+All of these are overrideable, meaning your subclasses can change behavior in a granular manner, and preserve the defaults where necessary.
+
+=== 3. Make sure you don't namespace your controllers
+
+Instead of namespacing your controllers, give them context. For example, let's say you you have /commments and /admin/comments. This controller has 2 contexts: root and admin. So your routes should look something like:
+
+  map.with_options(:path_prefix => "admin", :name_prefix => "admin_") do |admin|
+    admin.resource :comments
+  end
+  map.resources :comments
+
+Then in your controller use the context method to make adjustments:
+
+  class CommentsController < ResourceController
+    layout Proc.new { context == :admin ? "admin" : "application" }
+  end
+
+You also have the same context method in your views. Lastly, if you feel your views are getting cluttered by trying to determine what context you are in, you can use the namespace_views_by_context option (See Resourcelogic::Context::Config for more info). This will change your default view path to a context subfolder. Ex:
+
+  /comments
+    /admin
+    /root
+    any other contexts..
+
+See the Feature Highlights section below for more options, and the documentation for a complete list.
+
+== Feature highlights
+
+I don't want to repeat what is already in the documentation, but there are a lot of really nice configuration and utility methods. <b>Here are just a few</b>:
+
+<b>Class level methods</b>
+
+  belongs_to :relationship_name   # will check to see if the resource is being scoped by a parent and give you some nifty methods for this (see below). You can call this multiple times. Just like ActiveRecord.
+  contextual_views true           # will split up your views into subfolders: comments/context1, comments/context2, and will change your default view path to the respective folder
+
+<b>Instance level methods</b>
+
+Lets pretend we are dealing with a products resource that belongs to a category.
+
+  context                                 # the name of the context you are in
+  
+  object                                  # current product object, if any
+  collection                              # current collection of products
+  parent                                  # current category object, if any
+
+Now you have all of the "relative routes" to help you easily nest resources and use them in different contexts:
+  
+  object_path                             # /products/:id
+  edit_object_path                        # /products/:id/edit
+  new_object_path                         # /products/new
+  collection_path                         # /products
+  
+  parent_path                             # /categories/:parent_id
+  edit_parent_path                        # /categories/:parent_id/edit
+  parent_collection_path                  # /categories
+  new_parent_path                         # /categories/new
+  
+  sibling_path(sibling)                   # /sibling_name/:id
+  edit_sibling_path(sibling)              # /sibling_name/:id/edit
+  new_sibling_path(:sibling_name)         # /sibling_name/new
+  sibling_collection_path(:sibling_name)  # /sibling_name
+  
+  child_path(child)                       # /products/:product_id/child_name/:id
+  edit_child_path(child)                  # /products/:product_id/child_name/:id/edit
+  new_child_path(:child_name)             # /products/:product_id/child_name/new
+  child_collection_path(:child_name)      # /products/:product_id/child_name
+
+Notice you have the edit_* paths. The above paths are implemented in a very flexible manner. So you are not limited them, you can call your custom actions too:
+
+  map.resources :products, :member => [:approve], :collection => [:approve_all]
+  approve_object_path                     # /products/:id/approve
+  approve_all_collection_path             # /products/approve
+
+The above example is probably not the best one, but you get the point.
+
+Lastly, all of the above can end with _url instead of _path. <b>See docs for a complete list of available methods.</b>
+
+
+Copyright (c) 2008 {Ben Johnson of Binary Logic}[http://www.binarylogic.com], released under the MIT license

data/Rakefile

@@ -0,0 +1,49 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "resourcelogic"
+    gem.summary = "Removes the need to namespace controllers by adding context and relative url functions among other things."
+    gem.email = "bjohnson@binarylogic.com"
+    gem.homepage = "http://github.com/binarylogic/resourcelogic"
+    gem.authors = ["Ben Johnson of Binary Logic"]
+    gem.rubyforge_project = "resourcelogic"
+    gem.add_dependency "activesupport"
+  end
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :default => :test
+
+begin
+  require 'rake/contrib/sshpublisher'
+  namespace :rubyforge do
+    desc "Release gem to RubyForge"
+    task :release => ["rubyforge:release:gem"]
+  end
+rescue LoadError
+  puts "Rake SshDirPublisher is unavailable or your rubyforge environment is not configured."
+end

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:patch: 11
+:major: 0
+:minor: 0

data/init.rb

@@ -0,0 +1 @@
+require "resourcelogic"

data/lib/resourcelogic.rb

@@ -0,0 +1,16 @@
+require File.dirname(__FILE__) + "/resourcelogic/accessors"
+require File.dirname(__FILE__) + "/resourcelogic/action_options"
+require File.dirname(__FILE__) + "/resourcelogic/actions"
+require File.dirname(__FILE__) + "/resourcelogic/aliases"
+require File.dirname(__FILE__) + "/resourcelogic/child"
+require File.dirname(__FILE__) + "/resourcelogic/context"
+require File.dirname(__FILE__) + "/resourcelogic/failable_action_options"
+require File.dirname(__FILE__) + "/resourcelogic/parent"
+require File.dirname(__FILE__) + "/resourcelogic/response_collector"
+require File.dirname(__FILE__) + "/resourcelogic/scope"
+require File.dirname(__FILE__) + "/resourcelogic/self"
+require File.dirname(__FILE__) + "/resourcelogic/sibling"
+require File.dirname(__FILE__) + "/resourcelogic/singleton"
+require File.dirname(__FILE__) + "/resourcelogic/sub_views"
+require File.dirname(__FILE__) + "/resourcelogic/urligence"
+require File.dirname(__FILE__) + "/resourcelogic/base"

data/lib/resourcelogic/accessors.rb

@@ -0,0 +1,53 @@
+module Resourcelogic # :nodoc:
+  module Accessors # :nodoc:
+    private
+      def block_accessor(*accessors)
+        accessors.each do |block_accessor|
+          class_eval <<-"end_eval", __FILE__, __LINE__
+
+            def #{block_accessor}(*args, &block)
+              unless args.empty? && block.nil?
+                args.push block if block_given?
+                @#{block_accessor} = [args].flatten
+              end
+              
+              @#{block_accessor}
+            end
+
+          end_eval
+        end
+      end
+      
+      def scoping_reader(*accessor_names)
+        accessor_names.each do |accessor_name|        
+          class_eval <<-"end_eval", __FILE__, __LINE__
+            def #{accessor_name}(&block)
+              @#{accessor_name}.instance_eval &block if block_given?
+              @#{accessor_name}
+            end
+          end_eval
+        end
+      end
+      
+      def class_scoping_reader(accessor_name, start_value)
+        write_inheritable_attribute accessor_name, start_value
+        
+        class_eval <<-"end_eval", __FILE__, __LINE__
+          def self.#{accessor_name}(context = :root, &block)
+            read_inheritable_attribute(:#{accessor_name}).instance_eval(&block) if block_given?
+            read_inheritable_attribute(:#{accessor_name})
+          end
+        end_eval
+      end
+      
+      def reader_writer(accessor_name)
+        class_eval <<-"end_eval", __FILE__, __LINE__
+          def #{accessor_name}(*args, &block)
+            args << block unless block.nil?
+            @#{accessor_name} = args.first unless args.empty?
+            @#{accessor_name}
+          end
+        end_eval
+      end
+  end
+end

data/lib/resourcelogic/action_options.rb

@@ -0,0 +1,40 @@
+module Resourcelogic
+  class ActionOptions
+    extend Resourcelogic::Accessors
+    
+    reader_writer  :flash
+    reader_writer  :flash_now
+    
+    block_accessor :after, :before
+    
+    def initialize
+      @collector = Resourcelogic::ResponseCollector.new
+    end
+    
+    def response(*args, &block)
+      if !args.empty? || block_given?
+        @collector.clear
+        args.flatten.each { |symbol| @collector.send(symbol) }
+        block.call(@collector) if block_given?
+      end
+      
+      @collector.responses
+    end
+    alias_method :respond_to,  :response
+    alias_method :responds_to, :response
+    
+    def wants
+      @collector
+    end
+    
+    def dup
+      returning self.class.new do |duplicate|
+        duplicate.instance_variable_set(:@collector, wants.dup)
+        duplicate.instance_variable_set(:@before, before.dup)       unless before.nil?
+        duplicate.instance_variable_set(:@after, after.dup)         unless after.nil?
+        duplicate.instance_variable_set(:@flash, flash.dup)         unless flash.nil?
+        duplicate.instance_variable_set(:@flash_now, flash_now.dup) unless flash_now.nil?
+      end
+    end
+  end
+end

data/lib/resourcelogic/actions.rb

@@ -0,0 +1,174 @@
+module Resourcelogic
+  module Actions
+    ACTIONS           = [:index, :show, :new_action, :create, :edit, :update, :destroy].freeze
+    FAILABLE_ACTIONS  = ACTIONS - [:index, :new_action, :edit, :destroy].freeze
+    
+    def self.included(klass)
+      klass.class_eval do
+        ACTIONS.each do |action|
+          class_scoping_reader action, FAILABLE_ACTIONS.include?(action) ? FailableActionOptions.new : ActionOptions.new
+        end
+        class_scoping_reader :context, ContextOptions.new
+        add_acts_as_resource_module(Methods)
+      end
+    end
+    
+    module Methods
+      def new
+        load_object
+        before :new_action
+        response_for :new_action
+      end
+      
+      def create
+        load_object
+        before :create
+        if object.save
+          after :create
+          set_flash :create
+          response_for :create
+        else
+          after :create_fails
+          set_flash :create_fails
+          response_for :create_fails
+        end
+      end
+      
+      def edit
+        load_object
+        before :edit
+        response_for :edit
+      end
+      
+      def update
+        load_object
+        object.attributes = attributes
+        before :update
+        if object.save
+          after :update
+          set_flash :update
+          response_for :update
+        else
+          after :update_fails
+          set_flash :update_fails
+          response_for :update_fails
+        end
+      end
+      
+      def destroy
+        load_object
+        before :destroy
+        object.destroy
+        after :destroy
+        set_flash :destroy
+        response_for :destroy
+      end
+      
+      def show
+        load_object
+        before :show
+        response_for :show
+      rescue ActiveRecord::RecordNotFound
+        response_for :show_fails
+      end
+      
+      def index
+        load_collection
+        before :index
+        response_for :index
+      end
+      
+      private
+        # Used to actually pass the responses along to the controller's respond_to method.
+        #
+        def response_for(action)
+          begin
+            respond_to do |wants|
+              options_for(action).response.each do |method, block|
+                if block.nil?
+                  wants.send(method)
+                else
+                  wants.send(method) { instance_eval(&block) }
+                end
+              end
+            end
+          rescue ActionController::DoubleRenderError
+          end
+        end
+        
+        # Calls the after callbacks for the action, if one is present.
+        #
+        def after(action)
+          invoke_callbacks *options_for(action).after
+        end
+        
+        # Calls the before block for the action, if one is present.
+        #
+        def before(action)
+          invoke_callbacks *self.class.send(action).before
+        end
+        
+        # Sets the flash and flash_now for the action, if it is present.
+        #
+        def set_flash(action)
+          set_normal_flash(action)
+          set_flash_now(action)
+        end
+        
+        # Sets the regular flash (i.e. flash[:notice] = '...')
+        #
+        def set_normal_flash(action)
+          if f = options_for(action).flash
+            flash[:notice] = f.is_a?(Proc) ? instance_eval(&f) : options_for(action).flash
+          end
+        end
+        
+        # Sets the flash.now (i.e. flash.now[:notice] = '...')
+        #
+        def set_flash_now(action)
+          if f = options_for(action).flash_now
+            flash.now[:notice] = f.is_a?(Proc) ? instance_eval(&f) : options_for(action).flash_now
+          end
+        end
+        
+        # Returns the options for an action, which is a symbol.
+        #
+        # Manages splitting things like :create_fails.
+        #
+        def options_for(action)
+          action = action == :new_action ? [action] : "#{action}".split('_').map(&:to_sym)
+          options = self.class.send(action.first)
+          options = options.send(action.last == :fails ? :fails : :success) if Resourcelogic::Actions::FAILABLE_ACTIONS.include? action.first
+          
+          options
+        end
+        
+        def invoke_callbacks(*callbacks)
+          unless callbacks.empty?
+            callbacks.select { |callback| callback.is_a? Symbol }.each { |symbol| send(symbol) }
+            
+            block = callbacks.detect { |callback| callback.is_a? Proc }
+            instance_eval &block unless block.nil?
+          end
+        end
+        
+        def load_parent
+          instance_variable_set "@#{parent_model_name}", parent_object if parent?
+        end
+        
+        # Used internally to load the member object in to an instance variable @#{model_name} (i.e. @post)
+        #
+        def load_object
+          load_parent
+          instance_variable_set "@#{object_name}", object
+        end
+        
+        # Used internally to load the collection in to an instance variable @#{model_name.pluralize} (i.e. @posts)
+        #
+        def load_collection
+          load_parent
+          instance_variable_set "@#{object_name.to_s.pluralize}", collection
+        end
+    end
+  end
+end