resourcelogic 0.9.0 → 0.10.0

data/README.rdoc

@@ -1,26 +1,50 @@
 = Resourcelogic
 
-*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>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 "Contextual Development" (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. 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.
+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://resourcelogic.rubyforge.org
+* <b>Bugs / feature suggestions:</b> http://binarylogic.lighthouseapp.com/projects/28581-resourcelogic
 
 == Contextual Development
 
-The idea behind contextual development is simple: *an API should be a be a byproduct of good design*. Meaning you should never have to explicitly build an API, it should be an "accident".
+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".
 
-Your interface should not dictate the structure of your controllers. Instead, your controllers should represent a collection of resources that your interface can use. The problem is that rails does so much magic, and makes so many assumptions, that sometimes it distorts the basics behind the MVC pattern.
+=== 1. No need to namespace controllers when you have context
 
-This becomes very clear when you try build an interface with {Flex}[http://www.adobe.com/products/flex/]. What this forces you to do is separate your interface from your application. A flex interface communicates with your application via XML. So when you finish an app with a Flex interface you all of a sudden have a "production ready" API as well. Which feels really good. A proper API is the foundation for growing your application. Once this is done the sky is the limit.
+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.
 
-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 scope. Instead, why not have a single controller that is *context aware*. Hence the name *"Contextual Development"*.
+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.
 
-This is great because now you have a single controller that *every* request for the resource must pass through. In the same manner that all database activity passes through ORM models. You can feel confident adding controller specific logic to that resource without having to worry about duplicating it across multiple controllers. Ex: storing the user's IP address with a record.
+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:
 
-If it is any consolation, I am speaking from experience. I recently finished a very complex project using this method and I can say, without a doubt, it's the cleanest application I've built to date.
+  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
 
@@ -49,7 +73,7 @@ Your ResourceController should look something like:
     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 syntax resource_controller came up with is pretty cool:
+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
@@ -76,20 +100,10 @@ Instead of namespacing your controllers, give them context. For example, let's s
 Then in your controller use the context method to make adjustments:
 
   class CommentsController < ResourceController
-    layout :layout_by_context
-    
-    private
-      def layout_by_context
-        case context
-        when :admin
-          "admin"
-        else
-          "application"
-        end
-      end
+    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 you can use the contextual_views option (See Resourcelogic::Context::Config for more info). This will change your default view path to a context subfolder. Ex:
+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
@@ -100,36 +114,54 @@ See the Feature Highlights section below for more options, and the documentation
 
 == 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. Here are just a few:
+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>:
 
-*Class level methods*
+<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 respecive folder
+  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>
 
-*Instance level methods*
+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 object
-  collection                              # current collection
-  object_path                             # /comments/:id
-  new_object_path                         # /comments/new
-  collection_path                         # /comments
+  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                                  # current parent object
-  parent_path                             # /parent_name/:parent_id
-  parent_collection_path                  # /parent_name
-  new_parent_path                         # /parent_name/new
+  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)                       # /sibling_name/:id
-  new_child_path(:child_name)             # /sibling_name/new
-  child_collection_path(:child_name)      # /sibling_name
-  
-All of the above can end with _url instead of _path. See docs for a complete list of available methods.
+  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
+Copyright (c) 2008 {Ben Johnson of Binary Logic}[http://www.binarylogic.com], released under the MIT license

data/Rakefile

@@ -7,14 +7,14 @@ require File.dirname(__FILE__) << "/lib/resourcelogic/version"
 Hoe.new("Resourcelogic", Resourcelogic::Version::STRING) do |p|
   p.name = "resourcelogic"
   p.author = "Ben Johnson of Binary Logic"
-  p.email  = 'bjohnson@binarylogic.com'
-  p.summary = "Making an API a byproduct of good design."
-  p.description = "Making an API a byproduct of good design."
+  p.email  = "bjohnson@binarylogic.com"
+  p.summary = "Removes the need to namespace controllers by adding context and relative url functions among other things."
+  p.description = "Removes the need to namespace controllers by adding context and relative url functions among other things."
   p.url = "http://github.com/binarylogic/resourcelogic"
   p.history_file = "CHANGELOG.rdoc"
   p.readme_file = "README.rdoc"
   p.extra_rdoc_files = ["CHANGELOG.rdoc", "README.rdoc"]
-  p.remote_rdoc_dir = ''
+  p.remote_rdoc_dir = ""
   p.test_globs = ["test/*/test_*.rb", "test/*_test.rb", "test/*/*_test.rb"]
   p.extra_deps = %w(activesupport)
 end

data/lib/resourcelogic.rb

@@ -2,13 +2,16 @@ require File.dirname(__FILE__) + "/resourcelogic/version"
 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

@@ -33,7 +33,7 @@ module Resourcelogic # :nodoc:
         write_inheritable_attribute accessor_name, start_value
         
         class_eval <<-"end_eval", __FILE__, __LINE__
-          def self.#{accessor_name}(&block)
+          def self.#{accessor_name}(context = :root, &block)
             read_inheritable_attribute(:#{accessor_name}).instance_eval(&block) if block_given?
             read_inheritable_attribute(:#{accessor_name})
           end

data/lib/resourcelogic/actions.rb

@@ -1,48 +1,26 @@
 module Resourcelogic
   module Actions
     ACTIONS           = [:index, :show, :new_action, :create, :edit, :update, :destroy].freeze
-    FAILABLE_ACTIONS  = ACTIONS - [:index, :new_action, :edit].freeze
+    FAILABLE_ACTIONS  = ACTIONS - [:index, :new_action, :edit, :destroy].freeze
     
     def self.included(klass)
       klass.class_eval do
-        extend Config
         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 Config
-      def actions(*opts)
-        config = {}
-        config.merge!(opts.pop) if opts.last.is_a?(Hash)
-        
-        all_actions = (false && singleton? ? Resourcelogic::SINGLETON_ACTIONS : Resourcelogic::Actions::ACTIONS) - [:new_action] + [:new]
-        
-        actions_to_remove = []
-        if opts.first == :none
-          actions_to_remove = all_actions
-        else
-          actions_to_remove += all_actions - opts unless opts.first == :all
-          actions_to_remove += [*config[:except]] if config[:except]
-          actions_to_remove.uniq!
-        end
-
-        actions_to_remove.each { |action| undef_method(action) if method_defined?(action) }
-      end
-    end
-    
     module Methods
       def new
-        build_object
         load_object
         before :new_action
         response_for :new_action
       end
-    
+      
       def create
-        build_object
         load_object
         before :create
         if object.save
@@ -55,16 +33,16 @@ module Resourcelogic
           response_for :create_fails
         end
       end
-    
+      
       def edit
         load_object
         before :edit
         response_for :edit
       end
-
+      
       def update
         load_object
-        object.attributes = object_params
+        object.attributes = attributes
         before :update
         if object.save
           after :update
@@ -76,7 +54,7 @@ module Resourcelogic
           response_for :update_fails
         end
       end
-
+      
       def destroy
         load_object
         before :destroy
@@ -84,12 +62,8 @@ module Resourcelogic
         after :destroy
         set_flash :destroy
         response_for :destroy
-      rescue DestroyNotAllowed
-        after :destroy_fails
-        set_flash :destroy_fails
-        response_for :destroy_fails
       end
-    
+      
       def show
         load_object
         before :show
@@ -97,7 +71,7 @@ module Resourcelogic
       rescue ActiveRecord::RecordNotFound
         response_for :show_fails
       end
-    
+      
       def index
         load_collection
         before :index
@@ -121,26 +95,26 @@ module Resourcelogic
           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)
@@ -148,7 +122,7 @@ module Resourcelogic
             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)
@@ -156,7 +130,7 @@ module Resourcelogic
             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.
@@ -165,14 +139,14 @@ module Resourcelogic
           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
@@ -182,20 +156,13 @@ module Resourcelogic
           instance_variable_set "@#{parent_model_name}", parent_object if parent?
         end
         
-        def build_object
-          return @object if @object
-          @object = end_of_association_chain.send parent? ? :build : :new
-          @object.attributes = object_params
-          @object
-        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

data/lib/resourcelogic/base.rb

@@ -3,11 +3,13 @@ module Resourcelogic # :nodoc:
     def self.included(klass)
       klass.class_eval do
         extend ClassMethods
+        include InstanceMethods
       end
     end
     
     module ClassMethods
       def acts_as_resource(&block)
+        resourceful(true)
         yield self if block_given?
         acts_as_resource_modules.each { |mod| include mod }
         init_default_actions
@@ -65,13 +67,21 @@ module Resourcelogic # :nodoc:
         acts_as_resource_modules
       end
       
+      def resourceful(value = nil)
+        rw_config(:resourceful, value, false)
+      end
+      
+      def resourceful?
+        resourceful == true
+      end
+      
       private
         def acts_as_resource_modules
           key = :acts_as_resource_modules
           inheritable_attributes.include?(key) ? read_inheritable_attribute(key) : []
         end
         
-        def config(key, value, default_value = nil, read_value = nil)
+        def rw_config(key, value, default_value = nil, read_value = nil)
           if value == read_value
             inheritable_attributes.include?(key) ? read_inheritable_attribute(key) : default_value
           else
@@ -79,6 +89,21 @@ module Resourcelogic # :nodoc:
           end
         end
     end
+    
+    module InstanceMethods
+      def self.included(klass)
+        klass.helper_method :resourceful?, :section
+      end
+      
+      def resourceful?
+        self.class.resourceful?
+      end
+      
+      def section
+        section = request.path.split("/")[1]
+        section && section.to_sym
+      end
+    end
   end
 end
 
@@ -90,11 +115,16 @@ if defined?(::ActionController)
       include Resourcelogic::Actions
       include Resourcelogic::Child
       include Resourcelogic::Context
-      include Resourcelogic::Parent
+      include Resourcelogic::Scope
       include Resourcelogic::Self
       include Resourcelogic::Sibling
-      include Resourcelogic::Singleton
+      include Resourcelogic::SubViews
       include Resourcelogic::Urligence
+      
+      # Need to be loaded last to override methods
+      include Resourcelogic::Parent
+      include Resourcelogic::Aliases
+       include Resourcelogic::Singleton
     end
   end
 end