Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 206 lines (146 sloc) 6.413 kB
150ed62 @rafaelfranca Change README to markdown
rafaelfranca authored
1 # Responders
2
5156a80 @olivierlacan Spruce up badges with SVG versions
olivierlacan authored
3 [![Gem Version](https://fury-badge.herokuapp.com/rb/responders.svg)](http://badge.fury.io/rb/responders)
4 [![Build Status](https://api.travis-ci.org/plataformatec/responders.svg?branch=master)](http://travis-ci.org/plataformatec/responders)
5 [![Code Climate](https://codeclimate.com/github/plataformatec/responders.svg)](https://codeclimate.com/github/plataformatec/responders)
ebc053b @carlosantoniodasilva Add gem links to the README [ci skip]
carlosantoniodasilva authored
6
4e70f8e @josevalim Update to Rails 4.2
josevalim authored
7 A set of responders modules to dry up your Rails 4.2+ app.
8
9 ## Installation
10
11 Add the responders gem to your Gemfile:
12
13 gem "responders"
14
15 Update your bundle and run the install generator:
16
17 $ bundle install
18 $ rails g responders:install
150ed62 @rafaelfranca Change README to markdown
rafaelfranca authored
19
00e2380 @jedschneider add note for people upgrading from rails 4.1
jedschneider authored
20 If you are including this gem to support backwards compatibilty for responders in previous releases of Rails, you only need to include the gem and bundle.
21
22 $ bundle install
23
4059c2a @rafaelfranca Split responders in new sections
rafaelfranca authored
24 ## Responders Types
25
26 ### FlashResponder
27
28 Sets the flash based on the controller action and resource status.
29 For instance, if you do: `respond_with(@post)` on a POST request and the resource `@post`
30 does not contain errors, it will automatically set the flash message to
31 `"Post was successfully created"` as long as you configure your I18n file:
150ed62 @rafaelfranca Change README to markdown
rafaelfranca authored
32
33 ```yaml
34 flash:
35 actions:
36 create:
37 notice: "%{resource_name} was successfully created."
38 update:
39 notice: "%{resource_name} was successfully updated."
40 destroy:
41 notice: "%{resource_name} was successfully destroyed."
42 alert: "%{resource_name} could not be destroyed."
43 ```
44
4059c2a @rafaelfranca Split responders in new sections
rafaelfranca authored
45 In case the resource contains errors, you should use the failure key on I18n. This is
fc11d37 @nashby add alert message to update and create actions
nashby authored
46 useful to dry up flash messages from your controllers. Note: by default alerts for `update`
47 and `destroy` actions are commented in generated I18n file. If you need a specific message
4059c2a @rafaelfranca Split responders in new sections
rafaelfranca authored
48 for a controller, let's say, for `PostsController`, you can also do:
150ed62 @rafaelfranca Change README to markdown
rafaelfranca authored
49
50 ```yaml
51 flash:
52 posts:
53 create:
54 notice: "Your post was created and will be published soon"
55 ```
56
4059c2a @rafaelfranca Split responders in new sections
rafaelfranca authored
57 This responder is activated in all non get requests. By default it will use the keys
58 `:notice` and `:alert`, but they can be changed in your application:
150ed62 @rafaelfranca Change README to markdown
rafaelfranca authored
59
60 ```ruby
61 config.responders.flash_keys = [ :success, :failure ]
62 ```
63
4059c2a @rafaelfranca Split responders in new sections
rafaelfranca authored
64 You can also have embedded HTML. Just create a `_html` scope.
150ed62 @rafaelfranca Change README to markdown
rafaelfranca authored
65
66 ```yaml
67 flash:
68 actions:
69 create:
70 alert_html: "<strong>OH NOES!</strong> You did it wrong!"
71 posts:
72 create:
73 notice_html: "<strong>Yay!</strong> You did it!"
74 ```
75
a98b3f9 @marcandre Mention namespace_lookup option in README
marcandre authored
76 See also the `namespace_lookup` option to search the full hierarchy of possible keys.
77
7fbac14 @carlosantoniodasilva Clarify that including the location responder actually issues a depre…
carlosantoniodasilva authored
78 ### HttpCacheResponder
79
80 Automatically adds Last-Modified headers to API requests. This
81 allows clients to easily query the server if a resource changed and if the client tries
82 to retrieve a resource that has not been modified, it returns not_modified status.
83
84 ### CollectionResponder
85
86 Makes your create and update action redirect to the collection on success.
87
657d05b @igas Update naming in readme [ci skip]
igas authored
88 ### LocationResponder
5c72d59 @fnando Add :location responder, which allows to use callable objects.
fnando authored
89
90 This responder allows you to use callable objects as the redirect location.
91 Useful when you want to use the `respond_with` method with
92 a custom route that requires persisted objects, but the validation may fail.
93
7fbac14 @carlosantoniodasilva Clarify that including the location responder actually issues a depre…
carlosantoniodasilva authored
94 Note: this responder is included by default, and doesn't need to be included
95 on the top of your controller (including it will issue a deprecation warning).
06d12e4 @Dinuz README update the :location responders
Dinuz authored
96
5c72d59 @fnando Add :location responder, which allows to use callable objects.
fnando authored
97 ```ruby
98 class ThingsController < ApplicationController
99 respond_to :html
100
101 def create
7fdfa95 @untidy-hair Singularize a model name in README
untidy-hair authored
102 @thing = Thing.create(params[:thing])
5c72d59 @fnando Add :location responder, which allows to use callable objects.
fnando authored
103 respond_with @thing, location: -> { thing_path(@thing) }
104 end
105 end
106 ```
107
d77604a @maxcal #127 add namespaces info to readme
maxcal authored
108 **Dealing with namespaced routes**
109
110 In order for the LocationResponder to find the correct route helper for namespaced routes you need to pass the namespaces to `respond_with`:
111
112 ```ruby
113 class Api::V1::ThingsController < ApplicationController
114 respond_to :json
115
116 # POST /api/v1/things
117 def create
118 @thing = Thing.create(thing_params)
119 respond_with :api, :v1, @thing
120 end
121 end
122 ```
123
150ed62 @rafaelfranca Change README to markdown
rafaelfranca authored
124 ## Configuring your own responder
125
4e70f8e @josevalim Update to Rails 4.2
josevalim authored
126 Responders only provides a set of modules and to use them you have to create your own
127 responder. After you run the install command, the following responder will be
128 generated in your application:
150ed62 @rafaelfranca Change README to markdown
rafaelfranca authored
129
130 ```ruby
da8db79 @rafaelfranca Define the same file that is required in the README
rafaelfranca authored
131 # lib/application_responder.rb
2df3891 @pauloschiavon Update README.md
pauloschiavon authored
132 class ApplicationResponder < ActionController::Responder
150ed62 @rafaelfranca Change README to markdown
rafaelfranca authored
133 include Responders::FlashResponder
134 include Responders::HttpCacheResponder
135 end
136 ```
137
4e70f8e @josevalim Update to Rails 4.2
josevalim authored
138 Your application also needs to be configured to use it:
150ed62 @rafaelfranca Change README to markdown
rafaelfranca authored
139
140 ```ruby
141 # app/controllers/application_controller.rb
b1b4e5d @mibamur fix small application_ instead app_
mibamur authored
142 require "application_responder"
150ed62 @rafaelfranca Change README to markdown
rafaelfranca authored
143
144 class ApplicationController < ActionController::Base
2df3891 @pauloschiavon Update README.md
pauloschiavon authored
145 self.responder = ApplicationResponder
150ed62 @rafaelfranca Change README to markdown
rafaelfranca authored
146 respond_to :html
147 end
148 ```
149
150 ## Controller method
151
152 This gem also includes the controller method `responders`, which allows you to cherry-pick which
153 responders you want included in your controller.
154
155 ```ruby
156 class InvitationsController < ApplicationController
157 responders :flash, :http_cache
158 end
159 ```
160
1eaf85d @moonmaster9000 Update readme with interpolation options example
moonmaster9000 authored
161 ## Interpolation Options
162
163 You can pass in extra interpolation options for the translation by adding an `interpolation_options` method to your controller:
164
165 ```ruby
166 class InvitationsController < ApplicationController
167 responders :flash, :http_cache
9e664dd @rafaelfranca :scissors:
rafaelfranca authored
168
1eaf85d @moonmaster9000 Update readme with interpolation options example
moonmaster9000 authored
169 def create
170 @invitation = Invitation.create(params[:invitation])
171 respond_with @invitation
9e664dd @rafaelfranca :scissors:
rafaelfranca authored
172 end
173
1eaf85d @moonmaster9000 Update readme with interpolation options example
moonmaster9000 authored
174 private
9e664dd @rafaelfranca :scissors:
rafaelfranca authored
175
1eaf85d @moonmaster9000 Update readme with interpolation options example
moonmaster9000 authored
176 def interpolation_options
177 { resource_name: @invitation.email }
178 end
179 end
180 ```
181
182 Now you would see the message "bob@bob.com was successfully created" instead of the default "Invitation was successfully created."
183
150ed62 @rafaelfranca Change README to markdown
rafaelfranca authored
184 ## Generator
185
186 This gem also includes a responders controller generator, so your scaffold can be customized
4e70f8e @josevalim Update to Rails 4.2
josevalim authored
187 to use `respond_with` instead of default `respond_to` blocks. From 2.1, you need to explicitly opt-in to use this generator by adding the following to your `config/application.rb`:
150ed62 @rafaelfranca Change README to markdown
rafaelfranca authored
188
4e70f8e @josevalim Update to Rails 4.2
josevalim authored
189 config.app_generators.scaffold_controller :responders_controller
1e59364 @mikhail-alhimik To use default rails scaffold_controller add ... done
mikhail-alhimik authored
190
b271f8b Added a few examples to the README
Rodrigo Flores authored
191 ## Examples
192
193 Want more examples ? Check out this blog posts:
194
195 * [Embracing REST with mind, body and soul](http://blog.plataformatec.com.br/2009/08/embracing-rest-with-mind-body-and-soul/)
196 * [Three reasons to love ActionController::Responder](http://weblog.rubyonrails.org/2009/8/31/three-reasons-love-responder/)
197 * [My five favorite things about Rails 3](http://www.engineyard.com/blog/2009/my-five-favorite-things-about-rails-3/)
198
150ed62 @rafaelfranca Change README to markdown
rafaelfranca authored
199 ## Bugs and Feedback
200
201 If you discover any bugs or want to drop a line, feel free to create an issue on GitHub.
202
203 http://github.com/plataformatec/responders/issues
204
79e4960 @georgeguimaraes Update company name [ciskip]
georgeguimaraes authored
205 MIT License. Copyright 2009-2015 Plataformatec. http://plataformatec.com.br
Something went wrong with that request. Please try again.