aeonscope-rest 1.0.0 → 1.1.0

data/CHANGELOG.rdoc

@@ -1,3 +1,28 @@
+= v1.1.0
+
+* Clarified the readme documentation.
+* Updated the JavaScript code so that events are bound for current and future instances instead of just once.
+* Fixed a JavaScript bug where deleting nested inputs on a new form would cause an exception.
+* Updated the JavaScript code so that new records are initially hidden.
+* Updated the JavaScript code so the last record of a form is not deleted. Contents will be cleared and hidden (if last element).
+* Applied fade in/out effects when adding/destroying input forms.
+* Removed the hiding of the delete link via the various resource helpers.
+* Modified the JavaScript incrementNumber(string, position) function for better handling of complex nested Rails model forms.
+* Renamed all forms of the "new" action UJS classes to a single "new" class. Use the data-type attribute to distinguish type.
+* Applied "group" and "record" classes to distinguish between a group of records and a single record. Very handy for creating and/or destroying form elements.
+* Renamed the various resource helpers to be aware of input elements (this affects the destroy helpers mostly).
+* Added default option support for the Will Paginate gem requirement (use config/initializers/pagination.rb to change settings).
+* Renamed all "show_" helpers to "render_" helpers.
+* Added a render_show_link helper.
+* Added a render_new_link helper.
+* Added a render_edit_link helper.
+* Added icons for show, new, edit, and destroy actions. All corresponding helpers default to these icons.
+* Changed the rendering of partials to templates for all REST actions.
+* Added the ability to supply an index template if you wish to override the default index action behavior.
+* Added basic AJAX handling for the destroy action so that a response can be sent back to the JavaScript caller.
+* Moved all JavaScript REST functionality into a proper jQuery plugin.
+* Renamed the "ujs_setup" generator to "rest_setup".
+
 = v1.0.0
 
 * Initial version.

data/README.rdoc

@@ -1,12 +1,12 @@
 = Overview
 
-Enables default REST functionality, more than what you get with Rails out-of-the-box, and keeps your code DRY. This means you can write code like this:
+Enables default REST functionality, more than what you get with Rails out-of-the-box, to keep your code DRY. This means you can write code like this:
 
   class Posts < ApplicationController
     include Rest 
   end
 
-Which would automatically yield the following REST actions:
+Which would automatically add the following REST actions to your controller:
 
 * index
 * show
@@ -29,9 +29,9 @@ See the CHANGELOG file for more info.
 
 = Requirements
 
