Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 343 lines (236 sloc) 10.499 kb
a1023b0 @mislav improve Action Pack README
mislav authored
1 = Action Pack -- From request to response
db045db @dhh Initial
dhh authored
2
b3bb684 @mhayes removed duplicate word
mhayes authored
3 Action Pack is a framework for handling and responding to web requests. It
a1023b0 @mislav improve Action Pack README
mislav authored
4 provides mechanisms for *routing* (mapping request URLs to actions), defining
5 *controllers* that implement actions, and generating responses by rendering
6 *views*, which are templates of various formats. In short, Action Pack
7 provides the view and controller layers in the MVC paradigm.
db045db @dhh Initial
dhh authored
8
a1023b0 @mislav improve Action Pack README
mislav authored
9 It consists of several modules:
db045db @dhh Initial
dhh authored
10
a1023b0 @mislav improve Action Pack README
mislav authored
11 * Action Dispatch, which parses information about the web request, handles
12 routing as defined by the user, and does advanced processing related to HTTP
13 such as MIME-type negotiation, decoding parameters in POST/PUT bodies,
14 handling HTTP caching logic, cookies and sessions.
db045db @dhh Initial
dhh authored
15
a1023b0 @mislav improve Action Pack README
mislav authored
16 * Action Controller, which provides a base controller class that can be
17 subclassed to implement filters and actions to handle requests. The result
18 of an action is typically content generated from views.
19
20 * Action View, which handles view template lookup and rendering, and provides
21 view helpers that assist when building HTML forms, Atom feeds and more.
22 Template formats that Action View handles are ERb (embedded Ruby, typically
23 used to inline short Ruby snippets inside HTML), XML Builder and RJS
24 (dynamically generated JavaScript from Ruby code).
25
26 With the Ruby on Rails framework, users only directly interface with the
27 Action Controller module. Necessary Action Dispatch functionality is activated
28 by default and Action View rendering is implicitly triggered by Action
29 Controller. However, these modules are designed to function on their own and
30 can be used outside of Rails.
31
32 A short rundown of some of the major features:
db045db @dhh Initial
dhh authored
33
34 * Actions grouped in controller as methods instead of separate command objects
0432d15 @lifo Merge with docrails.
lifo authored
35 and can therefore share helper methods
db045db @dhh Initial
dhh authored
36
dbbae5e @lifo Merge with docrails
lifo authored
37 CustomersController < ActionController::Base
b6afb28 @dhh Nitpick updates
dhh authored
38 def show
db045db @dhh Initial
dhh authored
39 @customer = find_customer
40 end
b378764 @josh Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
41
db045db @dhh Initial
dhh authored
42 def update
43 @customer = find_customer
a1023b0 @mislav improve Action Pack README
mislav authored
44 if @customer.update_attributes(params[:customer])
45 redirect_to :action => "show"
46 else
47 render :action => "edit"
48 end
db045db @dhh Initial
dhh authored
49 end
b378764 @josh Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
50
db045db @dhh Initial
dhh authored
51 private
a1023b0 @mislav improve Action Pack README
mislav authored
52 def find_customer
53 Customer.find params[:id]
54 end
db045db @dhh Initial
dhh authored
55 end
56
e4efcfd @dhh Updated documentation
dhh authored
57 {Learn more}[link:classes/ActionController/Base.html]
db045db @dhh Initial
dhh authored
58
59
a1023b0 @mislav improve Action Pack README
mislav authored
60 * ERb templates (static content mixed with dynamic output from ruby)
db045db @dhh Initial
dhh authored
61
62 <% for post in @posts %>
63 Title: <%= post.title %>
64 <% end %>
65
a1023b0 @mislav improve Action Pack README
mislav authored
66 All post titles: <%= @posts.collect{ |p| p.title }.join(", ") %>
db045db @dhh Initial
dhh authored
67
68 <% unless @person.is_client? %>
69 Not for clients to see...
70 <% end %>
b378764 @josh Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
71
e4efcfd @dhh Updated documentation
dhh authored
72 {Learn more}[link:classes/ActionView.html]
db045db @dhh Initial
dhh authored
73
74
a1023b0 @mislav improve Action Pack README
mislav authored
75 * "Builder" templates (great for XML content, like RSS)
db045db @dhh Initial
dhh authored
76
e4efcfd @dhh Updated documentation
dhh authored
77 xml.rss("version" => "2.0") do
78 xml.channel do
79 xml.title(@feed_title)
80 xml.link(@url)
81 xml.description "Basecamp: Recent items"
82 xml.language "en-us"
83 xml.ttl "40"
84
85 for item in @recent_items
86 xml.item do
87 xml.title(item_title(item))
88 xml.description(item_description(item))
89 xml.pubDate(item_pubDate(item))
90 xml.guid(@recent_items.url(item))
91 xml.link(@recent_items.url(item))
92 end
db045db @dhh Initial
dhh authored
93 end
94 end
95 end
e4efcfd @dhh Updated documentation
dhh authored
96
97 {Learn more}[link:classes/ActionView/Base.html]
db045db @dhh Initial
dhh authored
98
99
a1023b0 @mislav improve Action Pack README
mislav authored
100 * Filters for pre- and post-processing of the response
db045db @dhh Initial
dhh authored
101
102 class WeblogController < ActionController::Base
a1023b0 @mislav improve Action Pack README
mislav authored
103 # filters as methods
db045db @dhh Initial
dhh authored
104 before_filter :authenticate, :cache, :audit
b451de0 @spastorino Deletes trailing whitespaces (over text files only find * -type f -exec ...
spastorino authored
105
a1023b0 @mislav improve Action Pack README
mislav authored
106 # filter as a proc
2a9ad9c @dhh Moved the caching stores from ActionController::Caching::Fragments::* to...
dhh authored
107 after_filter { |c| c.response.body = Gzip::compress(c.response.body) }
b451de0 @spastorino Deletes trailing whitespaces (over text files only find * -type f -exec ...
spastorino authored
108
a1023b0 @mislav improve Action Pack README
mislav authored
109 # class filter
db045db @dhh Initial
dhh authored
110 after_filter LocalizeFilter
b378764 @josh Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
111
b6afb28 @dhh Nitpick updates
dhh authored
112 def index
db045db @dhh Initial
dhh authored
113 # Before this action is run, the user will be authenticated, the cache
114 # will be examined to see if a valid copy of the results already
6ab9f2b @dhh Fix READMEs (closes #2680) [coffee2code]
dhh authored
115 # exists, and the action will be logged for auditing.
b378764 @josh Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
116
117 # After this action has run, the output will first be localized then
6ab9f2b @dhh Fix READMEs (closes #2680) [coffee2code]
dhh authored
118 # compressed to minimize bandwidth usage
db045db @dhh Initial
dhh authored
119 end
b378764 @josh Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
120
db045db @dhh Initial
dhh authored
121 private
122 def authenticate
6ab9f2b @dhh Fix READMEs (closes #2680) [coffee2code]
dhh authored
123 # Implement the filter with full access to both request and response
db045db @dhh Initial
dhh authored
124 end
125 end
b378764 @josh Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
126
e4efcfd @dhh Updated documentation
dhh authored
127 {Learn more}[link:classes/ActionController/Filters/ClassMethods.html]
b378764 @josh Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
128
db045db @dhh Initial
dhh authored
129
130 * Helpers for forms, dates, action links, and text
131
a1023b0 @mislav improve Action Pack README
mislav authored
132 <%= text_field_tag "post", "title", "size" => 30 %>
db045db @dhh Initial
dhh authored
133 <%= link_to "New post", :controller => "post", :action => "new" %>
dbbae5e @lifo Merge with docrails
lifo authored
134 <%= truncate(post.title, :length => 25) %>
b378764 @josh Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
135
e4efcfd @dhh Updated documentation
dhh authored
136 {Learn more}[link:classes/ActionView/Helpers.html]
db045db @dhh Initial
dhh authored
137
138
a1023b0 @mislav improve Action Pack README
mislav authored
139 * Layout sharing for template reuse
db045db @dhh Initial
dhh authored
140
141 class WeblogController < ActionController::Base
142 layout "weblog_layout"
b378764 @josh Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
143
db045db @dhh Initial
dhh authored
144 def hello_world
145 end
146 end
147
148 Layout file (called weblog_layout):
0049bd7 Update README
Marcel Molina authored
149 <html><body><%= yield %></body></html>
b378764 @josh Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
150
db045db @dhh Initial
dhh authored
151 Template for hello_world action:
152 <h1>Hello world</h1>
b378764 @josh Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
153
db045db @dhh Initial
dhh authored
154 Result of running hello_world action:
155 <html><body><h1>Hello world</h1></body></html>
156
e4efcfd @dhh Updated documentation
dhh authored
157 {Learn more}[link:classes/ActionController/Layout/ClassMethods.html]
db045db @dhh Initial
dhh authored
158
159
a1023b0 @mislav improve Action Pack README
mislav authored
160 * Routing makes pretty URLs incredibly easy
db045db @dhh Initial
dhh authored
161
a1023b0 @mislav improve Action Pack README
mislav authored
162 match 'clients/:client_name/:project_name/:controller/:action'
db045db @dhh Initial
dhh authored
163
a1023b0 @mislav improve Action Pack README
mislav authored
164 Accessing "/clients/37signals/basecamp/project/index" calls ProjectController#index with
165 { "client_name" => "37signals", "project_name" => "basecamp" } in `params`
b378764 @josh Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
166
a1023b0 @mislav improve Action Pack README
mislav authored
167 From that action, you can write the redirect in a number of ways:
b378764 @josh Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
168
db045db @dhh Initial
dhh authored
169 redirect_to(:action => "edit") =>
a1023b0 @mislav improve Action Pack README
mislav authored
170 /clients/37signals/basecamp/project/edit
db045db @dhh Initial
dhh authored
171
e4efcfd @dhh Updated documentation
dhh authored
172 redirect_to(:client_name => "nextangle", :project_name => "rails") =>
a1023b0 @mislav improve Action Pack README
mislav authored
173 /clients/nextangle/rails/project/index
db045db @dhh Initial
dhh authored
174
a1023b0 @mislav improve Action Pack README
mislav authored
175 {Learn more}[link:classes/ActionDispatch/Routing.html]
db045db @dhh Initial
dhh authored
176
177
0432d15 @lifo Merge with docrails.
lifo authored
178 * Easy testing of both controller and rendered template through ActionController::TestCase
db045db @dhh Initial
dhh authored
179
0432d15 @lifo Merge with docrails.
lifo authored
180 class LoginControllerTest < ActionController::TestCase
db045db @dhh Initial
dhh authored
181 def test_failing_authenticate
1c057b7 @jamis Update/clean up AP documentation (rdoc)
jamis authored
182 process :authenticate, :user_name => "nop", :password => ""
183 assert flash.has_key?(:alert)
db045db @dhh Initial
dhh authored
184 assert_redirected_to :action => "index"
185 end
186 end
187
0432d15 @lifo Merge with docrails.
lifo authored
188 {Learn more}[link:classes/ActionController/TestCase.html]
db045db @dhh Initial
dhh authored
189
190
191 * Automated benchmarking and integrated logging
192
46dd8af @pacoguzman Update integrated logging format
pacoguzman authored
193 Started GET "/weblog" for 127.0.0.1 at Fri May 28 00:41:55
194 Processing by WeblogController#index as HTML
195 Rendered weblog/index.html.erb within layouts/application (25.7ms)
196 Completed 200 OK in 29.3ms
db045db @dhh Initial
dhh authored
197
198 If Active Record is used as the model, you'll have the database debugging
199 as well:
200
46dd8af @pacoguzman Update integrated logging format
pacoguzman authored
201 Started POST "/posts" for 127.0.0.1 at Sat Jun 19 14:04:23
202 Processing by PostsController#create as HTML
203 Parameters: {"post"=>{"title"=>"this is good"}}
204 SQL (0.6ms) INSERT INTO posts (title) VALUES('this is good')
dbbae5e @lifo Merge with docrails
lifo authored
205 Redirected to http://example.com/posts/5
46dd8af @pacoguzman Update integrated logging format
pacoguzman authored
206 Completed 302 Found in 221ms (Views: 215ms | ActiveRecord: 0.6ms)
db045db @dhh Initial
dhh authored
207
208 You specify a logger through a class method, such as:
209
210 ActionController::Base.logger = Logger.new("Application Log")
211 ActionController::Base.logger = Log4r::Logger.new("Application Log")
212
213
e4efcfd @dhh Updated documentation
dhh authored
214 * Caching at three levels of granularity (page, action, fragment)
215
216 class WeblogController < ActionController::Base
217 caches_page :show
218 caches_action :account
b378764 @josh Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
219
e4efcfd @dhh Updated documentation
dhh authored
220 def show
b378764 @josh Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
221 # the output of the method will be cached as
e4efcfd @dhh Updated documentation
dhh authored
222 # ActionController::Base.page_cache_directory + "/weblog/show/n.html"
223 # and the web server will pick it up without even hitting Rails
224 end
b378764 @josh Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
225
e4efcfd @dhh Updated documentation
dhh authored
226 def account
227 # the output of the method will be cached in the fragment store
228 # but Rails is hit to retrieve it, so filters are run
229 end
b378764 @josh Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
230
e4efcfd @dhh Updated documentation
dhh authored
231 def update
1c057b7 @jamis Update/clean up AP documentation (rdoc)
jamis authored
232 List.update(params[:list][:id], params[:list])
233 expire_page :action => "show", :id => params[:list][:id]
e4efcfd @dhh Updated documentation
dhh authored
234 expire_action :action => "account"
1c057b7 @jamis Update/clean up AP documentation (rdoc)
jamis authored
235 redirect_to :action => "show", :id => params[:list][:id]
e4efcfd @dhh Updated documentation
dhh authored
236 end
237 end
238
239 {Learn more}[link:classes/ActionController/Caching.html]
240
241
db045db @dhh Initial
dhh authored
242 * Powerful debugging mechanism for local requests
243
244 All exceptions raised on actions performed on the request of a local user
245 will be presented with a tailored debugging screen that includes exception
246 message, stack trace, request parameters, session contents, and the
247 half-finished response.
248
e4efcfd @dhh Updated documentation
dhh authored
249 {Learn more}[link:classes/ActionController/Rescue.html]
db045db @dhh Initial
dhh authored
250
251
b6afb28 @dhh Nitpick updates
dhh authored
252 == Simple example (from outside of Rails)
db045db @dhh Initial
dhh authored
253
254 This example will implement a simple weblog system using inline templates and
e4efcfd @dhh Updated documentation
dhh authored
255 an Active Record model. So let's build that WeblogController with just a few
db045db @dhh Initial
dhh authored
256 methods:
257
258 require 'action_controller'
259 require 'post'
e4efcfd @dhh Updated documentation
dhh authored
260
db045db @dhh Initial
dhh authored
261 class WeblogController < ActionController::Base
262 layout "weblog/layout"
b378764 @josh Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
263
db045db @dhh Initial
dhh authored
264 def index
4038a6b @vijaydev minor fixesin READMEs
vijaydev authored
265 @posts = Post.all
db045db @dhh Initial
dhh authored
266 end
b378764 @josh Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
267
dbbae5e @lifo Merge with docrails
lifo authored
268 def show
0049bd7 Update README
Marcel Molina authored
269 @post = Post.find(params[:id])
db045db @dhh Initial
dhh authored
270 end
b378764 @josh Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
271
db045db @dhh Initial
dhh authored
272 def new
273 @post = Post.new
274 end
b378764 @josh Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
275
db045db @dhh Initial
dhh authored
276 def create
1c057b7 @jamis Update/clean up AP documentation (rdoc)
jamis authored
277 @post = Post.create(params[:post])
dbbae5e @lifo Merge with docrails
lifo authored
278 redirect_to :action => "show", :id => @post.id
db045db @dhh Initial
dhh authored
279 end
280 end
281
69b0e5c @technoweenie Allow Controllers to have multiple view_paths instead of a single templa...
technoweenie authored
282 WeblogController::Base.view_paths = [ File.dirname(__FILE__) ]
db045db @dhh Initial
dhh authored
283 WeblogController.process_cgi if $0 == __FILE__
284
285 The last two lines are responsible for telling ActionController where the
286 template files are located and actually running the controller on a new
287 request from the web-server (like to be Apache).
288
289 And the templates look like this:
290
dbbae5e @lifo Merge with docrails
lifo authored
291 weblog/layout.html.erb:
db045db @dhh Initial
dhh authored
292 <html><body>
0049bd7 Update README
Marcel Molina authored
293 <%= yield %>
db045db @dhh Initial
dhh authored
294 </body></html>
295
dbbae5e @lifo Merge with docrails
lifo authored
296 weblog/index.html.erb:
db045db @dhh Initial
dhh authored
297 <% for post in @posts %>
dbbae5e @lifo Merge with docrails
lifo authored
298 <p><%= link_to(post.title, :action => "show", :id => post.id) %></p>
db045db @dhh Initial
dhh authored
299 <% end %>
300
dbbae5e @lifo Merge with docrails
lifo authored
301 weblog/show.html.erb:
db045db @dhh Initial
dhh authored
302 <p>
dbbae5e @lifo Merge with docrails
lifo authored
303 <b><%= @post.title %></b><br/>
304 <b><%= @post.content %></b>
db045db @dhh Initial
dhh authored
305 </p>
306
dbbae5e @lifo Merge with docrails
lifo authored
307 weblog/new.html.erb:
db045db @dhh Initial
dhh authored
308 <%= form "post" %>
b378764 @josh Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
309
db045db @dhh Initial
dhh authored
310 This simple setup will list all the posts in the system on the index page,
311 which is called by accessing /weblog/. It uses the form builder for the Active
6ab9f2b @dhh Fix READMEs (closes #2680) [coffee2code]
dhh authored
312 Record model to make the new screen, which in turn hands everything over to
db045db @dhh Initial
dhh authored
313 the create action (that's the default target for the form builder when given a
dbbae5e @lifo Merge with docrails
lifo authored
314 new model). After creating the post, it'll redirect to the show page using
315 an URL such as /weblog/5 (where 5 is the id of the post).
db045db @dhh Initial
dhh authored
316
317
89b5e79 @mislav revise download/installation/support sections in READMEs
mislav authored
318 == Download and installation
db045db @dhh Initial
dhh authored
319
f1082bd @josevalim Remove old install.rb files.
josevalim authored
320 The latest version of Action Pack can be installed with Rubygems:
db045db @dhh Initial
dhh authored
321
89b5e79 @mislav revise download/installation/support sections in READMEs
mislav authored
322 % [sudo] gem install actionpack
db045db @dhh Initial
dhh authored
323
89b5e79 @mislav revise download/installation/support sections in READMEs
mislav authored
324 Source code can be downloaded as part of the Rails project on GitHub
db045db @dhh Initial
dhh authored
325
5bed377 @amatsuda "SSL everywhere" for GitHub URLs
amatsuda authored
326 * https://github.com/rails/rails/tree/master/actionpack/
db045db @dhh Initial
dhh authored
327
328
329 == License
330
b3bfe13 @dhh Updated the license (still referered to the old ruby one)
dhh authored
331 Action Pack is released under the MIT license.
db045db @dhh Initial
dhh authored
332
333
334 == Support
335
89b5e79 @mislav revise download/installation/support sections in READMEs
mislav authored
336 API documentation is at
db045db @dhh Initial
dhh authored
337
89b5e79 @mislav revise download/installation/support sections in READMEs
mislav authored
338 * http://api.rubyonrails.com
339
340 Bug reports and feature requests can be filed with the rest for the Ruby on Rails project here:
341
342 * https://rails.lighthouseapp.com/projects/8994-ruby-on-rails/tickets
Something went wrong with that request. Please try again.