Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 145 lines (104 sloc) 4.328 kb
150ed62 @rafaelfranca Change README to markdown
rafaelfranca authored
1 # Responders
2
3 A set of responders modules to dry up your Rails 3 app. If you are interested in the version
4 to be used with Rails 2.3 together with Inherited Resources, please check this branch instead:
5
6 http://github.com/plataformatec/responders/tree/v0.4
7
4059c2a @rafaelfranca Split responders in new sections
rafaelfranca authored
8 ## Responders Types
9
10 ### FlashResponder
11
12 Sets the flash based on the controller action and resource status.
13 For instance, if you do: `respond_with(@post)` on a POST request and the resource `@post`
14 does not contain errors, it will automatically set the flash message to
15 `"Post was successfully created"` as long as you configure your I18n file:
150ed62 @rafaelfranca Change README to markdown
rafaelfranca authored
16
17 ```yaml
18 flash:
19 actions:
20 create:
21 notice: "%{resource_name} was successfully created."
22 update:
23 notice: "%{resource_name} was successfully updated."
24 destroy:
25 notice: "%{resource_name} was successfully destroyed."
26 alert: "%{resource_name} could not be destroyed."
27 ```
28
4059c2a @rafaelfranca Split responders in new sections
rafaelfranca authored
29 In case the resource contains errors, you should use the failure key on I18n. This is
30 useful to dry up flash messages from your controllers. If you need a specific message
31 for a controller, let's say, for `PostsController`, you can also do:
150ed62 @rafaelfranca Change README to markdown
rafaelfranca authored
32
33 ```yaml
34 flash:
35 posts:
36 create:
37 notice: "Your post was created and will be published soon"
38 ```
39
4059c2a @rafaelfranca Split responders in new sections
rafaelfranca authored
40 This responder is activated in all non get requests. By default it will use the keys
41 `:notice` and `:alert`, but they can be changed in your application:
150ed62 @rafaelfranca Change README to markdown
rafaelfranca authored
42
43 ```ruby
44 config.responders.flash_keys = [ :success, :failure ]
45 ```
46
4059c2a @rafaelfranca Split responders in new sections
rafaelfranca authored
47 You can also have embedded HTML. Just create a `_html` scope.
150ed62 @rafaelfranca Change README to markdown
rafaelfranca authored
48
49 ```yaml
50 flash:
51 actions:
52 create:
53 alert_html: "<strong>OH NOES!</strong> You did it wrong!"
54 posts:
55 create:
56 notice_html: "<strong>Yay!</strong> You did it!"
57 ```
58
4059c2a @rafaelfranca Split responders in new sections
rafaelfranca authored
59 ### HttpCacheResponder
60
61 Automatically adds Last-Modified headers to API requests. This
62 allows clients to easily query the server if a resource changed and if the client tries
63 to retrieve a resource that has not been modified, it returns not_modified status.
64
65 ### CollectionResponder
150ed62 @rafaelfranca Change README to markdown
rafaelfranca authored
66
4059c2a @rafaelfranca Split responders in new sections
rafaelfranca authored
67 Makes your create and update action redirect to the collection on success.
150ed62 @rafaelfranca Change README to markdown
rafaelfranca authored
68
69 ## Configuring your own responder
70
71 The first step is instal responders gem and configure it in your application:
72
73 ```console
74 gem install responders
75 ```
76
77 In your Gemfile, add this line:
78
79 ```ruby
80 gem 'responders'
81 ```
82
83 Responders only provides a set of modules, to use them, you have to create your own
84 responder. This can be done inside the lib folder for example:
85
86 ```ruby
87 # lib/app_responder.rb
88 class AppResponder < ActionController::Responder
89 include Responders::FlashResponder
90 include Responders::HttpCacheResponder
91 end
92 ```
93
94 And then you need to configure your application to use it:
95
96 ```ruby
97 # app/controllers/application_controller.rb
98 require "app_responder"
99
100 class ApplicationController < ActionController::Base
101 self.responder = AppResponder
102 respond_to :html
103 end
104 ```
105
106 Or, for your convenience, just do:
107
108 ```console
109 rails generate responders:install
110 ```
111
112 ## Controller method
113
114 This gem also includes the controller method `responders`, which allows you to cherry-pick which
115 responders you want included in your controller.
116
117 ```ruby
118 class InvitationsController < ApplicationController
119 responders :flash, :http_cache
120 end
121 ```
122
123 ## Generator
124
125 This gem also includes a responders controller generator, so your scaffold can be customized
126 to use `respond_with` instead of default `respond_to` blocks. Installing this gem automatically
127 sets the generator.
128
b271f8b Added a few examples to the README
Rodrigo Flores authored
129 ## Examples
130
131 Want more examples ? Check out this blog posts:
132
133 * [One in Three: Inherited Resources, Has Scope and Responders](http://blog.plataformatec.com.br/2009/12/one-in-three-inherited-resources-has-scope-and-responders/)
134 * [Embracing REST with mind, body and soul](http://blog.plataformatec.com.br/2009/08/embracing-rest-with-mind-body-and-soul/)
135 * [Three reasons to love ActionController::Responder](http://weblog.rubyonrails.org/2009/8/31/three-reasons-love-responder/)
136 * [My five favorite things about Rails 3](http://www.engineyard.com/blog/2009/my-five-favorite-things-about-rails-3/)
137
150ed62 @rafaelfranca Change README to markdown
rafaelfranca authored
138 ## Bugs and Feedback
139
140 If you discover any bugs or want to drop a line, feel free to create an issue on GitHub.
141
142 http://github.com/plataformatec/responders/issues
143
144 MIT License. Copyright 2012 Plataforma Tecnologia. http://blog.plataformatec.com.br
Something went wrong with that request. Please try again.