Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 229 lines (169 sloc) 7.201 kb
470a4c3 initial import from svn
Hampton Catlin authored
1 = make_resourceful
2 ===== Take back control of your Controllers. Make them awesome. Make them sleek. Make them resourceful.
3
4 REST is a fine pattern for designing controllers,
5 but it can be pretty repetitive.
6 Who wants to write out the same actions and copy the same model lookup logic
7 all over their application?
8
9 make_resourceful handles all that for you.
10 It sets up all your RESTful actions and responses with next to no code.
11 Everything has full, sensible default functionality.
12
13 Of course, no controller _only_ uses the defaults.
14 So make_resourceful can be massively customized,
15 while still keeping your controllers trim and readable.
16
17 == Get it!
18
a137e71 update readme
Hampton Catlin authored
19 Rails 3.0+
470a4c3 initial import from svn
Hampton Catlin authored
20
a137e71 update readme
Hampton Catlin authored
21 gem "make_resourceful" #ZOMG, SO EASY
470a4c3 initial import from svn
Hampton Catlin authored
22
d158304 @james Update README to reflect move to github
james authored
23 Git
470a4c3 initial import from svn
Hampton Catlin authored
24
d158304 @james Update README to reflect move to github
james authored
25 $ git clone git://github.com/hcatlin/make_resourceful.git
470a4c3 initial import from svn
Hampton Catlin authored
26
27 == Use it!
28
29 If you want to try make_resourceful on one of your current controllers,
30 just replace the mess of repetition with this:
31
32 class FooController < ApplicationController
33 make_resourceful do
34 actions :all
35 end
36 end
37
38 Those three lines will replace the entire default controller
39 that comes out of the scaffold_resource generator.
40
41 === Really?
42
43 Yes.
44
45 === Can I do nested resources?
46
47 make_resourceful do
48 actions :all
49 belongs_to :post
50 end
51
52 === What if I want to use fancy permalinks?
53
54 def current_object
55 @current_object ||= current_model.find_by_permalink(params[:id])
56 end
57
58 === What about paging?
59
60 def current_objects
d35ce89 @hcatlin readme correction reported by http://github.com/ekampp
authored
61 @current_objects ||= current_model.find(:all,
470a4c3 initial import from svn
Hampton Catlin authored
62 :order => "created_at DESC", :page => {:current => params[:page], :size => 10 } )
63 end
64
65 === What if I want to do something in the middle of an action?
66
67 before :show, :index do
68 @page_title = "Awesome!"
69 end
70
71 after :create_fails do
72 @page_title = "Not So Awesome!"
73 end
74
75 === What about all of my awesome respond_to blocks for my XML APIs and RJS responses?
76
77 response_for :show do |format|
78 format.html
79 format.js
80 format.xml
81 end
82
83 response_for :update_fails do |format|
84 format.html { render :action => 'edit' }
85 format.json { render :json => false.to_json, :status => 422 }
86 end
87
88 === So I guess I have to write responses for all my actions?
89
90 Nope! make_resourceful makes them do the right thing by default.
91 You only need to customize them if you want to do something special.
92
93 === Seriously?!
94
95 Yes!
96
97 == Grok it!
98
99 === +make_resourceful+ the Method
100
101 The +make_resourceful+ block is where most of the action happens.
102 Here you specify which actions you want to auto-generate,
103 what code you want to run for given callbacks,
104 and so forth.
105
106 You also use the block to declare various bits of information about your controller.
107 For instance, if the controller is nested, you'd call +belongs_to+.
108 If you wanted to expose your models as some sort of text format,
109 you'd call +publish+.
110
111 Check out the documentation of Resourceful::Builder
112 for more information on the methods you can call here.
113
114 === Helper Methods
115
116 make_resourceful provides lots of useful methods
117 that can be used in your callbacks and in your views.
118 They range from accessing the records you're looking up
119 to easily generating URLs for a record
120 to getting information about the action itself.
121
122 Two of the most useful methods are +current_object+ and +current_objects+
123 (note the subtle plurality difference).
124 +current_objects+ only works for +index+,
125 and returns all the records in the current model.
126 +current_object+ works for all actions other than +index+,
127 and returns the record that's currently being dealt with.
128
129 The full documentation of the helper methods
130 is in Resourceful::Default::Accessors and Resourceful::Default::URLs.
131
132 === Nested Resources
133
134 make_resourceful supports easy management of nested resources.
135 This is set up with the Resourceful::Builder#belongs_to declaration.
136 Pass in the name of the parent model,
137
138 belongs_to :user
139
140 and everything will be taken care of.
141 When +index+ is run for GET /users/12/albums,
69c450e @hcatlin adding back in more lines
authored
142 parent_object
470a4c3 initial import from svn
Hampton Catlin authored
143 will get <tt>User.find(params[:user_id])</tt>,
afcb34f @hcatlin removing all but one link
authored
144 and current_objects
470a4c3 initial import from svn
Hampton Catlin authored
145 will get <tt>parent_object.albums</tt>.
146 When +create+ is run for POST /users/12/albums,
147 the newly created Album will automatically belong to the user
148 with id 12.
149
150 The normal non-scoped actions still work, too.
151 GET /albums/15 runs just fine.
152 make_resourceful knows that since there's no <tt>params[:user_id]</tt>,
153 you just want to deal with the album.
154
155 You can even have a single resource nested under several different resources.
156 Just pass multiple parent names to the Resourceful::Builder#belongs_to, like
157
158 belongs_to :user, :artist
159
160 Then /users/15/albums and /artists/7/albums will both work.
161
162 This does, however, mean that make_resourceful only supports one level of nesting.
163 There's no automatic handling of /users/15/collections/437/albums.
164 However, this is really the best way to organize most resources anyway;
0742111 @hcatlin adding in one link
authored
165 see this {article}[http://weblog.jamisbuck.org/2007/2/5/nesting-resources].
470a4c3 initial import from svn
Hampton Catlin authored
166
167 If you really need a deeply nested controller,
168 it should be easy enough to set up on your own.
afcb34f @hcatlin removing all but one link
authored
169 Just override current_model.
470a4c3 initial import from svn
Hampton Catlin authored
170 See the next section for more details.
171
172 === Overriding Methods
173
174 Not only are helper methods useful to the developer to use,
175 they're used internally by the actions created by make_resourceful.
176 Thus one of the main ways make_resourceful can be customized
177 is by overriding accessors.
178
179 For instance, if you want to only look up the 10 most recent records for +index+,
180 you're override +current_objects+.
181 If you wanted to use a different model than that suggested by the name of the controller,
182 you'd override +current_model+.
183
184 When you're overriding methods that do SQL lookups, though, be a little cautious.
185 By default, these methods cache their values in instance variables
186 so that multiple SQL queries aren't run on multiple calls.
187 When overriding them, it's wise for you to do the same.
188 For instance,
189
190 def current_object
191 @current_object ||= current_model.find_by_name(params[:name])
192 end
193
194 === For More Information...
195
196 Haven't found all the information you need in the RDoc?
197 Still a little confused about something?
198 Don't despair, there are still more resources available!
199
200 * Read the source code!
201 It's very straightforward,
202 and make_resourceful is built to encourage overriding methods
203 and hacking the source.
69c450e @hcatlin adding back in more lines
authored
204 * Nathan Weizenbaum has some good blog posts about make_resourceful.
205 They may be a little outdated, but they should still be useful and explanatory.
b4cd2f8 @hcatlin removing offending rdoc line
authored
206 * On nesting and associations: {here}[http://nex-3.com/posts/55-nesting-and-make_resourceful].
69c450e @hcatlin adding back in more lines
authored
207 * An overview of make_resourceful 0.2.0 and 0.2.2: {here}[http://localhost:3000/posts/54-make_resourceful-0-2-0].
b4cd2f8 @hcatlin removing offending rdoc line
authored
208 * On Resourceful::Builder#publish
69c450e @hcatlin adding back in more lines
authored
209 and Resourceful::Serialize:
210 {here}[http://nex-3.com/posts/35-make_resourceful-the-basics-of-publish] and
211 {here}[http://nex-3.com/posts/36-make_resourceful-publish-extras].
212 * There's an excellent, active Google Group http://groups.google.com/group/make_resourceful
213 where people will be happy to answer your questions.
470a4c3 initial import from svn
Hampton Catlin authored
214
215 ---
216
5c190ad @hcatlin updating license... jeff revoked his
authored
217 Copyright 2007-2010 Hampton Catlin and Nathan Weizenbaum.
470a4c3 initial import from svn
Hampton Catlin authored
218 Contributions by:
219
220 * Russell Norris
221 * Jonathan Linowes
222 * Cristi Balan
223 * Mike Ferrier
224 * James Golick
225 * Don Petersen
226 * Alex Ross
227 * Tom Stuart
afd76c2 @hcatlin the best job i could do on specs
authored
228 * Glenn Powell
229 * Johannes Jörg Schmidt
Something went wrong with that request. Please try again.