Responding with Multiple Formats
CFWheels controllers provide some powerful mechanisms for responding to requests for content in XML, JSON, and other formats. You can build an API with ease using these functions.
If you've ever needed to create an XML or JSON API for your Wheels application, you may have needed to go down the path of creating a separate controller or separate actions for the new format. This introduces the need to duplicate model calls or even break them out into a super long list of before filters. With this, your controllers can get pretty hairy pretty fast.
Using a few CFWheels functions, you can easily respond to requests for HTML, XML, JSON, and PDF formats without adding unnecessary bloat to your controllers.
Requesting Different Formats
With CFWheels Provides functionality in place, you can request different formats using the following methods:
URL Variable
URL Extension
Request Header
Which formats you can request is determined by what you configure in the controller. See the section below on Responding to Different Formats in the Controller for more details.
URL Variable
CFWheels will accept a URL variable called format
. If you wanted to request the
XML version of an action, for example, your URL call would look something like
this:
The same would go for JSON:
URL Extension
Perhaps a cleaner way is to request the format as a "file" extension. Here are the XML and JSON examples, respectively:
This works similarly to the URL variable approach mentioned above in that
there will now be a key in the params
struct set to the format
requested.
With the XML example, there will be a variable at params.format
with a value
of xml
.
Request Header
If you are calling the CFWheels application as a web service, you can also request
a given format via the HTTP Accept
header.
If you are consuming the service with another CFWheels application, your
<cfhttp>
call would look something like this:
In this example, we are sending an Accept
header with the value for the xml
format.
html
xml
json
csv
pdf
xls
Responding to Different Formats in the Controller
Take a look at this example:
When CFWheels handles this response, it will set the appropriate MIME type in the
Content-Type
HTTP header as well.
Providing the HTML Format
Automatic Generation of XML and JSON Formats
Best Practices for Providing JSON
Unfortunately there have been a lot of JSON related issues in CFML over the years. To avoid as many of these problems as possible we thought we'd outline some best practices for you to follow.
The reason for doing it this way is that it will preserve the case for the struct / JSON keys.
With that in place you can be sure that firstName
will always be treated as a string (i.e. wrap in double quotes) and booksForSale
as an integer (i.e. no decimal places) when producing the JSON output. Without this, your CFML engine might guess what the data type is, and it wouldn't always be correct unfortunately.
Providing Your Own Custom Responses
If you need to provide content for another type than xml
or json
, or if you
need to customize what your CFWheels application generates, you have that option.
In your controller's corresponding folder in views
, all you need to do is
implement a view file like so:
html
views/products/index.cfm
xml
views/products/index.xml.cfm
json
views/products/index.json.cfm
csv
views/products/index.csv.cfm
views/products/index.pdf.cfm
xls
views/products/index.xls.cfm
If you need to implement your own XML- or JSON-based output, the presence of your new custom view file will override the automatic generation that CFWheels normally performs.
Example: PDF Generation
If you need to provide a PDF version of the product catalog, the view file at
views/products/index.pdf.cfm
may look something like this:
HTML
Last updated
Was this helpful?