jeffrafter-resource_controller 0.5.5

data/README.rdoc

@@ -0,0 +1,314 @@
+= Resource Controller
+
+resource_controller makes RESTful controllers easier, more maintainable, and super readable.  With the RESTful controller pattern hidden away, you can focus on what makes your controller special.
+
+== Get It
+
+Install it as a plugin:
+
+  script/plugin install git://github.com/giraffesoft/resource_controller.git
+  
+Or grab the source
+  
+  git clone git://github.com/giraffesoft/resource_controller.git
+
+= Usage
+
+Creating a basic RESTful controller is as easy as...
+
+  class PostsController < ResourceController::Base
+  end
+  
+...or if you prefer, you can use the method-call syntax.  If you need to inherit from some other class, this syntax is definitely for you:
+
+  class PostsController < ApplicationController
+    resource_controller
+  end
+
+Both syntaxes are identical in their behavior.  Just make sure you call resource_controller before you use any other r_c functionality in your controller.
+  
+  
+Nobody just uses the default RESTful controller, though.  resource_controller provides a simple API for customizations.
+
+== Action Lifecycle
+
+It's really easy to make changes to the lifecycle of your actions.
+
+  Note: We had to call the new accessor "new_action", since new is somewhat reserved in ruby.
+
+=== Before and After
+
+  class ProjectsController < ResourceController::Base
+    
+    new_action.before do
+      3.times { object.tasks.build }
+    end
+    
+    create.after do
+      object.creator = current_user
+    end
+    
+  end
+  
+=== Flash
+
+  class ProjectsController < ResourceController::Base
+    create.flash "Can you believe how easy it is to use resource_controller?  Neither could I!"
+  end
+
+=== respond_to
+
+You can add to what's already there...
+  
+  class ProjectsController < ResourceController::Base      
+    create.wants.js { render :template => "show.rjs" }
+  end
+  
+Or you can create a whole new block.  This syntax destroys everything that's there, and starts again...
+
+  class ProjectsController < ResourceController::Base      
+    create.response do |wants|
+      wants.html
+      wants.js { render :template => "show.rjs" }
+    end
+  end
+  
+=== Scoping
+
+Because sometimes you want to make a bunch of customizations at once, most of the helpers accept blocks that make grouping calls really easy.  Is it a DSL?  Maybe; maybe not.  But, it's definitely awesome.
+
+With actions that can fail, the scoping defaults to success.  That means that create.flash == create.success.flash.
+
+  class ProjectsController < ResourceController::Base
+    
+    create do
+      flash "Object successfully created!"
+      wants.js { render :template => "show.rjs" }
+      
+      failure.wants.js { render :template => "display_errors.rjs" }
+    end
+    
+    destroy do
+      flash "You destroyed your project.  Good work."
+      
+      failure do
+        flash "You cannot destroy that project.  Stop trying!"
+        wants.js { render :template => "display_errors.rjs" }
+      end
+    end
+    
+  end
+  
+== Singleton Resource
+
+If you want to create a singleton RESTful controller inherit from ResourceController::Singleton.
+
+  class AccountsController < ResourceController::Singleton
+  end
+
+*Note:* This type of controllers handle a single resource only so the index action and all the collection helpers (collection_url, collection_path...) are not available for them.
+
+Loading objects in singletons is similar to plural controllers with one exception. For non-nested singleton controllers you should override the object method as it defaults to nil for them.
+
+  class AccountsController < ResourceController::Singleton
+    private
+      def object
+        @object ||= Account.find(session[:account_id])
+      end
+   end
+
+In other cases you can use the default logic and override it only if you use permalinks or anything special. 
+
+Singleton nesting with both :has_many and :has_one associations is provided...
+
+  map.resource :account, :has_many => :options  # /account/options, account is a singleton parent
+  map.resources :users, :has_one => :image  # /users/1/image, image is a singleton child
+
+If you have the :has_many association with a singleton parent remember to override parent_object for your :has_many controller as it returns nil by default in this case.
+
+  class OptionsController < ResourceController::Base
+    belongs_to :account
+
+    protected
+    def parent_object
+      Account.find(session[:account_id])
+    end
+  end
+
+== Helpers (ResourceController::Helpers)
+
+=== Loading objects
+
+You want to add something like pagination to your controller...
+
+  class PostsController < ResourceController::Base
+    private
+      def collection
+        @collection ||= end_of_association_chain.find(:all, :page => {:size => 10, :current => params[:page]})
+      end
+  end
+  
+Or maybe you used a permalink...
+
+  class PostsController < ResourceController::Base
+    private
+      def object
+        @object ||= end_of_association_chain.find_by_permalink(param)
+      end
+  end
+
+=== Building objects
+
+Maybe you have some alternative way of building objects...
+
+  class PostsController < ResourceController::Base
+    private
+      def build_object
+        @object ||= end_of_association_chain.build_my_object_some_funky_way object_params
+      end
+  end
+  
+...and there are tons more helpers in the ResourceController::Helpers
+
+== Nested Resources
+
+Nested controllers can be a pain, especially if routing is such that you may or may not have a parent.  Not so with Resource Controller.
+
+  class CommentsController < ResourceController::Base
+    belongs_to :post
+  end
+  
+All of the finding, and creation, and everything will be done at the scope of the post automatically.
+
+== Namespaced Resources
+
+...are handled automatically, and any namespaces are always available, symbolized, in array form @ ResourceController::Helpers#namespaces
+
+== Polymorphic Resources
+
+Everything, including url generation is handled completely automatically.  Take this example...
+  
+  ## comment.rb
+  class Comment
+    belongs_to :commentable, :polymorphic => true
+  end
+  
+  ## comments_controller.rb
+  class CommentsController < ResourceController::Base
+    belongs_to :post, :product, :user
+  end
+  *Note:* Your model doesn't have to be polymorphic in the ActiveRecord sense.  It can be associated in whichever way you want.
+  
+  ## routes.rb
+  map.resources :posts, :has_many => :comments
+  map.resources :products, :has_many => :comments
+  map.resources :users, :has_many => :comments
+
+All you have to do is that, and r_c will infer whichever relationship is present, and perform all the actions at the scope of the parent object.
+
+=== Parent Helpers
+
+You also get some helpers for reflecting on your parent.
+
+  parent?       # => true/false is there a parent present?
+  parent_type   # => :post
+  parent_model  # => Post
+  parent_object # => @post
+
+=== Non-standard resource names
+
+resource_controller supports overrides for every non-standard configuration of resources.
+
+The most common example is where the resource has a different name than the associated model.  Simply overriding the model_name helper will get resource_controller working with your model.
+
+  map.resources :tags
+  ...
+  class PhotoTag < ActiveRecord::Base
+  ...
+  class TagsController < ResourceController::Base
+    private
+      def model_name
+        'photo_tag'
+      end
+  end
+  
+In the above example, the variable, and params will be set to @tag, @tags, and params[:tag].  If you'd like to change that, override object_name.
+
+  def object_name
+    'photo_tag'
+  end
+
+If you're using a non-standard controller name, but everything else is standard, overriding resource_name will propagate through all of the other helpers.
+
+  map.resources :tags, :controller => "somethings"
+  ...
+  class Tag < ActiveRecord::Base
+  ...
+  class SomethingsController < ResourceController::Base
+    private
+      def resource_name
+        'tag'
+      end
+  end
+  
+Finally, the route_name helper is used by Urligence to determine which url helper to call, so if you have non-standard route names, override it.
+
+  map.resources :tags, :controller => "taggings"
+  ...
+  class Taggings < ActiveRecord::Base
+  ...
+  class TaggingsController < ResourceController::Base
+    private
+      def route_name
+        'tag'
+      end
+  end
+
+== Url Helpers
+
+Thanks to Urligence, you also get some free url helpers.
+
+No matter what your controller looks like...
+
+  [edit_|new_]object_url # is the equivalent of saying [edit_|new_]post_url(@post)
+  [edit_|new_]object_url(some_other_object) # allows you to specify an object, but still maintain any paths or namespaces that are present
+  
+  collection_url # is like saying posts_url
+
+Url helpers are especially useful when working with polymorphic controllers.
+
+  # /posts/1/comments
+  object_url          # => /posts/1/comments/#{@comment.to_param}
+  object_url(comment) # => /posts/1/comments/#{comment.to_param}
+  edit_object_url     # => /posts/1/comments/#{@comment.to_param}/edit
+  collection_url      # => /posts/1/comments
+    
+  # /products/1/comments
+  object_url          # => /products/1/comments/#{@comment.to_param}
+  object_url(comment) # => /products/1/comments/#{comment.to_param}
+  edit_object_url     # => /products/1/comments/#{@comment.to_param}/edit
+  collection_url      # => /products/1/comments
+  
+  # /comments
+  object_url          # => /comments/#{@comment.to_param}
+  object_url(comment) # => /comments/#{comment.to_param}
+  edit_object_url     # => /comments/#{@comment.to_param}/edit
+  collection_url      # => /comments
+  
+Or with namespaced, nested controllers...
+
+  # /admin/products/1/options
+  object_url          # => /admin/products/1/options/#{@option.to_param}
+  object_url(option)  # => /admin/products/1/options/#{option.to_param}
+  edit_object_url     # => /admin/products/1/options/#{@option.to_param}/edit
+  collection_url      # => /admin/products/1/options
+  
+You get the idea.  Everything is automagical!  All parameters are inferred.
+
+== Credits
+
+resource_controller was created, and is maintained by {James Golick}[http://jamesgolick.com].
+
+== License
+
+resource_controller is available under the {MIT License}[http://en.wikipedia.org/wiki/MIT_License]

data/VERSION.yml

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

data/generators/scaffold_resource/USAGE

@@ -0,0 +1,29 @@
+Description:
+    The scaffold resource generator creates a model, a controller, and a set of templates that's ready to use as the
+    starting point for your REST-like, resource-oriented application. This basically means that it follows a set of
+    conventions to exploit the full set of HTTP verbs (GET/POST/PUT/DELETE) and is prepared for multi-client access
+    (like one view for HTML, one for an XML API, one for ATOM, etc). Everything comes with sample unit and functional
+    tests as well.
+    
+    The generator takes the name of the model as its first argument. This model name is then pluralized to get the 
+    controller name. So "scaffold_resource post" will generate a Post model and a PostsController and will be intended
+    for URLs like /posts and /posts/45.
+    
+    As additional parameters, the generator will take attribute pairs described by name and type. These attributes will
+    be used to prepopulate the migration to create the table for the model and to give you a set of templates for the
+    view. For example, "scaffold_resource post title:string created_on:date body:text published:boolean" will give
+    you a model with those four attributes, forms to create and edit those models from, and an index that'll list them 
+    all.
+    
+    You don't have to think up all attributes up front, but it's a good idea of adding just the baseline of what's 
+    needed to start really working with the resource.
+    
+    Once the generator has run, you'll need to add a declaration to your config/routes.rb file to hook up the rules
+    that'll point URLs to this new resource. If you create a resource like "scaffold_resource post", you'll need to
+    add "map.resources :posts" (notice the plural form) in the routes file. Then your new resource is accessible from
+    /posts.
+
+Examples:
+    ./script/generate scaffold_resource post # no attributes, view will be anemic
+    ./script/generate scaffold_resource post title:string created_on:date body:text published:boolean
+    ./script/generate scaffold_resource purchase order_id:integer created_at:datetime amount:decimal

data/generators/scaffold_resource/scaffold_resource_generator.rb

@@ -0,0 +1,179 @@
+class ScaffoldResourceGenerator < Rails::Generator::NamedBase
+  attr_reader   :controller_name,
+                :controller_class_path,
+                :controller_file_path,
+                :controller_class_nesting,
+                :controller_class_nesting_depth,
+                :controller_class_name,
+                :controller_singular_name,
+                :controller_plural_name,
+                :resource_edit_path,
+                :default_file_extension,
+                :generator_default_file_extension
+  alias_method  :controller_file_name,  :controller_singular_name
+  alias_method  :controller_table_name, :controller_plural_name
+
+  def initialize(runtime_args, runtime_options = {})
+    super
+
+    if @rspec = has_rspec?
+      if ActionController::Base.respond_to?(:resource_action_separator)
+        @resource_edit_path = "/edit"
+      else
+        @resource_edit_path = ";edit"
+      end
+    end
+
+    @generator_default_file_extension = (defined? Haml )? "haml" : "erb"
+    
+    # we want to call erb templates .rhtml or .haml if this is rails 1
+    if RAILS_GEM_VERSION.to_i == 1
+      @default_file_extension = @generator_default_file_extension == 'erb' ? 'rhtml' : @generator_default_file_extension
+    else
+      @default_file_extension = "html.#{@generator_default_file_extension}"
+    end
+    
+    @controller_name = @name.pluralize
+
+    base_name, @controller_class_path, @controller_file_path, @controller_class_nesting, @controller_class_nesting_depth = extract_modules(@controller_name)
+    @controller_class_name_without_nesting, @controller_singular_name, @controller_plural_name = inflect_names(base_name)
+
+    if @controller_class_nesting.empty?
+      @controller_class_name = @controller_class_name_without_nesting
+    else
+      @controller_class_name = "#{@controller_class_nesting}::#{@controller_class_name_without_nesting}"
+    end
+  end
+
+  def manifest
+    record do |m|
+      # Check for class naming collisions.
+      m.class_collisions(controller_class_path, "#{controller_class_name}Controller", "#{controller_class_name}Helper")
+      m.class_collisions(class_path, "#{class_name}")
+
+      # Controller, helper, views, and test directories.
+      m.directory(File.join('app/models', class_path))
+      m.directory(File.join('app/controllers', controller_class_path))
+      m.directory(File.join('app/helpers', controller_class_path))
+      m.directory(File.join('app/views', controller_class_path, controller_file_name))
+
+      if @rspec
+        m.directory(File.join('spec/controllers', controller_class_path))
+        m.directory(File.join('spec/helpers', class_path))
+        m.directory(File.join('spec/models', class_path))
+        m.directory File.join('spec/views', controller_class_path, controller_file_name)
+        m.directory(File.join('spec/fixtures', class_path))
+      else
+        m.directory(File.join('test/functional', controller_class_path))
+        m.directory(File.join('test/unit', class_path))
+      end
+      
+      scaffold_views.each do |action|
+        m.template(
+          "view_#{action}.#{generator_default_file_extension}",
+          File.join('app/views', controller_class_path, controller_file_name, "#{action}.#{default_file_extension}")
+        )
+      end
+
+      m.template('model.rb', File.join('app/models', class_path, "#{file_name}.rb"))
+      m.template('controller.rb', File.join('app/controllers', controller_class_path, "#{controller_file_name}_controller.rb"))
+      m.template('helper.rb',          File.join('app/helpers',     controller_class_path, "#{controller_file_name}_helper.rb"))
+
+      if @rspec
+        m.template('rspec/functional_spec.rb',  File.join('spec/controllers', controller_class_path, "#{controller_file_name}_controller_spec.rb"))
+        m.template('rspec/routing_spec.rb',     File.join('spec/controllers', controller_class_path, "#{controller_file_name}_routing_spec.rb"))
+        m.template('rspec/helper_spec.rb',      File.join('spec/helpers',     class_path, "#{controller_file_name}_helper_spec.rb"))
+        m.template('rspec/unit_spec.rb',        File.join('spec/models',      class_path, "#{file_name}_spec.rb"))
+        m.template('fixtures.yml',        File.join('spec/fixtures',    "#{table_name}.yml"))
+
+        rspec_views.each do |action|
+          m.template(
+            "rspec/views/#{action}_spec.rb",
+            File.join('spec/views', controller_class_path, controller_file_name, "#{action}_spec.rb")
+          )
+        end
+
+      else
+        functional_test = (defined? ThoughtBot::Shoulda) ? "shoulda_functional_test.rb" : "functional_test.rb"
+
+        m.template("#{functional_test}", File.join('test/functional', controller_class_path, "#{controller_file_name}_controller_test.rb"))
+        m.template('unit_test.rb',       File.join('test/unit',       class_path, "#{file_name}_test.rb"))
+        m.template('fixtures.yml',       File.join('test/fixtures',   "#{table_name}.yml"))
+      end
+
+
+      unless options[:skip_migration]
+        migration_template = RAILS_GEM_VERSION.to_i == 1 ? 'old_migration.rb' : 'migration.rb'
+        
+        m.migration_template(
+          migration_template, 'db/migrate', 
+          :assigns => {
+            :migration_name => "Create#{class_name.pluralize.gsub(/::/, '')}",
+            :attributes     => attributes
+          }, 
+          :migration_file_name => "create_#{file_path.gsub(/\//, '_').pluralize}"
+        )
+      end
+
+      m.route_resources controller_file_name
+    end
+  end
+
+  # Lifted from Rick Olson's restful_authentication
+  def has_rspec?
+    options[:rspec] || (File.exist?('spec') && File.directory?('spec'))
+  end
+  
+  protected
+    # Override with your own usage banner.
+    def banner
+      "Usage: #{$0} scaffold_resource ModelName [field:type, field:type]"
+    end
+
+    def rspec_views
+      %w[ index show new edit ]
+    end
+    
+    def scaffold_views
+      rspec_views + %w[ _form ]
+    end
+
+    def model_name 
+      class_name.demodulize
+    end
+
+    def add_options!(opt)
+      opt.separator ''
+      opt.separator 'Options:'
+      opt.on("--rspec", "Force rspec mode (checks for RAILS_ROOT/spec by default)") { |v| options[:rspec] = true }
+    end
+end
+
+module Rails
+  module Generator
+    class GeneratedAttribute
+      def default_value
+        @default_value ||= case type
+          when :int, :integer               then "\"1\""
+          when :float                       then "\"1.5\""
+          when :decimal                     then "\"9.99\""
+          when :datetime, :timestamp, :time then "Time.now"
+          when :date                        then "Date.today"
+          when :string                      then "\"MyString\""
+          when :text                        then "\"MyText\""
+          when :boolean                     then "false"
+          else
+            ""
+        end      
+      end
+
+      def input_type
+        @input_type ||= case type
+          when :text                        then "textarea"
+          else
+            "input"
+        end      
+      end
+    end
+  end
+end