super_resources 1.0.0.rc1

data/.gitignore

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

data/Gemfile

@@ -0,0 +1,8 @@
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rails', '~> 3.1'
+
+gem 'sqlite3'
+gem 'rspec-rails'

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2012, 2013 Habanero Software Pty Limited
+
+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,215 @@
+# SuperResources
+
+SuperResources DRYs up your controller code by abstracting your controller's strandard RESTful actions and by providing 
+standard helpers to access the controller's target resource(s) in a consistent way across all controllers. More than that,
+SuperResources exploits the application's routes to provide simplified path helpers for nested resources.
+
+With SuperResources, in the great majority of common REST situations, you can use the same resource helpers and path helpers, 
+regardless of the the specific type of resource or how it is nested, even if the resource is nested under many other resources.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'super_resources'
+
+And then execute:
+
+    bundle install
+
+Or install it yourself as:
+
+    gem install super_resources
+
+## Usage
+
+To gain all the standard RESTful actions, just `include SuperResources::Controller` in your controller:
+
+    class OrganizationUnitsController < ApplicationController
+      include SuperResources::Controller
+    end
+
+### Resource Helper Methods
+
+SuperResources provides helper methods that you can use directly in the controller, views or helper methods:
+
+    resource
+    collection
+
+For member actions, `resource` answers a single object that the RESTFUL is operating on.
+For collection actions (i.e `index1), `collection` answer a scoped collection of objects.
+
+SuperResources does away with specifically named instance variables, such as those created by standard scaffolds. For example, in the example above, SuperResources does not give you `@organization_unit` or `@organization_units` for free. You won't need them in the common cases. Using `resource` and `collection` in every controller makes for easier coding and maintenance.
+
+### Path Helper Methods
+
+SuperResources provides a set of vastly simplified path helpers.
+
+    collection_path #=> path to the resource's index action
+    resource_path(object = resource)
+    new_resource_path
+    edit_resource_path(object = resource)
+
+Note that the helper methods that require an input argument, assumes the current resource by default, so you don't have to pass it in.
+
+#### These Helper Methods Work Even When the Resource is Nested
+
+Because SuperResources uses the metadata created by your routes declarations to work out whether the resource has been nested and if so, automatically uses the nesting objects to build complete paths. This relieves you of passing in an array to the path helper.
+
+With this feature alone, SuperResources cleans up your code and makes it more reusable. For example, the same code can be used when you 
+have a resource that is nested inside multiple other objects. SuperResources dynamically works out the nesting that applies in each case.
+
+## Nested Resource
+
+Let's face it: deailing with nested resources has always been a pain. All that fiddling about, getting the path names and inputs right. Chane the nesting and you have to go through and chaneg all your path calls too. Then, if you have a resource that can be nested within multiple other resources, such as when you have an associative object and you want to navigate to it from any of it associations, the permutations become very complex.
+
+It should be much easier, especially when you take routes into account. If I have an action that is matched to this route:
+
+    /notes/:note_id/pages/:id
+
+then shouldn't I have paths available that can work out the nesting context, so that I don't hard code it?
+
+SuperResources does this. For example, including SuperResources in `PagesController` will allow me to simply call, 
+for example, `edit_resource_path` and the code has been actioned through the above route, the nesting with a Note identified by `:note_id` will be assumed. Even better, if the same code is actioned by another route with different nesting, SuperResources will get that right too.
+
+If you need, such as when you want to link 'outside the nest' as it were, you still have `note_page_path(note, page)` available to you.
+
+### Parent Helper Method
+
+Sometimes you want to use the object that is nesting your resource, such as when you want to customize a redirect. SuperResources provides 
+`parent` to answer that object. For example given, the following route:
+
+    /notes/:note_id/pages/:id
+
+
+calling `parent` will answer a Note object with an id of `:note_id`. 
+
+For deeper nests, the immediately nested object is always answered by `parent`. For example, given this route:
+
+    /authors/:author_id/notes/:note_id/pages/:id
+
+calling `parent` will still answer a Note object with an id of `:note_id`. 
+
+### Accessing Route Objects
+
+Any nested route implies a component hierarchy of objects. SuperResources allows you to access these objects bye a convenient name.
+
+For example, given this route:
+
+    /authors/:author_id/notes/:note_id/pages/:id
+
+you can make these calls:
+
+  author  #=> Author with an id of :author_id
+  note    #=> Note with an id of :note_id
+  page    #=> Page with an id of :id
+
+An example of a place where you will want these, is in a layout template that presents information about the nesting objects. For example, you may want to show a page inside an author layout template. The author layout template will present information about the author. In this case, the layout will be used in the context of `PagesController`, so you can't refer to `resource` in the layout, since it will answer the page, not the author. You need some way to arbitrarily refer to the author.  Being able to call `author` provides this.
+
+## Adapting and Customising
+
+### Resource Class
+
+SuperResources derives the class of the target resource from the controller name. For example, `OrganizationUnitsController` operates, by default, on resources of the class `OrganizationUnit`. If you want to change this, redefine hotspot method `resource_class`, for example:
+
+    class TeamsController < ApplicationController
+      include SuperResources::Controller
+
+      protected
+
+      def resource_class
+        OrganizationUnit
+      end
+    end
+
+### Resource Helper Methods
+
+Yes, you can adapt these to suit your needs. 
+
+Both `resource` and `collection` accept a block, which SuperResources uses to stitch into its internal implementation, so tht any subsequent calls to these helpers uses your implementation.
+The block for `resource` shall answer a single instance of the resource class and the block for `collection` shall answer an array of instances of the resource class. 
+
+For example, if you wanted 'TeamsController#collection' to return only those teams that the current user has joined, you would write an implementation of `collection` that calls its super, passing a block the evalautes to the right collection:
+
+    def collection
+      super { resource_class.joined_by(current_user) }
+    end
+
+If that looks strange, bear in mind it's been designed so that you don't need to know how SuperResources internally uses your preferred implementation.
+
+### Finder Method
+
+Before being able to use the result of `resource`, SuperResources may need to find it. The canonical way to do this is to do:
+
+  resource_class.find(:params[:id])
+
+While SuperResource uses the `find` method as the default, you can choose another finder method by redefining `finder_method`. For example:
+
+    class PagesController < ApplicationController
+
+      protected
+
+      def finder_method
+        :find_by_position
+      end
+    end
+
+### Builder Method
+
+SuperResources extracts the construction of a new resource into the `build_resource` method. If you need to create a new resource, say in a special action, use 'build_resource' so that SuperResource can also keep track of it (for example, make sure that `resource' answers the built object).
+
+If you need to do specialized work for the build, pass the a block to `build_resource` that evaluates to an object with the state you need. For example:
+
+    build_resource do
+      resource_class.new do |p|
+        # initialize the state here
+      end
+    end
+
+More commonly, you would redefine the whole method so that it always behaves the same way for its enclosing controller:
+
+    def build_resource
+      super do
+        resource_class.new do |p|
+          # initialize the state here
+        end
+      end
+    end
+
+### Redefining Actions
+
+Yes, you can. All actions defined by SuperResources use responders and accept parameters to pass to `respond_with`, so customizing these parameters is a common adaptation.
+
+For example, suppose that after creating a comment, you want to redirect to an index of comments that apply to the same parent. Adapt teh action like this:
+
+    def create
+      super :location => polymorphic_url([ parent, :comments ])
+    end
+
+Anything you can pass to `respond_with`, you can pass to he super call, including a block.
+
+You could, of course, completely redefine an action:
+
+    def new
+      # knock yourself out
+    end
+
+### Defining Actions
+
+Just do it. Declare them in your controller and match them in routes. All the SuperResources helpers are still available to you.
+
+## Acknowledgments
+
+SuperResources would never have happened without InheritedResources [https://github.com/josevalim/inherited_resources] existing first.
+We preferred the idea of abstracting and extracting RESTful actions out of all our controllers and we're not so keen on scaffolds generating
+un-DRY code. We used InheritedResources in a production deployed application [meetlinkshare.com], gained some experience and decided we wanted an even DRYer tool.
+
+The basic mechanics of SuperResources was hacked out during Rails Camp 12 in Tasmania, Australia and was subsequently applied to MeetLinkShare.
+
+## 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

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/super_resources/actions.rb

@@ -0,0 +1,49 @@
+module SuperResources
+  module Actions
+    extend ActiveSupport::Concern
+
+    included do
+      respond_to :html
+    end
+
+    def index(options = {}, &block)
+      respond_with(*(with_chain(collection) << options), &block)
+    end
+
+    def show(options = {}, &block)
+      respond_with(*(with_chain(resource) << options), &block)
+    end
+
+    def new(options = {}, &block)
+      respond_with(*(with_chain(build_resource) << options), &block)
+    end
+
+    def edit(options = {}, &block)
+      respond_with(*(with_chain(resource) << options), &block)
+    end
+
+    def create(options = {}, &block)
+      if create_resource(resource_params)
+        options[:location] ||= resource_url
+      end
+
+      respond_with(*(with_chain(resource) << options), &block)
+    end
+
+    def update(options = {}, &block)
+      if update_resource(resource_params)
+        options[:location] ||= resource_url
+      end
+
+      respond_with(*(with_chain(resource) << options), &block)
+    end
+
+    def destroy(options = {}, &block)
+      if destroy_resource
+        options[:location] ||= collection_url
+      end
+
+      respond_with(*(with_chain(resource) << options), &block)
+    end
+  end
+end

data/lib/super_resources/cancan.rb

@@ -0,0 +1,15 @@
+module SuperController
+  module Cancan
+    extend ActiveSupport::Concern
+
+    included do
+      before_filter :authorize_resource
+    end
+
+    protected
+
+    def authorize_resource
+      #authorize! action_name.to_sym, resource
+    end
+  end
+end

data/lib/super_resources/controller.rb

@@ -0,0 +1,12 @@
+module SuperResources
+  module Controller
+    extend ActiveSupport::Concern
+
+    included do
+    	include Actions
+	    include Nesting
+	    include HasScope
+	    include URLHelpers	    
+	  end
+  end
+end

data/lib/super_resources/has_scope.rb

@@ -0,0 +1,9 @@
+module SuperResources
+  module HasScope
+    protected
+
+    def end_of_association_chain
+      respond_to?(:apply_scopes) ? apply_scopes(super) : super
+    end
+  end
+end

data/lib/super_resources/nesting.rb

@@ -0,0 +1,110 @@
+module SuperResources
+  module Nesting
+    extend ActiveSupport::Concern
+    include Resources
+
+    included do
+      helper_method :association_chain, :with_chain, :method_missing, :respond_to?
+    end
+
+    def respond_to?(m, *args)
+      m.in?(symbols_for_association_chain) ? true : super
+    end
+
+    protected
+
+    def method_missing(m, *args, &block)
+      case
+      when m == resource_params_name
+        resource
+      when i = symbols_for_association_chain.index(m)
+        association_chain[i]
+      else
+        super
+      end
+    end
+
+    def collection(&block)
+      if block_given?
+        @collection = yield
+      else
+        @collection ||= end_of_association_chain
+      end
+    end
+
+    def resource(&block)
+      if block_given?
+        @resource = yield
+      else
+        @resource ||= end_of_association_chain.send(finder_method, params[:id])
+      end
+    end
+
+    def build_resource(&block)
+      if block_given?
+        @resource = yield
+      else
+        @resource ||= end_of_association_chain.build(resource_params)
+      end
+    end
+
+    def nested?
+      association_chain.any?
+    end
+
+    def parent
+      association_chain.last
+    end
+
+    def end_of_association_chain
+      nested? ? parent.send(resource_collection_name) : resource_class.scoped
+    end
+
+    def association_chain
+      @association_chain ||=
+        symbols_for_association_chain.inject([]) do |chain, symbol|
+          chain << chain_link(symbol, chain.last)
+        end
+    end
+
+    def chain_link(symbol, previous_link)
+      link = if previous_link
+        previous_link.send(symbol.to_s.pluralize.to_sym)
+      else
+        symbol.to_s.classify.safe_constantize
+      end
+
+      link.find(params[:"#{symbol}_id"])
+    end
+
+    def symbols_for_association_chain
+      @symbols_for_association_chain ||=
+        route.parts \
+             .select { |p| p.to_s =~ %r(_id$) } \
+             .map    { |p| p.to_s.gsub(/_id$/, '').to_sym }
+      @symbols_for_association_chain
+    end
+
+    def with_chain(object)
+      association_chain + [ object ]
+    end
+
+    def route
+      @route ||= begin
+        routes.formatter.send(:match_route, nil, path_parameters) do |route|
+          # TODO: don't assume the first route is good, validate!
+          # TODO: don't use break
+          break route
+        end
+      end
+    end
+
+    def routes
+      request.env['action_dispatch.routes']
+    end
+
+    def path_parameters
+      request.env['action_dispatch.request.path_parameters'].symbolize_keys
+    end
+  end
+end

data/lib/super_resources/resources.rb

@@ -0,0 +1,88 @@
+module SuperResources
+  module Resources
+    extend ActiveSupport::Concern
+
+    included do
+      helper_method :collection, :collection=, :resource, :resource=, :resource_class, :parent, :nested?
+    end
+
+    protected
+
+    def resource_class
+      controller_name.classify.singularize.safe_constantize
+    end
+
+    def resource_instance_name
+      controller_name.singularize.to_sym
+    end
+
+    def resource_params_name
+      resource_instance_name
+    end
+
+    def resource_collection_name
+      controller_name.to_sym
+    end
+
+    def collection(&block)
+      if block_given?
+        @collection = yield
+      else
+        @collection ||= resource_class.scoped
+      end
+    end
+
+    def collection=(c)
+      @collection = c
+    end
+
+    def resource(&block)
+      if block_given?
+        @resource = yield
+      else
+        @resource ||= resource_class.send(finder_method, params[:id])
+      end
+    end
+
+    def resource=(r)
+      @resource = r
+    end
+
+    def finder_method
+      :find
+    end
+
+    def nested?
+      false
+    end
+
+    def parent
+      nil
+    end
+
+    def build_resource(&block)
+      if block_given?
+        @resource = yield
+      else
+        @resource ||= resource_class.new(resource_params)
+      end
+    end
+
+    def create_resource(attributes)
+      build_resource.attributes = attributes
+      resource.save
+    end
+
+    def update_resource(attributes)
+      resource.update_attributes(attributes)
+    end
+  
+    def resource_params
+      params[resource_params_name] || {}
+    end
+
+    def destroy_resource
+      resource.destroy
+    end
+  end
+end

data/lib/super_resources/url_helpers.rb

@@ -0,0 +1,61 @@
+module SuperResources
+  module URLHelpers
+    extend ActiveSupport::Concern
+
+    included do
+      helper_method :collection_path, :resource_path, :new_resource_path,
+                    :edit_resource_path
+    end
+
+    protected
+
+    def full_association_chain_symbols
+      symbols_for_association_chain + [resource_instance_name]
+    end
+
+    def collection_route
+      chain = symbols_for_association_chain + [resource_collection_name]
+      :"#{chain.join('_')}_url"
+    end
+
+    def resource_route
+      :"#{full_association_chain_symbols.join('_')}_url"
+    end
+
+    def new_resource_route
+      :"new_#{resource_route}"
+    end
+
+    def edit_resource_route
+      :"edit_#{resource_route}"
+    end
+
+    def collection_url
+      send(collection_route, *association_chain)
+    end
+
+    alias_method :collection_path, :collection_url
+
+    def resource_url(object = resource)
+      if object.persisted?
+        send(resource_route, *(association_chain + [object]))
+      else
+        collection_url # probably a new action
+      end
+    end
+
+    alias_method :resource_path, :resource_url
+
+    def new_resource_url
+      send(new_resource_route, *association_chain)
+    end
+
+    alias_method :new_resource_path, :new_resource_url
+
+    def edit_resource_url(object = resource)
+      send(edit_resource_route, *(association_chain + [object]))
+    end
+
+    alias_method :edit_resource_path, :edit_resource_url
+  end
+end

data/lib/super_resources/version.rb

@@ -0,0 +1,3 @@
+module SuperResources
+  VERSION = "1.0.0.rc1"
+end

data/lib/super_resources.rb

@@ -0,0 +1,11 @@
+module SuperResources
+  autoload :Actions,    "super_resources/actions"
+  autoload :Controller, "super_resources/controller"
+  autoload :Nesting,    "super_resources/nesting"
+  autoload :Resources,  "super_resources/resources"
+  autoload :URLHelpers, "super_resources/url_helpers"
+  autoload :Version,    "super_resources/version"
+
+  autoload :HasScope,   "super_resources/has_scope"
+  autoload :Cancan,     "super_resources/cancan"
+end