DEFAULTS LICENSE Rakefile VERSION generators/resourceful_scaffold/resourceful_scaffold_generator.rb generators/resourceful_scaffold/templates/controller.rb generators/resourceful_scaffold/templates/fixtures.yml generators/resourceful_scaffold/templates/functional_test.rb generators/resourceful_scaffold/templates/helper.rb generators/resourceful_scaffold/templates/migration.rb generators/resourceful_scaffold/templates/model.rb generators/resourceful_scaffold/templates/unit_test.rb generators/resourceful_scaffold/templates/view__form.haml generators/resourceful_scaffold/templates/view_edit.haml generators/resourceful_scaffold/templates/view_index.haml generators/resourceful_scaffold/templates/view_new.haml generators/resourceful_scaffold/templates/view_partial.haml generators/resourceful_scaffold/templates/view_show.haml init.rb lib/resourceful/base.rb lib/resourceful/builder.rb lib/resourceful/default/accessors.rb lib/resourceful/default/actions.rb lib/resourceful/default/callbacks.rb lib/resourceful/default/responses.rb lib/resourceful/default/urls.rb lib/resourceful/maker.rb lib/resourceful/response.rb lib/resourceful/serialize.rb spec/accessors_spec.rb spec/actions_spec.rb spec/base_spec.rb spec/builder_spec.rb spec/callbacks_spec.rb spec/integration_spec.rb spec/maker_spec.rb spec/response_spec.rb spec/responses_spec.rb spec/rspec_on_rails/LICENSE spec/rspec_on_rails/redirect_to.rb spec/rspec_on_rails/render_template.rb spec/serialize_spec.rb spec/spec_helper.rb spec/urls_spec.rb @@ -0,0 +1,239 @@ += 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 + + $ ruby script/plugin install http://svn.hamptoncatlin.com/make_resourceful/trunk + $ mv vendor/plugins/trunk vendor/plugins/make_resourceful + +Subversion + + $ svn co http://svn.hamptoncatlin.com/make_resourceful/trunk make_resourceful + +== Use it! + +The easiest way to start with make_resourceful +is to run the resource_scaffold generator. +It uses the same syntax as the Rails scaffold_resource generator: + + $ script/generate resource_scaffold post title:string body:text + +It does, however, require Haml[http://haml.hamptoncatlin.com]. +You _are_ using Haml, right? No? +I'll wait here while you go fall in love with 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_object ||= 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[link:classes/Resourceful/Accessors.html#M000024] +will get <tt>User.find(params[:user_id])</tt>, +and current_objects[link:classes/Resourceful/Default/Accessors.html#M000010] +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[link:classes/Resourceful/Default/Accessors.html#M000018]. +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! + +* Nathan Weizenbaum periodically makes blog posts about new features and versions of 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[link:classes/Resourceful/Builder.html#M000061] + 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 (link[http://groups.google.com/group/make_resourceful]) + where people will be happy to answer your questions. +* Read the source code! + It's very straightforward, + and make_resourceful is built to encourage overriding methods + and hacking the source. + +--- + +Copyright 2007 Hampton Catlin, Nathan Weizenbaum, and Jeff Hardy. + +Contributions by: + +* Russell Norris +* Jonathan Linowes +* Cristi Balan +* Mike Ferrier +* James Golick +* Don Petersen +* Alex Ross +* Tom Stuart README ef08dbf295447bb60eca6cecbefca8ba43f344a1 Hampton Catlin hcatlin@greed.local http://github.com/hcatlin/make_resourceful/commit/470a4c3ed199cd34c2076e29bd476d2bc6dc7e96 470a4c3ed199cd34c2076e29bd476d2bc6dc7e96 2008-08-22T10:07:07-07:00 2008-08-22T10:07:07-07:00 initial import from svn 5cb884ed43d1d75fa44776ba64e68aa2478528e6 Hampton Catlin hcatlin@greed.local