Module: Merb::ResponderMixin
- Included in:
- Controller
- Defined in:
- lib/merb-core/controller/mixins/responder.rb
Overview
The ResponderMixin adds methods that help you manage what formats your controllers have available, determine what format(s) the client requested and is capable of handling, and perform content negotiation to pick the proper content format to deliver.
If you hear someone say “Use provides” they’re talking about the Responder. If you hear someone ask “What happened to respond_to?” it was replaced by provides and the other Responder methods.
A simple example
The best way to understand how all of these pieces fit together is with an example. Here’s a simple web-service ready resource that provides a list of all the widgets we know about. The widget list is available in 3 formats: :html (the default), plus :xml and :text.
class Widgets < Application
provides :html # This is the default, but you can
# be explicit if you like.
provides :xml, :text
def index
@widgets = Widget.fetch
render @widgets
end
end
Let’s look at some example requests for this list of widgets. We’ll assume they’re all GET requests, but that’s only to make the examples easier; this works for the full set of RESTful methods.
-
The simplest case, /widgets.html Since the request includes a specific format (.html) we know what format to return. Since :html is in our list of provided formats, that’s what we’ll return.
render
will look for an index.html.erb (or another template format like index.html.mab; see the documentation on Template engines) -
Almost as simple, /widgets.xml This is very similar. They want :xml, we have :xml, so that’s what they get. If
render
doesn’t find an index.xml.builder or similar template, it will callto_xml
on @widgets. This may or may not do something useful, but you can see how it works. -
A browser request for /widgets This time the URL doesn’t say what format is being requested, so we’ll look to the HTTP Accept: header. If it’s ‘/’ (anything), we’ll use the first format on our list, :html by default.
If it parses to a list of accepted formats, we’ll look through them, in order, until we find one we have available. If we find one, we’ll use that. Otherwise, we can’t fulfill the request: they asked for a format we don’t have. So we raise 406: Not Acceptable.
A more complex example
Sometimes you don’t have the same code to handle each available format. Sometimes you need to load different data to serve /widgets.xml versus /widgets.txt. In that case, you can use content_type
to determine what format will be delivered.
class Widgets < Application
def action1
if content_type == :text
Widget.load_text_formatted(params[:id])
else
render
end
end
def action2
case content_type
when :html
handle_html()
when :xml
handle_xml()
when :text
handle_text()
else
render
end
end
end
You can do any standard Ruby flow control using content_type
. If you don’t call it yourself, it will be called (triggering content negotiation) by render
.
Once content_type
has been called, the output format is frozen, and none of the provides methods can be used.
Defined Under Namespace
Modules: ClassMethods Classes: ContentTypeAlreadySet
Constant Summary collapse
- TYPES =
{}
Class Method Summary collapse
-
.included(base) ⇒ Object
Parameters base<Module>:: The module that ResponderMixin was mixed into.
Instance Method Summary collapse
-
#_perform_content_negotiation ⇒ Object
Do the content negotiation: 1.
-
#_provided_formats ⇒ Object
Returns Array:: The current list of formats provided for this instance of the controller.
-
#_set_provided_formats(*formats) ⇒ Object
(also: #_provided_formats=)
Sets the provided formats for this action.
-
#content_type(fmt = nil) ⇒ Object
Returns the output format for this request, based on the provided formats,
params[:format]
and the client’s HTTP Accept header. -
#content_type=(type) ⇒ Object
Sets the content type of the current response to a value based on a passed in key.
-
#does_not_provide(*formats) ⇒ Object
Removes formats from the list of provided formats for this particular request.
-
#only_provides(*formats) ⇒ Object
Sets list of provided formats for this particular request.
-
#provides(*formats) ⇒ Object
Adds formats to the list of provided formats for this particular request.
Class Method Details
.included(base) ⇒ Object
Parameters
- base<Module>
-
The module that ResponderMixin was mixed into
105 106 107 108 109 110 111 112 |
# File 'lib/merb-core/controller/mixins/responder.rb', line 105 def self.included(base) # :nodoc: base.extend(ClassMethods) base.class_eval do class_inheritable_accessor :class_provided_formats self.class_provided_formats = [] end base.reset_provides end |
Instance Method Details
#_perform_content_negotiation ⇒ Object
Do the content negotiation:
-
if params is there, and provided, use it
-
Parse the Accept header
-
If it’s /, use the first provided format
-
Look for one that is provided, in order of request
-
Raise 406 if none found
287 288 289 290 291 292 293 294 295 296 297 298 |
# File 'lib/merb-core/controller/mixins/responder.rb', line 287 def _perform_content_negotiation # :nodoc: raise Merb::ControllerExceptions::NotAcceptable if _provided_formats.empty? if (fmt = params[:format]) && !fmt.empty? accepts = [fmt.to_sym] else accepts = Responder.parse(request.accept).map {|t| t.to_sym}.compact end specifics = accepts & _provided_formats return specifics.first unless specifics.length == 0 return _provided_formats.first if accepts.include? :all raise Merb::ControllerExceptions::NotAcceptable end |
#_provided_formats ⇒ Object
Returns
- Array
-
The current list of formats provided for this instance of the controller. It starts with what has been set in the controller (or :html by default) but can be modifed on a per-action basis.
193 194 195 |
# File 'lib/merb-core/controller/mixins/responder.rb', line 193 def _provided_formats @_provided_formats ||= class_provided_formats.dup end |
#_set_provided_formats(*formats) ⇒ Object Also known as: _provided_formats=
Sets the provided formats for this action. Usually, you would use a combination of provides, only_provides and does_not_provide to manage this, but you can set it directly.
Parameters
- *formats<Symbol>
-
A list of formats to be passed to provides.
Raises
- Merb::ResponderMixin::ContentTypeAlreadySet
-
Content negotiation already occured, and the content_type is set.
Returns
- Array
-
List of formats passed in.
210 211 212 213 214 215 216 |
# File 'lib/merb-core/controller/mixins/responder.rb', line 210 def _set_provided_formats(*formats) if @_content_type raise ContentTypeAlreadySet, "Cannot modify provided_formats because content_type has already been set" end @_provided_formats = [] provides(*formats) end |
#content_type(fmt = nil) ⇒ Object
Returns the output format for this request, based on the provided formats, params[:format]
and the client’s HTTP Accept header.
The first time this is called, it triggers content negotiation and caches the value. Once you call content_type
you can not set or change the list of provided formats.
Called automatically by render
, so you should only call it if you need the value, not to trigger content negotiation.
Parameters
- fmt<String>
-
An optional format to use instead of performing content negotiation. This can be used to pass in the values of opts from the render function to short-circuit content-negotiation when it’s not necessary. This optional parameter should not be considered part of the public API.
Returns
- Symbol
-
The content-type that will be used for this controller.
324 325 326 327 |
# File 'lib/merb-core/controller/mixins/responder.rb', line 324 def content_type(fmt = nil) self.content_type = (fmt || _perform_content_negotiation) unless @_content_type @_content_type end |
#content_type=(type) ⇒ Object
Sets the content type of the current response to a value based on a passed in key. The Content-Type header will be set to the first registered header for the mime-type.
Parameters
- type<Symbol>
-
The content type.
Raises
- ArgumentError
-
type is not in the list of registered mime-types.
Returns
- Symbol
-
The content-type that was passed in.
344 345 346 347 348 349 350 |
# File 'lib/merb-core/controller/mixins/responder.rb', line 344 def content_type=(type) unless Merb.available_mime_types.has_key?(type) raise Merb::ControllerExceptions::NotAcceptable.new("Unknown content_type for response: #{type}") end headers['Content-Type'] = Merb.available_mime_types[type][:request_headers].first @_content_type = type end |
#does_not_provide(*formats) ⇒ Object
Removes formats from the list of provided formats for this particular request. Usually used to remove formats from a single action. See also the controller-level does_not_provide that affects all actions in a controller.
Parameters
- *formats<Symbol>
-
Registered mime-type
Returns
- Array
-
List of formats that remain after removing the ones not to provide.
276 277 278 279 |
# File 'lib/merb-core/controller/mixins/responder.rb', line 276 def does_not_provide(*formats) formats.flatten! self._provided_formats -= formats end |
#only_provides(*formats) ⇒ Object
Sets list of provided formats for this particular request. Usually used to limit formats to a single action. See also the controller-level only_provides that affects all actions in a controller.
Parameters
- *formats<Symbol>
-
A list of formats to use as the per-action list of provided formats.
Returns
- Array
-
List of formats passed in.
258 259 260 |
# File 'lib/merb-core/controller/mixins/responder.rb', line 258 def only_provides(*formats) _set_provided_formats(*formats) end |
#provides(*formats) ⇒ Object
Adds formats to the list of provided formats for this particular request. Usually used to add formats to a single action. See also the controller-level provides that affects all actions in a controller.
Parameters
- *formats<Symbol>
-
A list of formats to add to the per-action list of provided formats.
Raises
- Merb::ResponderMixin::ContentTypeAlreadySet
-
Content negotiation already occured, and the content_type is set.
Returns
- Array
-
List of formats passed in.
236 237 238 239 240 241 242 243 |
# File 'lib/merb-core/controller/mixins/responder.rb', line 236 def provides(*formats) if @_content_type raise ContentTypeAlreadySet, "Cannot modify provided_formats because content_type has already been set" end formats.each do |fmt| _provided_formats << fmt unless _provided_formats.include?(fmt) end end |