Finally, a framework for the rest of us!

CFWheels is an open source CFML (ColdFusion Markup Language) framework inspired by Ruby on Rails that provides fast application development, a great organization system for your code, and is just plain fun to use.

One of our biggest goals is for you to be able to get up and running with CFWheels quickly. We want for you to be able to learn it as rapidly as it is to write applications with it.

Get Started    

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:

  1. URL Variable
  2. URL Extension
  3. 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.

1. 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:

http://www.example.com/products?format=xml

The same would go for JSON:

http://www.example.com/products?format=json

2. URL Extension

Perhaps a cleaner way is to request the format as a "file" extension. Here are
the XML and JSON examples, respectively:

http://www.example.com/products.xml
http://www.example.com/products.json

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.

3. 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.

<cfhttp url="http://www.example.com/products">
    <cfhttpparam type="header" name="Accept" value="application/octet-stream">
</cfhttp>

Here is a list of values that you can grab from mimeTypes() with CFWheels out
of the box.

  1. html
  2. xml
  3. json
  4. csv
  5. pdf
  6. xls

You can use addFormat() to set more types to the appropriate MIME type for
reference. For example, we could set a Microsoft Word MIME type in
config/settings.cfm like so:

<cfset addFormat(extension="doc", mimeType="application/msword")>

Responding to Different Formats in the Controller

The fastest way to get going with creating your new API and formats is to call
provides() from within your controller's init() method.

Take a look at this example:

<cfcomponent extends="Controller">

	<cffunction name="init">
		<cfscript>
			provides("html,json,xml");
		</cfscript>
	</cffunction>

	<cffunction name="index">
		<cfscript>
			products = model("product").findAll(order="title");
      renderWith(products);
		</cfscript>
	</cffunction>

</cfcomponent>

By calling the provides() function in init(), you are instructing the
CFWheels controller to be ready to provide content in a number of formats.
Possible choices to add to the list are html (which runs by default), xml,
json, csv, pdf, and xls.

This is coupled with a call to renderwith() in the following actions.
In the example above, we are setting a query result of products and passing it
to renderwith(). By passing our data to this function, CFWheels gives us the
ability to respond to requests for different formats, and it even gives us the
option to just let CFWheels handle the generation of certain formats
automatically.

When CFWheels handles this response, it will set the appropriate MIME type in the
Content-Type HTTP header as well.

Providing the HTML Format

Responding to requests for the HTML version is the same as you're already used
to with Rendering Content. renderwith() will accept the same arguments
as renderPage(), and you create just a view template in the views folder
like normal.

Automatic Generation of XML and JSON Formats

If the requested format is xml or json, the renderwith() function will
automatically transform the data that you provide it. If you're fine with what
the function produces, then you're done!

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.

First of all, always return data as an array of structs. This is done by using the returnAs argument (on findAll() for example), like this:

authors = model("author").findAll(returnAs="structs");

The reason for doing it this way is that it will preserve the case for the struct / JSON keys.

Secondly, make use of CFWheels ability to return the JSON values in a specified type. This is done in the renderWith() function, like this:

renderWith(data=authors, firstName="string", booksForSale="integer");

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:

Type
Example

html

views/products/index.cfm

xml

views/products/index.xml.cfm

json

views/products/index.json.cfm

csv

views/products/index.csv.cfm

pdf

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:

<cfdocument format="pdf">
    <h1>Products</h1>
    <table>
        <thead>
            <tr>
                <th>Name</th>
                <th>Description</th>
                <th>Price</th>
            </tr>
        </thead>
        <tbody>
            #includePartial(products)#
        </tbody>
    </table>
</cfdocument>

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.