Skip to content

HTTPS clone URL

Subversion checkout URL

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