make_resourceful 1.0

data/Rakefile

@@ -0,0 +1,31 @@
+require 'rake'
+require 'rake/rdoctask'
+require 'spec/rake/spectask'
+
+desc 'Default: run specs.'
+task :default => :spec
+
+spec_files = Rake::FileList["spec/**/*_spec.rb"]
+
+desc "Run specs"
+Spec::Rake::SpecTask.new do |t|
+  t.spec_files = spec_files
+  t.spec_opts = ["-c"]
+end
+
+desc "Generate code coverage"
+Spec::Rake::SpecTask.new(:coverage) do |t|
+  t.spec_files = spec_files
+  t.rcov = true
+  t.rcov_opts = ['--exclude', 'spec,/var/lib/gems']
+end
+
+desc 'Generate documentation for the make_resourceful plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'make_resourceful'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.main = 'README'
+  rdoc.rdoc_files.include(FileList.new('*').exclude(/[^A-Z0-9]/))
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/Readme.rdoc

@@ -0,0 +1,229 @@
+= make_resourceful
+===== Take back control of your Controllers. Make them awesome. Make them sleek. Make them resourceful.
+
+REST is a fine pattern for designing controllers,
+but it can be pretty repetitive.
+Who wants to write out the same actions and copy the same model lookup logic
+all over their application?
+
+make_resourceful handles all that for you.
+It sets up all your RESTful actions and responses with next to no code.
+Everything has full, sensible default functionality.
+
+Of course, no controller _only_ uses the defaults.
+So make_resourceful can be massively customized,
+while still keeping your controllers trim and readable.
+
+== Get it!
+ 
+Rails 3.0+
+
+  gem "make_resourceful" #ZOMG, SO EASY
+
+Git
+
+  $ git clone git://github.com/hcatlin/make_resourceful.git
+
+== Use it!
+
+If you want to try make_resourceful on one of your current controllers,
+just replace the mess of repetition with this:
+
+  class FooController < ApplicationController
+    make_resourceful do
+      actions :all
+    end
+  end
+
+Those three lines will replace the entire default controller
+that comes out of the scaffold_resource generator.
+
+=== Really?
+
+Yes.
+
+=== Can I do nested resources?
+
+  make_resourceful do
+    actions :all
+    belongs_to :post
+  end
+
+=== What if I want to use fancy permalinks?
+
+  def current_object
+    @current_object ||= current_model.find_by_permalink(params[:id])
+  end
+
+=== What about paging?
+
+  def current_objects
+    @current_objects ||= current_model.find(:all,
+      :order => "created_at DESC", :page => {:current => params[:page], :size => 10 } )
+  end
+
+=== What if I want to do something in the middle of an action?
+
+  before :show, :index do
+    @page_title = "Awesome!"
+  end
+
+  after :create_fails do
+    @page_title = "Not So Awesome!"
+  end
+
+=== What about all of my awesome respond_to blocks for my XML APIs and RJS responses?
+
+  response_for :show do |format|
+    format.html
+    format.js
+    format.xml
+  end
+
+  response_for :update_fails do |format|
+    format.html { render :action => 'edit' }
+    format.json { render :json => false.to_json, :status => 422 }
+  end
+
+=== So I guess I have to write responses for all my actions?
+
+Nope! make_resourceful makes them do the right thing by default.
+You only need to customize them if you want to do something special.
+
+=== Seriously?!
+
+Yes!
+
+== Grok it!
+
+=== +make_resourceful+ the Method
+
+The +make_resourceful+ block is where most of the action happens.
+Here you specify which actions you want to auto-generate,
+what code you want to run for given callbacks,
+and so forth.
+
+You also use the block to declare various bits of information about your controller.
+For instance, if the controller is nested, you'd call +belongs_to+.
+If you wanted to expose your models as some sort of text format,
+you'd call +publish+.
+
+Check out the documentation of Resourceful::Builder
+for more information on the methods you can call here.
+
+=== Helper Methods
+
+make_resourceful provides lots of useful methods
+that can be used in your callbacks and in your views.
+They range from accessing the records you're looking up
+to easily generating URLs for a record
+to getting information about the action itself.
+
+Two of the most useful methods are +current_object+ and +current_objects+
+(note the subtle plurality difference).
++current_objects+ only works for +index+,
+and returns all the records in the current model.
++current_object+ works for all actions other than +index+,
+and returns the record that's currently being dealt with.
+
+The full documentation of the helper methods
+is in Resourceful::Default::Accessors and Resourceful::Default::URLs.
+
+=== Nested Resources
+
+make_resourceful supports easy management of nested resources.
+This is set up with the Resourceful::Builder#belongs_to declaration.
+Pass in the name of the parent model,
+
+  belongs_to :user
+
+and everything will be taken care of.
+When +index+ is run for GET /users/12/albums,
+parent_object
+will get <tt>User.find(params[:user_id])</tt>,
+and current_objects
+will get <tt>parent_object.albums</tt>.
+When +create+ is run for POST /users/12/albums,
+the newly created Album will automatically belong to the user
+with id 12.
+
+The normal non-scoped actions still work, too.
+GET /albums/15 runs just fine.
+make_resourceful knows that since there's no <tt>params[:user_id]</tt>,
+you just want to deal with the album.
+
+You can even have a single resource nested under several different resources.
+Just pass multiple parent names to the Resourceful::Builder#belongs_to, like
+
+  belongs_to :user, :artist
+
+Then /users/15/albums and /artists/7/albums will both work.
+
+This does, however, mean that make_resourceful only supports one level of nesting.
+There's no automatic handling of /users/15/collections/437/albums.
+However, this is really the best way to organize most resources anyway;
+see this {article}[http://weblog.jamisbuck.org/2007/2/5/nesting-resources].
+
+If you really need a deeply nested controller,
+it should be easy enough to set up on your own.
+Just override current_model.
+See the next section for more details.
+
+=== Overriding Methods
+
+Not only are helper methods useful to the developer to use,
+they're used internally by the actions created by make_resourceful.
+Thus one of the main ways make_resourceful can be customized
+is by overriding accessors.
+
+For instance, if you want to only look up the 10 most recent records for +index+,
+you're override +current_objects+.
+If you wanted to use a different model than that suggested by the name of the controller,
+you'd override +current_model+.
+
+When you're overriding methods that do SQL lookups, though, be a little cautious.
+By default, these methods cache their values in instance variables
+so that multiple SQL queries aren't run on multiple calls.
+When overriding them, it's wise for you to do the same.
+For instance,
+
+  def current_object
+    @current_object ||= current_model.find_by_name(params[:name])
+  end
+
+=== For More Information...
+
+Haven't found all the information you need in the RDoc?
+Still a little confused about something?
+Don't despair, there are still more resources available!
+
+* Read the source code!
+  It's very straightforward,
+  and make_resourceful is built to encourage overriding methods
+  and hacking the source.
+* Nathan Weizenbaum has some good blog posts about make_resourceful.
+  They may be a little outdated, but they should still be useful and explanatory.
+  * On nesting and associations: {here}[http://nex-3.com/posts/55-nesting-and-make_resourceful].
+  * An overview of make_resourceful 0.2.0 and 0.2.2: {here}[http://localhost:3000/posts/54-make_resourceful-0-2-0].
+  * On Resourceful::Builder#publish
+    and Resourceful::Serialize:
+    {here}[http://nex-3.com/posts/35-make_resourceful-the-basics-of-publish] and
+    {here}[http://nex-3.com/posts/36-make_resourceful-publish-extras].
+* There's an excellent, active Google Group http://groups.google.com/group/make_resourceful
+  where people will be happy to answer your questions.
+
+---
+
+Copyright 2007-2010 Hampton Catlin and Nathan Weizenbaum.
+Contributions by:
+
+* Russell Norris
+* Jonathan Linowes
+* Cristi Balan
+* Mike Ferrier
+* James Golick
+* Don Petersen
+* Alex Ross
+* Tom Stuart
+* Glenn Powell
+* Johannes Jörg Schmidt

data/VERSION

@@ -0,0 +1 @@
+1.0

data/lib/make_resourceful.rb

@@ -0,0 +1,11 @@
+
+class MakeResourcefulTie < Rails::Railtie
+  initializer "my_railtie.configure_rails_initialization" do
+    require_relative 'resourceful/maker'
+    ActionController::Base.extend Resourceful::Maker
+  end
+  
+  generators do
+    #require_relative 'resourceful/generators/resourceful_scaffold/resourceful_scaffold_generator'
+  end
+end

data/lib/resourceful/base.rb

@@ -0,0 +1,63 @@
+# The module containing all the code for make_resourceful.
+#
+# For methods available in the +make_resourceful+ block,
+# see Resourceful::Builder.
+#
+# For helper methods and methods you can override
+# to customize the behavior of your actions,
+# see Resourceful::Default::Accessors
+# and Resourceful::Default::URLs.
+module Resourceful
+  # We want to define some stuff before we load other modules
+
+  # The default actions generated by make_resourceful.
+  ACTIONS = [:index, :show, :edit, :update, :create, :new, :destroy]
+
+  # The actions that modify the database.
+  MODIFYING_ACTIONS = [:update, :create, :destroy]
+
+  # The actions that act on multiple records.
+  PLURAL_ACTIONS = [:index]
+
+  # The actions that act on just one record.
+  SINGULAR_ACTIONS = ACTIONS - PLURAL_ACTIONS
+
+  # The actions that act on just one record.
+  SINGULAR_PRELOADED_ACTIONS = SINGULAR_ACTIONS - [:new, :create]
+end
+
+require 'resourceful/default/accessors'
+require 'resourceful/default/responses'
+require 'resourceful/default/callbacks'
+require 'resourceful/default/urls'
+
+# All modules included by this module
+# are made available to the controller as accessors.
+module Resourceful::Base
+  @@made_resourceful_callbacks = []
+
+  # This method is meant to be called by included classes.
+  # It takes a block of the same form as that given to Maker#make_resourceful.
+  # The Maker will then run that block
+  # along with the blocks given by the individual controllers.
+  def self.made_resourceful(&block)
+    if block
+      @@made_resourceful_callbacks << block
+    else
+      @@made_resourceful_callbacks
+    end
+  end
+
+  include Resourceful::Default::Accessors
+  include Resourceful::Default::Responses
+  include Resourceful::Default::Callbacks
+  include Resourceful::Default::URLs
+
+  # FIXME HACK
+  # making methods assigned to controller private
+  # prevents access from dispatcher.
+  private *Resourceful::Default::Accessors.public_instance_methods
+  private *Resourceful::Default::Responses.public_instance_methods
+  private *Resourceful::Default::Callbacks.public_instance_methods
+  private *Resourceful::Default::URLs.public_instance_methods
+end