aeonscope-btech_rest 0.2.0

data/CHANGELOG.rdoc

@@ -0,0 +1,5 @@
+v0.1.0 Initial version.
+v0.2.0 Fixed a bug where a resource with no namespace(s) would result in double slashed prefixes (i.e. "//").
+       Added a resource breadcrumb helper.
+       Added unobtrusive jQuery support.
+

data/LICENSE.rdoc

@@ -0,0 +1,20 @@
+Copyright (c) 2008, 2009 Berserk Technologies
+
+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,114 @@
+= Overview
+
+Easily adhere to DRY principals and add default REST functionality to your controllers.  This means you can write code
+like this:
+
+	class Posts < ApplicationController
+		include BTech::Rest 
+	end
+
+...and you will automatically have the following REST actions:
+
+* index
+* show
+* new
+* edit
+* create
+* update
+* destroy
+
+How is that for being DRY[http://en.wikipedia.org/wiki/DRY]?  Read on to learn more.
+
+= License
+
+Copyright (c) 2008-2009 {Berserk Technologies}[http://www.berserktech.com].
+See the included LICENSE[link:files/LICENSE_rdoc.html] file for more info.
+
+= History
+
+See the CHANGELOG[link:files/CHANGELOG_rdoc.html] file for more info.
+
+= Requirements
+
+1. Knowledge of the {Representational State Transfer (REST)}[http://en.wikipedia.com/wiki/REST]. Download and read {RESTful Rails}[http://www.b-simple.de/documents] if you need further info.
+2. mislav-will_paginate[http://github.com/mislav/will_paginate/tree/master] gem. This is automatically installed/updated for you unless the correct version is detected.
+
+= Installation
+
+Type the following from the command line to install:
+
+* <b>MacOS/Linux</b>: sudo gem install btech_rest
+* *Windows*: gem install btech_rest
+
+Type the following from the command line to setup:
+
+* script/generate rest_setup
+
+= Usage
+
+As mentioned in the overview, simply add the following line of code to your controller(s) to make them RESTful:
+
+	include BTech::Rest
+	
+Example:
+
+	class Posts < ApplicationController
+		include BTech::Rest 
+	end
+
+To customize the RESTful behavior of your controller, use any combination of these three macros:
+
+* belongs_to[link:classes/BTech/Rest/ClassMethods.html] - Enables resource nesting where a controller can belong to a parent controller (i.e. http://www.example.com/posts/1/comments/2). This behavior is similar to the ActiveRecord belongs_to[http://apidock.com/rails/ActiveRecord/Associations/ClassMethods/belongs_to/] macro.
+* resource_options[link:classes/BTech/Rest/ClassMethods.html] - Allows you to customize the default behavior of your controller(s). There is a lot you can do with this, so follow the link and read the method comments to learn more.
+* disabled_actions[link:classes/BTech/Rest/ClassMethods.html] - Allows you to disable any of the default REST actions. Follow the link to learn more.
+
+Example:
+
+	class Comments < ApplicationController
+		include BTech::Rest
+		belongs_to :posts
+		resource_options :label => "My Wicked Comments"
+		disabled_actions :show, :destroy
+	end
+
+Here is the breakdown, line-by-line, of the example shown above:
+
+1. Enables restful behavior.
+2. Identifies the controller as a nested resource of posts.
+3. Instead of using the default label "Comments", a customized label of "My Wicked Comments" is used instead.
+4. The "show" and "destroy" actions are disabled which means only the following actions will work:  index, new, edit, create, and update.
+
+Using the post and comment controller relationship as defined above, we can break this relationship down even further.
+The post (parent) resource would have the following values (in this case, all default values):
+
+* +parent_key+ = N/A
+* +parent_value+ = N/A
+* +parent_resource_method+ = N/A
+* +name+ = "posts"
+* +label+ = "Posts"
+* +controller+ = PostsController
+* +model+ = Post
+* +record+ =  #<Post id: 1, label: "Test", content: "Test", created_at: "2008-10-31 23:59:28", updated_at: "2008-10-31 23:59:28">
+* +namespaces+ = []
+* +show_partial+ = "/posts/show"
+* +new_or_edit_partial+ = "/posts/new_or_edit"
+
+The comment (child) resource would have the following values:
+	
+* +parent_key+ = post_id
+* +parent_value+ = 1
+* +parent_resource_method+ = N/A
+* +name+ = "comments"
+* +label+ = "My Wicked Comments"
+* +controller+ = CommentsController
+* +model+ = Comment
+* +record+ =  #<Post id: 1, post_id: nil, label: "Test", content: "Test", created_at: "2008-10-31 23:59:28", updated_at: "2008-10-31 23:59:28">
+* +namespaces+ = []
+* +show_partial+ = "/comments/show"
+* +new_or_edit_partial+ = "/comments/new_or_edit"
+		
+= Contact/Feedback/Issues
+
+* {Berserk Technologies}[http://www.berserktech.com] - Company web site.
+* Aeonscope[http://www.aeonscope.net] - Personal web site.
+* Twitter[http://www.twitter.com/Aeonscope] - Short bursts of insight and/or noise.

data/VERSION.yml

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

data/lib/actions.rb

@@ -0,0 +1,195 @@
+module BTech
+	module Rest
+	  module Actions
+	    # Default index action.  Feel free to override.
+	    def index
+	      build_resources
+	      if @resources.size > 1
+	        # Records for a nested resource (act on the second-to-last parent).
+	        parent = @resources[@resources.size - 2][:record]
+	        @records = parent.instance_eval("#{@resources.last[:parent_resource_method] || @resources.last[:name]}").paginate :page => params[:page], :per_page => 10
+	      else
+	        # Records for single resource.
+	        @records = @resources.last[:model].paginate :page => params[:page], :per_page => 10
+	      end
+	    end
+
+	    # Default show action.  Feel free to override.
+	    def show
+	      build_resources
+	      render :partial => @resources.last[:show_partial], :layout => true, :locals => {:record => @record, :resources => @resources}
+	    end
+
+	    # Default new action.  Feel free to override.
+	    def new
+	      build_resources
+	      render_new_or_edit
+	    end
+
+	    # Default edit action.  Feel free to override.
+	    def edit
+	      build_resources
+	      render_new_or_edit
+	    end
+
+	    # Default create action.  Feel free to override.
+	    def create
+	      build_resources
+	      if @record.update_attributes params[:record]
+	        redirect_to build_resource_url(@resources)
+	      else
+	        render_new_or_edit
+	      end
+	    end
+
+	    # Default update action.  Feel free to override.
+	    def update
+	      build_resources
+	      if @record.update_attributes params[:record]
+	        redirect_to build_resource_url(@resources)
+	      else
+	        render_new_or_edit
+	      end  
+	    end
+
+	    # Default destroy action.  Feel free to override.
+	    def destroy
+	      build_resources
+	      @record.destroy
+	      @resources.last.delete :record
+	      redirect_to build_resource_url(@resources)
+	    end
+
+	    protected
+
+	    # Convenience method for rendering the new or edit partial.
+	    def render_new_or_edit
+	      render :partial => @resources.last[:new_or_edit_partial], :layout => true, :locals => {:record => @record, :resources => @resources}
+	    end
+
+	    # Builds the RESTful parent URL based on an array of resources.
+	    def build_parent_url resources = []
+				namespaces = resources.last[:namespaces]
+        url = namespaces && !namespaces.empty? ? '/' + resources.last[:namespaces].join('/') : nil
+	      if resources.size > 1
+	        resources.slice(0...resources.size - 1).each do |resource|
+	          url = [url, resource[:name], resource[:parent_id]].join('/')
+	        end
+	      end
+	      url
+	    end    
+
+	    # A convenience method for builing RESTful URLs based on an array of resources with the
+	    # option to override the default action.  This is also defined as a helper method (see base.rb).
+	    def build_resource_url resources = [], action = :index
+	      name = resources.last[:name]
+	      id = resources.last[:record].id if resources.last[:record]
+        parent_url = build_parent_url(resources)
+	      url = parent_url ? [parent_url, name].join('/') : '/' + name
+	      case action
+	        when :show then url = [url, id].compact.join('/')
+	        when :new then url = [url, "new"].compact.join('/')
+	        when :edit then url = [url, id, "edit"].compact.join('/')
+	        when :update then url = [url, id].compact.join('/') if name == name.pluralize
+	        when :destroy then url = [url, id].compact.join('/') if name == name.pluralize
+	      end
+	      logger.debug "Resource URL: #{url}"
+	      url
+	    end    
+
+	    private
+
+	    # Builds all resources for the controller(s).
+	    def build_resources
+	      @resources ||= []
+	      if @resources.empty?
+	        controller_name = self.class.name
+	        add_resource controller_name, @resources
+	        @resources.reverse!
+	      end
+	      # Convenience for holding the current record and for form manipulation.
+	      @record = @resources.last[:record]
+	    end 
+
+			# Convenience method for answering back a properly camelized controller name.
+			def camelize_controller_name name
+				name = name.capitalize.gsub "controller", "Controller"
+				name += "Controller" unless name.include? "Controller"
+				name
+			end
+
+	    # Answers the child or parent controller namespaces (array) and name (string).
+			# Accepts the following argruments:
+			# * *full_name* - The fully namespaced controller (i.e. PostsController) or parent name (i.e. protected_pages).
+			# Usage:
+			# * Input:  Public::PostsController, Output: [Public], "PostsController"
+			# * Input:  member_manage_posts, Output: [Member, Manage], "PostsController"
+			# * Input:  posts, Output: nil, "PostsController"
+			def get_controller_namespaces_and_name full_name
+				if full_name
+					delimiter = full_name.include?("Controller") ? "::" : '_'
+					if full_name.include? delimiter
+				    namespaces = full_name.split delimiter
+						name = camelize_controller_name namespaces.pop
+						return namespaces.collect(&:capitalize), name
+					else
+						return nil, camelize_controller_name(full_name)
+					end
+				end
+			end			
+
+	    # Recursively walks the controller belongs_to hierarchy (if any) adding new resources along the way.
+	    def add_resource controller_name, resources
+	      logger.debug "Adding resource '#{controller_name}' to resources (size = #{resources.size})."
+	      resource = configure_resource controller_name
+	      if resource
+	        resources << resource
+	        # Recursively add parents (if any).
+	        if resource[:controller].methods.include? "parent_resource"
+	          add_resource resource[:controller].parent_resource, resources
+	        end
+	      end
+	    end
+
+	    # Configures a resource via belongs_to name refrence in controller.  By default the controller and model
+	    # are assumed to use the same root name regardless of singular or plural context. 
+	    def configure_resource controller_name
+				namespaces, name = get_controller_namespaces_and_name controller_name
+	      controller = [namespaces, name].compact.join("::").constantize
+        name = name.chomp("Controller").underscore
+	      parent_key = name.singularize + "_id"
+	      resource = controller.resource_options || {}
+	      resource.reverse_merge! :parent_key => parent_key,
+	      :parent_id => params[parent_key],
+	      :name => name,
+	      :controller => controller,
+	      :label => name.capitalize,
+	      :namespaces => (namespaces.collect(&:downcase) if namespaces),
+	      :show_partial => '/' + [namespaces, name, "show"].compact.join('/').downcase,
+	      :new_or_edit_partial => '/' + [namespaces, name, "new_or_edit"].compact.join('/').downcase
+	      begin
+	        resource.reverse_merge! :model => name.singularize.camelize.constantize
+	      rescue NameError
+	        logger.warn "Unable to constantize: " + name
+	      end
+	      add_record resource
+	    end
+
+	    # Adds the current record to the resource based on position in chain.
+	    def add_record resource
+	      if resource[:model]
+	        if params.include? resource[:parent_key]
+	          # Nested parent.
+	          resource[:record] = resource[:model].find resource[:parent_id] if resource[:parent_id]
+	        else
+	          # Single resource and/or end of nested chain.
+	          resource[:record] = params[:id] ? resource[:model].find(params[:id]) : resource[:model].new
+	        end
+	      else
+	        logger.error "Invalid model.  Check that your controller and model are of the same name, otherwise specify the model as a resource option."
+	      end
+	      resource
+	    end
+	  end
+	end	
+end

data/lib/btech_rest.rb

@@ -0,0 +1,14 @@
+require File.dirname(__FILE__) + "/class_methods.rb"
+require File.dirname(__FILE__) + "/actions.rb"
+require File.dirname(__FILE__) + "/resource_helper.rb"
+
+module BTech
+	module Rest
+	  def self.included base
+	    base.extend ClassMethods
+	    base.helper "resource"
+	    base.helper_method :build_resource_url
+	  end
+	  include Actions
+	end
+end

data/lib/class_methods.rb

@@ -0,0 +1,37 @@
+module BTech
+	module Rest
+	  module ClassMethods
+	    # Allows an object to belong to a parent object, thus creating a nested hierarchy. This behaves in a similar
+	    # fashion to the belongs_to ActiveRecord macro.  Accepts the following parameters:
+	    # * *parent* - The parent symbol (including namespaces delimited by underscores). Be sure to reflect singular or plural forms on the name. Example: Public::PostsController, Result: :public_posts
+	    def belongs_to parent
+	      @parent_resource = parent.to_s
+	      class_eval "class << self; attr_accessor :parent_resource end"
+	    end
+
+	    # Allows one to specify the various options for a resource.  The following options are accepted:
+	  	# * *parent_key* - The ID key of the parent resource (for nested resources only).  Defaults to:  <belongs_to name>_id
+	  	# * *parent_value* - The ID value of the parent resource (for nested resources only).  Defaults to the record id.
+	  	# * *parent_resource_method* - The instance method to call for acquiring child resource(s) of the parent (for nested resources only). Example: A post with many comments would be post.comments. Defaults to child resource name.
+	  	# * *name* - The resource name. Defaults to the controller name.
+	  	# * *label* - The resource label. Defaults to the controller name with capitalization.
+	  	# * *controller* - The controller class. Defaults to the current class. You should not need to change this.
+	  	# * *model* - The model class. Defaults to a model of the same name as the controller (minus namespace, suffix, and pluralization of course).
+	  	# * *record* - The record (new or found) related to the resource.
+	  	# * *namespaces* - The namespaces (if any) for routing. Defaults to whatever namespace your controller is using.
+	  	# * *show_partial* - The show partial. Defaults to "/<namspace(s)>/<controller name>/_show".
+	  	# * *new_or_edit_partial* - The new or edit partial. Defaults to "/<namspace(s)>/<controller name>/_new_or_edit".
+	    def resource_options options = {}
+	      @resource_options = options
+	      class_eval "class << self; attr_reader :resource_options end"
+	    end
+
+	    # Allows one to disable any number of default actions.  Accepts the following parameters:
+	    # * *actions* - A variable list of REST action symbols you wish to disable. You may use any of the following: index, show, new, create, edit, update, and/or destroy.
+	    def disabled_actions *actions
+	      actions.uniq!
+	      actions.each {|action| undef_method(action)}
+	    end
+	  end
+	end	
+end

data/lib/resource_helper.rb

@@ -0,0 +1,78 @@
+module ResourceHelper
+  # Displays breadcrumb navigation based on an array of hashes.  Each resource
+  # hash is expected to have the following keys:
+  # * *id* - The resource ID (a.k.a the model ID).
+  # * *label* - The link label for display, otherwise the name is used instead.
+  # * *name* - The name of the resource (a.k.a. the controller).  Also used as the link lable unless a label has been given.
+  # An optional hash of key/values can be supplied, here is what is allowed:
+  # * *separator* - The breadcrumb separator link, defaults to:  '>'
+  def resource_breadcrumbs resources = [], options = {}
+    # Set defaults.
+    breadcrumbs = []
+    options.reverse_merge! :separator => "»"
+    # Process resources.
+    if resources.size > 0
+      url = '/' + resources.first[:namespaces].join('/')
+      parent_id = nil
+      resources.each do |resource|
+        url = [url, parent_id, resource[:name].pluralize].compact.join('/')
+        parent_id = resource[:parent_id]
+        breadcrumbs << link_to(resource[:label], url)
+      end
+    end
+ 		content_for :breadcrumbs, content_tag(:div, :id => "breadcrumbs") {breadcrumbs.compact.join(" #{options[:separator]} ")}
+  end	
+	
+  # Builds the submit path for a new or edit form based on current controller action. This assumes
+  # that the new/create and edit/update forms are always submitted to the same URL.  Accepts the following parameters:
+  # * *resources* - The array of resource hashes.
+  # * *html_options* - The html options for a form (same as form_for[http://apidock.com/rails/ActionView/Helpers/FormHelper/form_for] html options).
+  def build_resource_form_submit resources = [], html_options = {}
+    case params[:action]
+    # New/create flow.
+    when "new" then return :url => build_resource_url(resources, :create), :html => html_options
+    # Validate/create flow.
+    when "create" then return :url => build_resource_url(resources, :create), :html => html_options
+    # Edit/update flow.
+    when "edit" then return :url => build_resource_url(resources, :update), :html => html_options.merge({:method => :put})
+    # Validate/update flow.
+    when "update" then return :url => build_resource_url(resources, :update), :html => html_options.merge({:method => :put})
+    end
+  end
+  
+  # Builds a more descriptive label based on the current controller action.  Accepts the following parameters:
+  # * *label* - The action label.
+  def build_action_label label
+    [params[:action].capitalize, label.singularize].compact.join ' '
+  end
+  
+  # Shows an unobtrusive jQuery link where the UJS event is attached to the link via the "destroy" class.
+  # If JavaScript is disabled then the _show_ action will be called instead of the _destroy_ action. Accepts
+  # the following hash arguments:
+  # * *parent_id* - The ID of the parent element for which the link is a child of. Example: post_1. *NOTE:* The parent ID take precidence over the link ID if defined.
+  # * *id* - The link ID. Example: post_1_link. *NOTE:* The link ID _must_ include the parent ID.
+  # * *label* - The link label. Defaults to "Delete".
+  # * *url* - The REST destroy URL. Example: /posts/1. *NOTE:* The proper HTTP POST request will be handled by the JavaScript.
+  def show_destroy_link options = {}
+    options.reverse_merge! :label => "Delete", :class => "destroy"
+		options[:id] = options[:parent_id] + "_link" if options[:parent_id]
+    content_tag :a, options[:label], :href => options[:url], :id => options[:id], :class => options[:class]
+  end
+
+  # Shows an unobtrusive jQuery link based on an array of resource hashes.  See the show_destroy_link above
+  # for further details. Accepts the following arguments:
+  # * *resources* - The array of resource hashes.
+	def show_destroy_resource_link resources
+		show_destroy_link :parent_id => resources.last[:parent_id], :url => build_resource_url(resources, :destroy)
+	end
+
+  # Shows edit and delete links for resources. *NOTE*: Normally the record being edited is not known when
+  # resources are first assembled. Make sure to add the record to the last resource prior to calling this
+  # method for correct results.  Accepts the following parameters:
+  # * *resources* - The array of resource hashes.
+  def show_edit_and_destroy_resource_links resources
+    html = link_to "Edit", build_resource_url(resources, :edit)
+    html += " | "
+    html += show_destroy_resource_link resources
+  end
+end

data/test/btech_rest_test.rb

@@ -0,0 +1,7 @@
+require 'test_helper'
+
+class Btech::RestTest < Test::Unit::TestCase
+  should "execute some intelligent tests" do
+    flunk "yo, there are no tests here, WTF!?!"
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,10 @@
+require 'rubygems'
+require 'test/unit'
+require 'shoulda'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'btech_rest'
+
+class Test::Unit::TestCase
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification 
+name: aeonscope-btech_rest
+version: !ruby/object:Gem::Version 
+  version: 0.2.0
+platform: ruby
+authors: 
+- Brooke Kuhlmann
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-04-05 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: mislav-will_paginate
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 2.3.7
+    version: 
+description: 
+email: aeonscope@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+- LICENSE.rdoc
+files: 
+- CHANGELOG.rdoc
+- LICENSE.rdoc
+- README.rdoc
+- VERSION.yml
+- lib/actions.rb
+- lib/btech_rest.rb
+- lib/class_methods.rb
+- lib/resource_helper.rb
+- test/btech_rest_test.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://github.com/aeonscope/btech-rest
+post_install_message: 
+rdoc_options: 
+- CHANGELOG.rdoc
+- --inline-source
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: 1.8.6
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Easily adhere to DRY principals and add default REST functionality to your controllers.
+test_files: []
+