Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 342 lines (235 sloc) 10.424 kb
a1023b0 Mislav Marohnić improve Action Pack README
mislav authored
1 = Action Pack -- From request to response
db045db David Heinemeier Hansson Initial
dhh authored
2
b3bb684 Mark Hayes removed duplicate word
mhayes authored
3 Action Pack is a framework for handling and responding to web requests. It
a1023b0 Mislav Marohnić 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 David Heinemeier Hansson Initial
dhh authored
8
a1023b0 Mislav Marohnić improve Action Pack README
mislav authored
9 It consists of several modules:
db045db David Heinemeier Hansson Initial
dhh authored
10
a1023b0 Mislav Marohnić 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 David Heinemeier Hansson Initial
dhh authored
15
a1023b0 Mislav Marohnić 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 Akira Matsuda s/ERb/ERB/g (part II)
amatsuda authored
22 Template formats that Action View handles are ERB (embedded Ruby, typically
16bccca Xavier Noria removed references to RJS from the AP README
fxn authored
23 used to inline short Ruby snippets inside HTML), and XML Builder.
a1023b0 Mislav Marohnić 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 David Heinemeier Hansson Initial
dhh authored
32
33 * Actions grouped in controller as methods instead of separate command objects
0432d15 Pratik Merge with docrails.
lifo authored
34 and can therefore share helper methods
db045db David Heinemeier Hansson Initial
dhh authored
35
110a066 Vijay Dev fix coding error in readme reported in rails GH #980
vijaydev authored
36 class CustomersController < ActionController::Base
b6afb28 David Heinemeier Hansson Nitpick updates
dhh authored
37 def show
db045db David Heinemeier Hansson Initial
dhh authored
38 @customer = find_customer
39 end
b378764 Joshua Peek Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
40
db045db David Heinemeier Hansson Initial
dhh authored
41 def update
42 @customer = find_customer
a1023b0 Mislav Marohnić 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 David Heinemeier Hansson Initial
dhh authored
48 end
b378764 Joshua Peek Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
49
db045db David Heinemeier Hansson Initial
dhh authored
50 private
a1023b0 Mislav Marohnić improve Action Pack README
mislav authored
51 def find_customer
52 Customer.find params[:id]
53 end
db045db David Heinemeier Hansson Initial
dhh authored
54 end
55
e4efcfd David Heinemeier Hansson Updated documentation
dhh authored
56 {Learn more}[link:classes/ActionController/Base.html]
db045db David Heinemeier Hansson Initial
dhh authored
57
58
9bf5cdd Akira Matsuda s/ERb/ERB/g (part II)
amatsuda authored
59 * ERB templates (static content mixed with dynamic output from ruby)
db045db David Heinemeier Hansson Initial
dhh authored
60
8630cd4 Arun Agrawal README updated for for => each
arunagw authored
61 <% @posts.each do |post| %>
db045db David Heinemeier Hansson Initial
dhh authored
62 Title: <%= post.title %>
63 <% end %>
64
a1023b0 Mislav Marohnić improve Action Pack README
mislav authored
65 All post titles: <%= @posts.collect{ |p| p.title }.join(", ") %>
db045db David Heinemeier Hansson Initial
dhh authored
66
67 <% unless @person.is_client? %>
68 Not for clients to see...
69 <% end %>
b378764 Joshua Peek Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
70
e4efcfd David Heinemeier Hansson Updated documentation
dhh authored
71 {Learn more}[link:classes/ActionView.html]
db045db David Heinemeier Hansson Initial
dhh authored
72
73
a1023b0 Mislav Marohnić improve Action Pack README
mislav authored
74 * "Builder" templates (great for XML content, like RSS)
db045db David Heinemeier Hansson Initial
dhh authored
75
e4efcfd David Heinemeier Hansson 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 Arun Agrawal README updated for for => each
arunagw authored
84 @recent_items.each do |item|
e4efcfd David Heinemeier Hansson 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 David Heinemeier Hansson Initial
dhh authored
92 end
93 end
94 end
e4efcfd David Heinemeier Hansson Updated documentation
dhh authored
95
96 {Learn more}[link:classes/ActionView/Base.html]
db045db David Heinemeier Hansson Initial
dhh authored
97
98
a1023b0 Mislav Marohnić improve Action Pack README
mislav authored
99 * Filters for pre- and post-processing of the response
db045db David Heinemeier Hansson Initial
dhh authored
100
101 class WeblogController < ActionController::Base
a1023b0 Mislav Marohnić improve Action Pack README
mislav authored
102 # filters as methods
db045db David Heinemeier Hansson Initial
dhh authored
103 before_filter :authenticate, :cache, :audit
b451de0 Santiago Pastorino Deletes trailing whitespaces (over text files only find * -type f -exec ...
spastorino authored
104
a1023b0 Mislav Marohnić improve Action Pack README
mislav authored
105 # filter as a proc
2a9ad9c David Heinemeier Hansson Moved the caching stores from ActionController::Caching::Fragments::* to...
dhh authored
106 after_filter { |c| c.response.body = Gzip::compress(c.response.body) }
b451de0 Santiago Pastorino Deletes trailing whitespaces (over text files only find * -type f -exec ...
spastorino authored
107
a1023b0 Mislav Marohnić improve Action Pack README
mislav authored
108 # class filter
db045db David Heinemeier Hansson Initial
dhh authored
109 after_filter LocalizeFilter
b378764 Joshua Peek Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
110
b6afb28 David Heinemeier Hansson Nitpick updates
dhh authored
111 def index
db045db David Heinemeier Hansson 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 David Heinemeier Hansson Fix READMEs (closes #2680) [coffee2code]
dhh authored
114 # exists, and the action will be logged for auditing.
b378764 Joshua Peek 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 David Heinemeier Hansson Fix READMEs (closes #2680) [coffee2code]
dhh authored
117 # compressed to minimize bandwidth usage
db045db David Heinemeier Hansson Initial
dhh authored
118 end
b378764 Joshua Peek Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
119
db045db David Heinemeier Hansson Initial
dhh authored
120 private
121 def authenticate
6ab9f2b David Heinemeier Hansson Fix READMEs (closes #2680) [coffee2code]
dhh authored
122 # Implement the filter with full access to both request and response
db045db David Heinemeier Hansson Initial
dhh authored
123 end
124 end
b378764 Joshua Peek Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
125
e4efcfd David Heinemeier Hansson Updated documentation
dhh authored
126 {Learn more}[link:classes/ActionController/Filters/ClassMethods.html]
b378764 Joshua Peek Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
127
db045db David Heinemeier Hansson Initial
dhh authored
128
129 * Helpers for forms, dates, action links, and text
130
a1023b0 Mislav Marohnić improve Action Pack README
mislav authored
131 <%= text_field_tag "post", "title", "size" => 30 %>
db045db David Heinemeier Hansson Initial
dhh authored
132 <%= link_to "New post", :controller => "post", :action => "new" %>
dbbae5e Pratik Merge with docrails
lifo authored
133 <%= truncate(post.title, :length => 25) %>
b378764 Joshua Peek Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
134
e4efcfd David Heinemeier Hansson Updated documentation
dhh authored
135 {Learn more}[link:classes/ActionView/Helpers.html]
db045db David Heinemeier Hansson Initial
dhh authored
136
137
a1023b0 Mislav Marohnić improve Action Pack README
mislav authored
138 * Layout sharing for template reuse
db045db David Heinemeier Hansson Initial
dhh authored
139
140 class WeblogController < ActionController::Base
141 layout "weblog_layout"
b378764 Joshua Peek Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
142
db045db David Heinemeier Hansson 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 Joshua Peek Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
149
db045db David Heinemeier Hansson Initial
dhh authored
150 Template for hello_world action:
151 <h1>Hello world</h1>
b378764 Joshua Peek Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
152
db045db David Heinemeier Hansson Initial
dhh authored
153 Result of running hello_world action:
154 <html><body><h1>Hello world</h1></body></html>
155
e4efcfd David Heinemeier Hansson Updated documentation
dhh authored
156 {Learn more}[link:classes/ActionController/Layout/ClassMethods.html]
db045db David Heinemeier Hansson Initial
dhh authored
157
158
a1023b0 Mislav Marohnić improve Action Pack README
mislav authored
159 * Routing makes pretty URLs incredibly easy
db045db David Heinemeier Hansson Initial
dhh authored
160
a1023b0 Mislav Marohnić improve Action Pack README
mislav authored
161 match 'clients/:client_name/:project_name/:controller/:action'
db045db David Heinemeier Hansson Initial
dhh authored
162
a1023b0 Mislav Marohnić 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 Joshua Peek Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
165
a1023b0 Mislav Marohnić improve Action Pack README
mislav authored
166 From that action, you can write the redirect in a number of ways:
b378764 Joshua Peek Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
167
db045db David Heinemeier Hansson Initial
dhh authored
168 redirect_to(:action => "edit") =>
a1023b0 Mislav Marohnić improve Action Pack README
mislav authored
169 /clients/37signals/basecamp/project/edit
db045db David Heinemeier Hansson Initial
dhh authored
170
e4efcfd David Heinemeier Hansson Updated documentation
dhh authored
171 redirect_to(:client_name => "nextangle", :project_name => "rails") =>
a1023b0 Mislav Marohnić improve Action Pack README
mislav authored
172 /clients/nextangle/rails/project/index
db045db David Heinemeier Hansson Initial
dhh authored
173
a1023b0 Mislav Marohnić improve Action Pack README
mislav authored
174 {Learn more}[link:classes/ActionDispatch/Routing.html]
db045db David Heinemeier Hansson Initial
dhh authored
175
176
0432d15 Pratik Merge with docrails.
lifo authored
177 * Easy testing of both controller and rendered template through ActionController::TestCase
db045db David Heinemeier Hansson Initial
dhh authored
178
0432d15 Pratik Merge with docrails.
lifo authored
179 class LoginControllerTest < ActionController::TestCase
db045db David Heinemeier Hansson Initial
dhh authored
180 def test_failing_authenticate
1c057b7 Jamis Buck Update/clean up AP documentation (rdoc)
jamis authored
181 process :authenticate, :user_name => "nop", :password => ""
182 assert flash.has_key?(:alert)
db045db David Heinemeier Hansson Initial
dhh authored
183 assert_redirected_to :action => "index"
184 end
185 end
186
0432d15 Pratik Merge with docrails.
lifo authored
187 {Learn more}[link:classes/ActionController/TestCase.html]
db045db David Heinemeier Hansson Initial
dhh authored
188
189
190 * Automated benchmarking and integrated logging
191
46dd8af Paco Guzmán 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 David Heinemeier Hansson Initial
dhh authored
196
197 If Active Record is used as the model, you'll have the database debugging
198 as well:
199
46dd8af Paco Guzmán 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 Pratik Merge with docrails
lifo authored
204 Redirected to http://example.com/posts/5
46dd8af Paco Guzmán Update integrated logging format
pacoguzman authored
205 Completed 302 Found in 221ms (Views: 215ms | ActiveRecord: 0.6ms)
db045db David Heinemeier Hansson Initial
dhh authored
206
207 You specify a logger through a class method, such as:
208
209 ActionController::Base.logger = Logger.new("Application Log")
210 ActionController::Base.logger = Log4r::Logger.new("Application Log")
211
212
e4efcfd David Heinemeier Hansson 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 Joshua Peek Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
218
e4efcfd David Heinemeier Hansson Updated documentation
dhh authored
219 def show
b378764 Joshua Peek Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
220 # the output of the method will be cached as
168e653 Alexey Vakhov Fix actionpack readme weblog example
avakhov authored
221 # ActionController::Base.page_cache_directory + "/weblog/show.html"
e4efcfd David Heinemeier Hansson Updated documentation
dhh authored
222 # and the web server will pick it up without even hitting Rails
223 end
b378764 Joshua Peek Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
224
e4efcfd David Heinemeier Hansson 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 Joshua Peek Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
229
e4efcfd David Heinemeier Hansson Updated documentation
dhh authored
230 def update
1c057b7 Jamis Buck 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 David Heinemeier Hansson Updated documentation
dhh authored
233 expire_action :action => "account"
1c057b7 Jamis Buck Update/clean up AP documentation (rdoc)
jamis authored
234 redirect_to :action => "show", :id => params[:list][:id]
e4efcfd David Heinemeier Hansson Updated documentation
dhh authored
235 end
236 end
237
238 {Learn more}[link:classes/ActionController/Caching.html]
239
240
db045db David Heinemeier Hansson 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 David Heinemeier Hansson Updated documentation
dhh authored
248 {Learn more}[link:classes/ActionController/Rescue.html]
db045db David Heinemeier Hansson Initial
dhh authored
249
250
b6afb28 David Heinemeier Hansson Nitpick updates
dhh authored
251 == Simple example (from outside of Rails)
db045db David Heinemeier Hansson Initial
dhh authored
252
253 This example will implement a simple weblog system using inline templates and
e4efcfd David Heinemeier Hansson Updated documentation
dhh authored
254 an Active Record model. So let's build that WeblogController with just a few
db045db David Heinemeier Hansson Initial
dhh authored
255 methods:
256
257 require 'action_controller'
258 require 'post'
e4efcfd David Heinemeier Hansson Updated documentation
dhh authored
259
db045db David Heinemeier Hansson Initial
dhh authored
260 class WeblogController < ActionController::Base
261 layout "weblog/layout"
b378764 Joshua Peek Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
262
db045db David Heinemeier Hansson Initial
dhh authored
263 def index
4038a6b Vijay Dev minor fixesin READMEs
vijaydev authored
264 @posts = Post.all
db045db David Heinemeier Hansson Initial
dhh authored
265 end
b378764 Joshua Peek Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
266
dbbae5e Pratik Merge with docrails
lifo authored
267 def show
0049bd7 Update README
Marcel Molina authored
268 @post = Post.find(params[:id])
db045db David Heinemeier Hansson Initial
dhh authored
269 end
b378764 Joshua Peek Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
270
db045db David Heinemeier Hansson Initial
dhh authored
271 def new
272 @post = Post.new
273 end
b378764 Joshua Peek Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
274
db045db David Heinemeier Hansson Initial
dhh authored
275 def create
1c057b7 Jamis Buck Update/clean up AP documentation (rdoc)
jamis authored
276 @post = Post.create(params[:post])
dbbae5e Pratik Merge with docrails
lifo authored
277 redirect_to :action => "show", :id => @post.id
db045db David Heinemeier Hansson Initial
dhh authored
278 end
279 end
280
69b0e5c risk danger olson Allow Controllers to have multiple view_paths instead of a single templa...
technoweenie authored
281 WeblogController::Base.view_paths = [ File.dirname(__FILE__) ]
db045db David Heinemeier Hansson 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 Lue rephrase "like to be"
waynn authored
286 request from the web-server (e.g., Apache).
db045db David Heinemeier Hansson Initial
dhh authored
287
288 And the templates look like this:
289
dbbae5e Pratik Merge with docrails
lifo authored
290 weblog/layout.html.erb:
db045db David Heinemeier Hansson Initial
dhh authored
291 <html><body>
0049bd7 Update README
Marcel Molina authored
292 <%= yield %>
db045db David Heinemeier Hansson Initial
dhh authored
293 </body></html>
294
dbbae5e Pratik Merge with docrails
lifo authored
295 weblog/index.html.erb:
8630cd4 Arun Agrawal README updated for for => each
arunagw authored
296 <% @posts.each do |post| %>
dbbae5e Pratik Merge with docrails
lifo authored
297 <p><%= link_to(post.title, :action => "show", :id => post.id) %></p>
db045db David Heinemeier Hansson Initial
dhh authored
298 <% end %>
299
dbbae5e Pratik Merge with docrails
lifo authored
300 weblog/show.html.erb:
db045db David Heinemeier Hansson Initial
dhh authored
301 <p>
dbbae5e Pratik Merge with docrails
lifo authored
302 <b><%= @post.title %></b><br/>
303 <b><%= @post.content %></b>
db045db David Heinemeier Hansson Initial
dhh authored
304 </p>
305
dbbae5e Pratik Merge with docrails
lifo authored
306 weblog/new.html.erb:
db045db David Heinemeier Hansson Initial
dhh authored
307 <%= form "post" %>
b378764 Joshua Peek Move link_to_function and link_to_remote into prototype_legacy_helper
josh authored
308
db045db David Heinemeier Hansson 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 David Heinemeier Hansson Fix READMEs (closes #2680) [coffee2code]
dhh authored
311 Record model to make the new screen, which in turn hands everything over to
db045db David Heinemeier Hansson Initial
dhh authored
312 the create action (that's the default target for the form builder when given a
dbbae5e Pratik 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 David Heinemeier Hansson Initial
dhh authored
315
316
89b5e79 Mislav Marohnić revise download/installation/support sections in READMEs
mislav authored
317 == Download and installation
db045db David Heinemeier Hansson Initial
dhh authored
318
b905f8c Sukeerthi Adiga Rubygems => RubyGems
sukeerthiadiga authored
319 The latest version of Action Pack can be installed with RubyGems:
db045db David Heinemeier Hansson Initial
dhh authored
320
89b5e79 Mislav Marohnić revise download/installation/support sections in READMEs
mislav authored
321 % [sudo] gem install actionpack
db045db David Heinemeier Hansson Initial
dhh authored
322
89b5e79 Mislav Marohnić revise download/installation/support sections in READMEs
mislav authored
323 Source code can be downloaded as part of the Rails project on GitHub
db045db David Heinemeier Hansson Initial
dhh authored
324
21b1a79 Arun Agrawal Updated other README to point 3-2-stable
arunagw authored
325 * https://github.com/rails/rails/tree/3-2-stable/actionpack
db045db David Heinemeier Hansson Initial
dhh authored
326
327
328 == License
329
b3bfe13 David Heinemeier Hansson Updated the license (still referered to the old ruby one)
dhh authored
330 Action Pack is released under the MIT license.
db045db David Heinemeier Hansson Initial
dhh authored
331
332
333 == Support
334
89b5e79 Mislav Marohnić revise download/installation/support sections in READMEs
mislav authored
335 API documentation is at
db045db David Heinemeier Hansson Initial
dhh authored
336
bfb9f75 Karunakar (Ruby) changed http://api.rubyonrails.com to http://api.rubyonrails.org in rea...
Karunakar authored
337 * http://api.rubyonrails.org
89b5e79 Mislav Marohnić revise download/installation/support sections in READMEs
mislav authored
338
339 Bug reports and feature requests can be filed with the rest for the Ruby on Rails project here:
340
9870afb Arun Agrawal Some readme fixes as required.
arunagw authored
341 * https://github.com/rails/rails/issues
Something went wrong with that request. Please try again.