giraffesoft-resource_controller 0.4.10 → 0.4.12

data/README

@@ -1,312 +1 @@
-= 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
-
-  svn export http://svn.jamesgolick.com/resource_controller/tags/stable vendor/plugins/resource_controller
-  
-SVN (stable): {http://svn.jamesgolick.com/resource_controller/tags/stable}[http://svn.jamesgolick.com/resource_controller/tags/stable]
-
-SVN (ongoing): {http://svn.jamesgolick.com/resource_controller/trunk}[http://svn.jamesgolick.com/resource_controller/trunk]
-
-= 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
-
-== 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
-
-== 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
-
-== 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]
+README.rdoc

data/README.rdoc

@@ -4,17 +4,11 @@ resource_controller makes RESTful controllers easier, more maintainable, and sup
 
 == Get It
 
-Add it as a gem dependency
-
-  config.gem 'giraffesoft-resource_controller', :lib => 'resource_controller', :source => 'http://gems.github.com'
-  
-Or install it as a gem manually  
-  
-  sudo gem install giraffesoft-resource_controller
+  svn export http://svn.jamesgolick.com/resource_controller/tags/stable vendor/plugins/resource_controller
   
-Or grab the source
-  
-  git clone git://github.com/giraffesoft/resource_controller.git
+SVN (stable): {http://svn.jamesgolick.com/resource_controller/tags/stable}[http://svn.jamesgolick.com/resource_controller/tags/stable]
+
+SVN (ongoing): {http://svn.jamesgolick.com/resource_controller/trunk}[http://svn.jamesgolick.com/resource_controller/trunk]
 
 = Usage
 
@@ -232,6 +226,42 @@ Finally, the route_name helper is used by Urligence to determine which url helpe
       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
+
 == Url Helpers
 
 Thanks to Urligence, you also get some free url helpers.

data/Rakefile

@@ -2,7 +2,7 @@ require 'rake'
 require 'rake/testtask'
 require 'rake/rdoctask'
 require File.dirname(__FILE__)+'/lib/resource_controller/version'
-Dir['lib/tasks/**.rake'].each { |tasks| load tasks }
+Dir['tasks/**.rake'].each { |tasks| load tasks }
 
 desc 'Default: run unit tests.'
 task :default => :test

data/lib/resource_controller/version.rb

@@ -2,7 +2,7 @@ module ResourceController
   module VERSION
     MAJOR    = 0
     MINOR    = 4
-    TINY     = 10
+    TINY     = 12
     
     STRING   = [MAJOR, MINOR, TINY].join('.')
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: giraffesoft-resource_controller
 version: !ruby/object:Gem::Version 
-  version: 0.4.10
+  version: 0.4.12
 platform: ruby
 authors: 
 - James Golick
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-08-05 21:00:00 -07:00
+date: 2008-08-10 21:00:00 -07:00
 default_executable: 
 dependencies: []
 
@@ -46,8 +46,6 @@ files:
 - lib/resource_controller/singleton.rb
 - lib/resource_controller/version.rb
 - lib/resource_controller.rb
-- lib/tasks
-- lib/tasks/gem.rake
 - lib/urligence.rb
 - test/app
 - test/app/controllers

data/lib/tasks/gem.rake

@@ -1,67 +0,0 @@
-require 'rake/gempackagetask'
-require 'yaml'
-
-task :clean => :clobber_package
-
-spec = Gem::Specification.new do |s|
-  s.name                  = 'resource_controller'
-  s.version               = ResourceController::VERSION::STRING
-  s.summary               = "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."
-  s.rubyforge_project     = "giraffesoft"
-  s.description           = "Rails RESTful controller abstraction plugin."
-  s.author                = "James Golick"
-  s.email                 = "james@giraffesoft.ca"
-  s.homepage              = "http://jamesgolick.com/resource_controller"
-  s.has_rdoc              = true
-
-  s.required_ruby_version = '>= 1.8.5'
-
-  s.files                 = %w(README.rdoc README LICENSE init.rb Rakefile) +
-                            Dir.glob("{lib,test,generators,rails}/**/*")
-  
-  s.require_path          = "lib"
-end
-
-Rake::GemPackageTask.new(spec) do |p|
-  p.gem_spec = spec
-end
-
-task :tag_warn do
-  puts "*" * 40
-  puts "Don't forget to tag the release:"
-  puts
-  puts "  git tag -a v#{ResourceController::VERSION::STRING}"
-  puts
-  puts "or run rake tag"
-  puts "*" * 40
-end
-
-task :tag do
-  sh "git tag -a v#{ResourceController::VERSION::STRING}"
-end
-task :gem => :tag_warn
-
-namespace :gem do
-  desc 'Upload gems to rubyforge.org'
-  task :rubyforge => :gem do
-    sh 'rubyforge login'
-    sh "rubyforge add_release giraffesoft resource_controller #{ResourceController::VERSION::STRING} pkg/#{spec.full_name}.gem"
-    sh "rubyforge add_file    giraffesoft resource_controller #{ResourceController::VERSION::STRING} pkg/#{spec.full_name}.gem"
-  end
-  
-  desc "Update the gemspec for GitHub's gem server"
-  task :github do
-    File.open("resource_controller.gemspec", 'w'){|f| f.puts YAML::dump(spec) }
-    puts "gemspec generated here: resource_controller.gemspec"
-  end
-  
-  desc "Build and install the gem locally."
-  task :install => [:clobber, :package] do
-    sh "sudo gem install pkg/#{spec.full_name}.gem"
-  end
-  
-  desc "Remove the gem."
-  task :uninstall => :clean do
-    sh "sudo gem uninstall -v #{ResourceController::VERSION::STRING} -x #{ResourceController::NAME}"
-  end
-end