Here we invoke three methods called html, js and xml that use mime type names configured in grails-app/conf/Config.groovy (See content negotiation for more information). The call to html accepts a model (a Map) which is passed on to the view. Grails searches for a view called grails-app/views/book/list.html.gsp and if that is not found fallback to grails-app/views/book/list.gsp.

Note that the order of the types is significant if the request format is "all" or if more than one content type has the same "q" rating in the accept header. In the former case, the first type handler in the block is executed ("html" in the short example above). The latter case is more confusing because it only holds if there is more than one content type with the highest "q" rating for which you have a type handler and you have more than one type handler matching that "q" rating. For example if the request has "text/html" and "application/xml" with a "q" rating of 1.0, then this code:

withFormat {
xml { … }
html { … }
}

will use the "xml" type handler for the request.

Another important factor to note is that the withFormat method deals with the response format and not the request format. As of Grails 2.0, there is a separate withFormat method made available on the request that you can use to handle the request format which is dictated by the CONTENT_TYPE header of the request:

request.withFormat {
xml { .. }
html { .. }
}

If you require that the model be lazily executed you can pass a Closure instead of a Map:

withFormat {
html { [bookList: Book.list()] }
…
}

This way the html Closure will only be executed if the html format is matched.

Grails ignores the HTTP Accept header unless you add a grails.mime.use.accept.header = true setting to your Config.groovy file. In other words, withFormat() will be completely unaffected by the Accept header without that setting.

Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.
Sponsored by SpringSource