Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Provides an easy way to specify custom formats and flexible per request format selection

branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

README.textile

merb-custom-formats

Proivdes simple setup for custom formats in merb. You can use Merb::CustomFormats as a descriptive
way to configure new mime types in merb. The plugin also provides a way for you to execute arbitrary logic
easily to set your format from any information available in the request.

Declaring A Mime Type

To declare a new mime type simply add it and declare which mime_types are acceptable for the format


Merb::CustomFormats.add(:iphone) do
  mime_types "application/xhtml+xml"
end

This will setup the :iphone format for use in Merb via
provides :iphone

The only required step is to declare the mime_types but you can also specify the
default response headers, transform (serialization) method, quality and a custom format selector.
By default the transform_method is :"to_#{format}"

Expanded Example

Here’s an example showing all things in play


Merb::CustomFormats.add(:iphone) do
  mime_types        "application/xhtml+xml", "text/xml"
  transform_method  :to_iphone_data
  headers           :some => "default header"
  quality           0.45
  selector do |request, route_params|
    request.user_agent && request.user_agent =~ /iphone/i
  end
end
You can see here that there are multiple mime_types being set, custom transform method, etc.

Selectors

The selector is a block that is run in the router as arbitrary logic to determine if the format matches
By returning true, you’re asserting a match, and params[:format] and therefore content_type will be (in this case)
:iphone If on the other hand you return false, the next custom format selector will be tried.
You don’t have to provide a selector, and if you don’t, a normal mime type will be added to merb.

To use in the router, just add a custom_format block around the routes you want to apply it to


Merb::Router.prepare do
  custom_formats do
    resources :iphone_resources
    match("/foo").to(:controller => "bar")
  end
  resources :non_iphone_resources
end

This will check the format on the :iphone_resources route, and also the “/foo” route. I will not try to match the
custom formats on the :non_iphone_resources routes.

Using this in your controller and views

All this is well and good. But what good does it actually do in your application?

The above example lets you do this:


class MyController < Application
  provides :iphone
  
end

All action and class level provides are respected with this method.

Something went wrong with that request. Please try again.