-1. {Ruby on Rails}[http://rubyonrails.org] (automatically installed for you if you don't have 2.3.x or higher).
-2. mislav-will_paginate[http://github.com/mislav/will_paginate/tree/master] gem (automatically installed for you).
-3. 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.
+1. Knowledge of {Representational State Transfer (REST)}[http://en.wikipedia.com/wiki/REST].
+2. {Ruby on Rails}[http://rubyonrails.org] (automatically installed for you if you don't have 2.3.x or higher).
+3. mislav-will_paginate[http://github.com/mislav/will_paginate/tree/master] gem (automatically installed for you).
 
 = Installation
 
@@ -42,11 +42,11 @@ Type the following from the command line to install:
 
 Update your environment.rb file to include the new gem:
 
-* config.gem "rest"
+* config.gem "aeonscope-rest", :lib => "rest", :source => "http://gems.github.com"
 
-To apply unobtrusive jQuery support, run the following generator (TIP: suffix the command line with -h option for usage):
+Then run the following generator to complete setup (TIP: suffix the command line with -h option for usage):
 
-* script/generate ujs_setup
+* script/generate rest_setup
 
 = Usage
 
@@ -60,7 +60,11 @@ Example:
     include Rest 
   end
 
-This will automatically create the seven REST actions (index, show, new, create, edit, update, and destroy) for your controller. The model (i.e. Post) and model instance (i.e. @posts or @post depending on the action) are automatically determined from the controller name and created for you as well which means you can immediately write the following code in your views:
+This will automatically create the seven REST actions (index, show, new, create, edit, update, and destroy) for your controller. The model (i.e. Post) and model instance (i.e. @posts or @post depending on the action) are automatically determined from the controller name. Just make sure your routes are updated to reflect the new resource. For example:
+
+  map.resources :posts
+
+This means you can immediately write the following code in your views:
 
 <b>index.html.erb</b>
 
@@ -91,7 +95,7 @@ This will automatically create the seven REST actions (index, show, new, create,
 
   <p><%= link_to "Back", :back %></p>
 
-<b>new.html.erb</b>
+<b>new_or_edit.html.erb</b>
 
   <% form_for @post do |form| %>
     <%= form.error_messages :header_data => :strong, :header_message => "Error" %>
@@ -106,14 +110,10 @@ This will automatically create the seven REST actions (index, show, new, create,
       <%= form.text_area :content %>
     </div>
 
-    <div><%= show_submit_and_cancel :cancel_options => posts_path %></div>
+    <div><%= submit_tag "Save", :class => "form-button" %> or <%= link_to "Cancel", posts_path %></div>
  <% end %>
 
-<b>edit.html.erb</b>
-
-Use the same code as shown in the new.html.erb view above. ;-) The Rails form_for helper will automatically determine what action to take as shown in the following code:
-
-  <% form_for @post do |form| %>
+Notice how the form_for[http://apidock.com/rails/ActionView/Helpers/FormHelper/form_for] helper method automatically determines what controller action to use based off the model object (i.e. @post). This allows you to use the same form for new and edit actions by creating one template called: new_or_edit.html.erb. Nice, eh?
 
 To customize the RESTful behavior of your controller, use any combination of these three macros:
 
@@ -133,7 +133,7 @@ Example:
 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.
+2. Identifies the comments controller as a child of the posts controller (i.e. nested resource).
 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.
 
@@ -142,28 +142,40 @@ Using the post and comment controller relationship as defined above, we can brea
 * *parent_key* = N/A
 * *parent_value* = N/A
 * *parent_resource_method* = N/A
-* *name* = "posts"
+* *controller_class* = PostsController
+* *controller_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">
+* *model_class* = Post
+* *model_name* = post
+* *model_object* = @post #<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"
+* *index_template* = "/posts/index"
+* *show_template* = "/posts/show"
+* *new_or_edit_template* = "/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"
+* *controller_class* = CommentsController
+* *controller_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">
+* *model_class* = Comment
+* *model_name* = comment
+* *model_object* = @comment #<Comment id: 1, 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* = "/comments/show"
-* *new_or_edit_partial* = "/comments/new_or_edit"
+* *index_template* = "/comments/index"
+* *show_template* = "/comments/show"
+* *new_or_edit_template* = "/comments/new_or_edit"
+
+Resources
+
+To learn more about REST in Rails, check out the following:
+
+* {RESTful Rails}[http://www.b-simple.de/documents] - A PDF work downloading and reading that inspired me to write this gem.
+* {Rails Routing}[http://guides.rails.info/routing.html] - The definitive guide to RESTful routing in Rails.
+* {Taking Things Too Far}[http://www.therailsway.com/2009/6/22/taking-things-too-far-rest] - A good read on knowing when you have gone too far with REST API.
 		
 = Contact/Feedback/Issues
 

data/Rakefile

@@ -5,14 +5,14 @@ begin
   require 'jeweler'
   Jeweler::Tasks.new do |gem|
     gem.name = "rest"
-    gem.summary = "Enables default REST functionality, more than what you get with Rails out-of-the-box, and keeps your code DRY."
+    gem.summary = "Enables default REST functionality, UJS support (jQuery), and keeps your code DRY."
     gem.description = "Ruby on Rails supports RESTful routing out-of-the-box. However, as you move along, you will often find yourself repeating the code for the seven REST actions: index, show, new, create, edit, update, destroy. This gem allows you to get all of the code for free by simply typing 'include Rest' at top of your controller code. That's it! Even better, you can have nested resources as well by adding a 'belongs_to' statement to your controllers much like you would for ActiveRecord models. This is just the tip of the iceburg so make sure to read the RDoc for more info."
     gem.authors = ["Brooke Kuhlmann"]
     gem.email = "aeonscope@gmail.com"
     gem.homepage = "http://github.com/aeonscope/rest"
 		gem.required_ruby_version = ">= 1.8.6"
 		gem.add_dependency "rails", ">= 2.3.2"
-		gem.add_dependency "mislav-will_paginate", ">= 2.3.7"
+		gem.add_dependency "mislav-will_paginate", ">= 2.3.10"
 		gem.rdoc_options << "CHANGELOG.rdoc"
 		gem.files = FileList["[A-Z]*", "{bin,lib,generators,rails_generators,test,spec}/**/*"]
   end

data/VERSION.yml

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

data/lib/class_methods.rb

@@ -1,35 +1,35 @@
 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
+    # Describes the parent/child relationship of a resource. The behavior is similar to the belongs_to macro in ActiveRecord.
+    # * *parent* - The parent symbol (including namespaces delimited by underscores). 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".
+    # Allows one to specify the various options for a resource.
+  	# * *parent_key* - Optional. The ID key of the parent resource (for nested resources only).  Defaults to:  <belongs_to name>_id
+  	# * *parent_value* - Optional. The ID value of the parent resource (for nested resources only).  Defaults to the record id.
+  	# * *parent_resource_method* - Optional. 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.
+  	# * *controller_class* - Optional. The controller class (for nested resources only). Defaults to the current class. You should never need to use this.
+  	# * *controller_name* - Optional. The controller name. Defaults to the controller class name minus the "Controller" suffix (same behavior as used in routing). Example: PostsController => posts
+  	# * *label* - Optional. The resource label. Defaults to the controller name with capitalization. Example: posts => Posts.
+  	# * *model_class* - Optional. The model class. Defaults to the same name as the controller (minus namespace, suffix, and pluralization of course). Example: PostsController => Post
+  	# * *model_name* - Optional. The model name. Defaults to the singularized version of the :controller_name. Example: posts (controller_name) => post (model_name).
+  	# * *model_object* - Optional. The model object. The name defaults to the model_name. Example: post (model_name) => @post (model object). You should never need to use this.
+  	# * *namespaces* - Optional. The namespaces (if any) for routing. Defaults to whatever namespace your controller is using.
+  	# * *index_template* - Optional. The index template. Defaults to "/<namspace(s)>/<controller name>/index".
+  	# * *show_template* - Optional. The show template. Defaults to "/<namspace(s)>/<controller name>/show".
+  	# * *new_or_edit_template* - Optional. The new or edit template. 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:
+    # Allows one to disable any number of default actions.
     # * *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.each {|action| undef_method action}
     end
   end
 end	
-

data/lib/instance_methods.rb

@@ -0,0 +1,261 @@
+module Rest
+  module InstanceMethods
+		# Default index action.
+		# See config/initializers/pagination.rb to change default pagination settings.
+    def index
+      build_resources
+      if @resources.size > 1
+        # Model objects for a nested resource (act on the second-to-last parent).
+        parent = @resources[@resources.size - 2][:model_object]
+				mname = parent.class.name.underscore.pluralize
+				model_objects = parent.instance_eval("#{@resources.last[:parent_resource_method] || @resources.last[:controller_name]}").paginate PAGINATION_PARAM_NAME => params[PAGINATION_PARAM_NAME], :per_page => PAGINATION_PAGE_COUNT
+      else
+        # Model objects for a single resource.
+				if model_name
+					mname = model_name.pluralize
+					model_objects = model_class.all.paginate(PAGINATION_PARAM_NAME => params[PAGINATION_PARAM_NAME], :per_page => PAGINATION_PAGE_COUNT)
+				end
+      end
+			instance_variable_set "@#{mname}", model_objects if mname
+			render_action_template @resources.last[:index_template]
+    end
+
+    # Default show action.
+    def show
+      build_resources
+			render_action_template @resources.last[:show_template]
+    end
+
+    # Default new action.
+    def new
+      build_resources
+      render_new_or_edit_template
+    end
+
+    # Default edit action.
+    def edit
+      build_resources
+      render_new_or_edit_template
+    end
+
+    # Default create action.
+    def create
+      build_resources
+      if model_object.update_attributes params[model_symbol]
+        redirect_to build_resource_url(@resources)
+      else
+        render_new_or_edit_template
+      end
+    end
+
+    # Default update action.
+    def update
+      build_resources
+      if model_object.update_attributes params[model_symbol]
+        redirect_to build_resource_url(@resources)
+      else
+        render_new_or_edit_template
+      end  
+    end
+
+    # Default destroy action.
+    def destroy
+      build_resources
+      model_object.destroy
+      @resources.last.delete :model_object
+		  respond_to do |format|
+		    format.html {redirect_to build_resource_url(@resources)}
+		    format.js {render :text => "ok"}
+		  end			
+    end
+
+    protected
+
+    # Renders an action template.
+		def render_action_template template
+			unless template.blank?
+				symbol = model_symbol
+				object = model_object
+				if symbol && object
+					render :template => template, :locals => {symbol => object, :resources => @resources}
+				else
+					render :template => template, :locals => {:resources => @resources}
+				end
+			end
+		end
+
+    # Rendering a new/edit template.
+    def render_new_or_edit_template
+			render_action_template @resources.last[:new_or_edit_template]
+    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[:controller_name], resource[:parent_id]] * '/'
+        end
+      end
+      url
+    end    
+
+    # Builds 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
+      controller_name = resources.last[:controller_name]
+      id = resources.last[:model_object].id if resources.last[:model_object]
+       parent_url = build_parent_url(resources)
+      url = parent_url ? [parent_url, controller_name].join('/') : '/' + controller_name
+      case action
+        when :show then url = [url, id].compact * '/'
+        when :new then url = [url, "new"].compact * '/'
+        when :edit then url = [url, id, "edit"].compact * '/'
+        when :update then url = [url, id].compact.join('/') if controller_name == controller_name.pluralize
+        when :destroy then url = [url, id].compact.join('/') if controller_name == controller_name.pluralize
+      end
+      logger.debug "Resource URL: #{url}"
+      url
+    end    
+
+    private
+
+		# Answers the current page from the session (if any).
+		def current_page
+			update_page
+			session[controller_symbol("page")] || 1
+		end
+
+		# Updates the current page for the session.
+		def update_page
+			key = controller_symbol("page")
+			case params[:action]
+				when "index" then session[key] = params[:page] if params[:page] && session[key] != params[:page]
+				when "show" then
+					ids = model_class.all.map {|model| model.id}
+					session[key] = (ids.index(params[:id].to_i) + 1) / PAGINATION_PAGE_COUNT
+			end
+		end
+
+		# Answers the class of the current model.
+		def model_class
+			@resources.last[:model_class]
+		end
+		
+		# Answers the name of the current model.
+		def model_name
+			@resources.last[:model_name]
+		end
+		
+		# Answers the symbol of the current model.
+		# NOTE: The symbol is always derived from the model class name (i.e. MasterPost => :master_post) rather
+		# than the :model_name resource option in order to comply with the auto-generated model attribute hash built by Rails.
+		# This is especially important when dealing with new, create, edit, and update actions.
+		def model_symbol
+			name = model_class.name.underscore
+			name ? name.to_sym : nil
+		end
+
+		# Answers the current model object.
+		def model_object
+			model_name ? instance_variable_get("@#{model_name}") : nil
+		end
+
+		# Answers the controller symbol
+		def controller_symbol suffix = nil
+			[self.class.to_s.underscore.gsub('/', '_').chomp("_controller"), suffix].compact.join('_').to_sym
+		end
+
+		# Convenience method for answering back a properly camelized controller name.
+		def camelize_controller_name name
+			name = name.gsub(/^(\w)/) {|c| c.capitalize}
+			name += "Controller" unless name.include? "Controller"
+			name
+		end
+
+    # Builds all resources for the controller(s).
+    def build_resources
+      @resources ||= []
+      if @resources.empty?
+        add_resource self.class.name, @resources
+        @resources.reverse!
+      end
+      # Convenience for accessing the current model object.
+			instance_variable_set "@#{model_name}", @resources.last[:model_object] if model_name
+    end
+
+    # Answers the child or parent controller namespace (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_class].methods.include? "parent_resource"
+          add_resource resource[:controller_class].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, controller_name = get_controller_namespaces_and_name controller_name
+      controller_class = [namespaces, controller_name].compact.join("::").constantize
+      controller_name = controller_name.chomp("Controller").underscore
+      parent_key = controller_name.singularize + "_id"
+      resource = controller_class.resource_options || {}
+      resource.reverse_merge! :parent_key => parent_key,
+      :parent_id => params[parent_key],
+      :controller_name => controller_name,
+      :controller_class => controller_class,
+      :label => controller_name.capitalize,
+			:model_name => controller_name.singularize,
+      :namespaces => (namespaces.collect(&:downcase) if namespaces),
+      :new_or_edit_template => '/' + [namespaces, controller_name, "new_or_edit"].compact.join('/').downcase
+      begin
+        resource.reverse_merge! :model_class => controller_name.singularize.camelize.constantize
+      rescue NameError
+        logger.warn "Unable to constantize: " + controller_name
+      end
+      add_model_object resource
+    end
+
+    # Adds the current model object to the resource based on position in relationship chain.
+    def add_model_object resource
+      if resource[:model_class]
+        if params.include? resource[:parent_key]
+          # Nested parent.
+          resource[:model_object] = resource[:model_class].find resource[:parent_id] if resource[:parent_id]
+        else
+          # Single resource and/or end of nested chain.
+          resource[:model_object] = params[:id] ? resource[:model_class].find(params[:id]) : resource[:model_class].new
+        end
+      else
+        logger.error "Invalid model class.  Check that your controller and model are of the same name, otherwise specify the model as a resource option."
+      end
+      resource
+    end
+  end
+end