ColdFusion on Wheels Blog

Creating a mega quick JSON API in CFWheels 2.x

Screencast: Routing in CFWheels 2.x – part 2

Covers constraints, wildcard segments and shallow resources.

Screencast: Routing in CFWheels 2.x

A quick  overview of routing in Wheels 2.x


Screencast: Basic CRUD interface in CFWheels 2.x

CFWheels 2.0.1 maintenance Release

Today sees a maintenance release for the 2.x series.

Download 2.0.1 today to fix the following:

Bug Fixes

  • Fixes reload links on application test suite page – #820 [Michael Diederich]
  • Set dbname in cfdbinfo calls when using custom database connection string – #822 [Per Djurner]
  • Fixes humanize() function – #663 [Chris Peters, Per Djurner, kmd1970]
  • Enables the rel attribute for stylesheetlinkTag() – #834 [Michael Diederich]
  • Returning a NULL value from a query with NULL support enabled no longer throws an error – #834 [Michael Diederich]
  • Accessing a route with incorrect verb now provides a more useful error message – #800 [Tom King]
  • Fixed bug with arrays in URLs – #836 [Michael Diederich, Per Djurner]
  • startFormTag now properly applies the method attribute – #837 [David Paul Belanger]
  • Incompatible plugin notice now ignores patch releases unless specified – #840 [Risto, Tom King]

CFWheels 1.4.6 maintenance Release

Today sees a maintenance release for the 1.4.x series. Please note that as 2.0 is now released, future updates to the 1.x branch will be limited to essential bug fixes only.

Download 1.4.6 today to fix the following:

Bug Fixes

  • Made humanize() keep spaces in input.
  • Added spatial datatypes for MySQL.
  • Scope variable to avoid object being returned as NULL.
  • Include “MariaDB” in database check connection string.
  • Fixes MySQL attempts to insert nulls for blank strings.

CFWheels 2.0 Released

Ok, it’s been a while, but *finally*, CFWheels 2.0 has gone gold!

  • Direct Download: Download zip
  • Commandbox quick install : install cfwheels (Just downloads and unzips)
  • Commandbox install wizard via CFWheels CLI (with url rewriting included):  wheels new
    (make sure your version of the CLI is up to date with install cfwheels-cli)

Make sure to check the “Breaking Changes” section, and please report any bugs.

Needless to say, this has been a massive undertaking with over 1000 commits, and over a year in the making. The core team wishes to thank all the many contributors, testers, and well, just users of the framework. We think we’re in a pretty strong place to move forward with loads more exciting things in the future.

For a comprehensive list of changes, check the Changelog, but for a quick summary:

Need help upgrading? Check the upgrade notes, and feel free to post questions to the Google Group, or hit us up on the #cfwheels room on the CFML Slack Channel

CFWheels 2.0.0-beta.1 Now Available

It’s been about a year in the making, and well over 1000 commits, but the beta for 2.0 has now arrived! We’re still catching up on the main documentation as there’s so much to cover in this release, so bear with us a bit! In the meantime, please do check it out:

  • Direct Download: Download zip
  • Commandbox quick install : install [email protected] (Just downloads and unzips)
  • Commandbox install wizard via CFWheels CLI (with url rewriting included):  wheels new
    (make sure your version of the CLI is up to date with install cfwheels-cli)

Make sure to check the “Breaking Changes” section below, and please report any bugs.

Need a little help upgrading?

There will be some more posts coming up covering some of the big topics like routing & migrations, but in the meantime:

  • Check out Adam’s upgrade advisor plugin (Commandbox: install upgradeadvisor)
  • Get in touch via the Mailing List, Slack channel etc.


Model Enhancements

  • Support for passing in select=false to property() to not include a calculated property by default in SELECT clauses – #122 [Adam Chapman, Per Djurner]
  • Support for setting calculated properties to a specific data type – [Per Djurner]
  • Support for returnIncludedAs and returnIncluded arguments to properties() for returning nested properties – [Adam Chapman]
  • Support for calling updateProperty() with dynamic argument, e.g. updateProperty(firstName="Per") – [Per Djurner]
  • Support for using boolean transaction argument, e.g. update(transaction=false)#654 [Adam Chapman]
  • Support for MariaDB – #563 [AlexeiCF, Adam Chapman]
  • Model instance isPersisted() and propertyIsBlank() methods – #559 [Chris Peters]
  • Database Migrations (dbmigrate) now available in the core – #664 [Adam Chapman, Tom King, Mike Grogan]
  • Databases can now be automatically migrated to the latest version on application start – #766 [Tom King]
  • New timeStampMode setting ("utc", "local" or "epoch") for the createdAt and updatedAtcolumns – [Andy Bellenie]
  • Allow nested transactions – #732 [Andy Bellenie]
  • The handle argument to finders now set the variable name for the query so it’s easier to find in the debug output – [Per Djurner]
  • Support added for HAVING when using aggregate functions in the where argument – #483 [Per Djurner]
  • Added support for the JSON data type in the MySQL adapter – #759 [Joel Stobart]
  • Corrected mapping for text types in the MySQL adapter – #759 [Joel Stobart]
  • Added global setting, lowerCaseTableNames, to always lower case table names in SQL statements – [Per Djurner]

View Enhancements

  • flashMessages() are now in default layout.cfm – #650 [Tom King]
  • Added ability to override value in textField(), passwordField() and hiddenField()#633 [Per Djurner, Chris Peters]
  • Support for the method argument in buttonTo() helper – #761 [Adam Chapman]

Controller Enhancements

  • Support for HTTP verbs, scopes, namespaces, and resources in routes (ColdRoute) [Don Humphreys, James Gibson, Tom King]
  • Support for passing in ram:// resources to sendFile()#566 [Tom King]
  • Extended sendMail() so that it can return the text and/or html content of the email – #122 [Adam Chapman]
  • renderWith() can now set http status codes in header with the status argument – #549 [Tom King]
  • Cross-Site Request Forgery (CSRF) protection – #613 [Chris Peters]
  • Parse JSON body and add to params struct – [Tom King, Per Djurner]

Bug Fixes

  • Fixes skipped model instantiation due to Linux file case sensitivity – #643 [Adam Chapman, Tom King]
  • Added spatial datatypes for MySQL – #660 [Normal Cesar]
  • Made humanize() keep spaces in input – #663 [Per Djurner, Chris Peters]
  • Avoid double redirect error when doing delayed redirects from a verification handler function – [Per Djurner]
  • Fixes attempts to insert nulls for blank strings – #654 [Andy Bellenie, Per Djurner]
  • Fix for using validatePresenceOf() with default on update – [Andy Bellenie]
  • Fixes so paginated finder calls with no records include column names – #722 [Per Djurner]
  • Fixes “invalid data” error when using unsigned integers in MySQL – #768 [Per Djurner]


  • Plugins now distributed via [Tom King]
  • Update to the plugin system to allow overriding of the same framework method multiple times – #681 [James Gibson, Tom King]
  • Added ability to turn off incompatible plugin warnings from showing – [Danny Beard]
  • Plugins now have any java lib/class files automatically mapped onApplicationStart 731 [Andy Bellenie, Tom King]
  • Plugins now read version number off their box.json files and are displayed in debug area #68 [Tom King]
  • Plugin meta data as set in box.json now available in application.wheels.pluginMeta scope #68 [Tom King]


  • Redirect away after a reload request – [Chris Peters]
  • Support checking IP in http_x_forwarded_for when doing maintenance mode exclusions – [Per Djurner]
  • Support checking user agent string when doing maintenance mode exclusions – [Per Djurner]
  • Added JUnit and JSON format test results – [Adam Chapman]
  • Added empty application test directories – [Chris Peters, Adam Chapman]
  • Added default urlrewrite.xml to support Tuckey URL rewriting with Commandbox #649 – [Tom King]
  • Added beforeAll(), afterAll(), packageSetup(), packageTeardown() methods to test framework #651 – [Adam Chapman]
  • Added errorEmailFromAddress and errorEmailToAddress config settings – #95 [Andy Bellenie, Tony Petruzzi, Per Djurner]
  • Support for passing in any “truthy” value to assert() in tests – [Per Djurner]
  • Added /app/ mapping pointing to the root of the application – [Per Djurner]
  • Added a processRequest() function that simplifies testing controllers – [Per Djurner]
  • Added new embedded documentation viewer/generator for JavaDoc – #734 [Tom King]
  • Removes all references to Railo – #656 (Adam Chapman)
  • Made uncountable and irregular words configurable – #739 [Per Djurner]
  • Removed design mode – [Per Djurner]
  • Removed cacheRoutes setting – [Per Djurner]
  • The cacheFileChecking and cacheImages settings are now turned off in development mode – [Per Djurner]
  • Added includeErrorInEmailSubject setting – [Per Djurner]
  • Environment switching via URL can now be turned off via allowEnvironmentSwitchViaUrl#766 [Tom King]

Breaking Changes

  • Minimum Lucee version is now
  • Minimum ACF version is now 10.0.23 / 11.0.12.
  • Support for Railo has been dropped.
  • Rewrite and config files for IIS and Apache have been removed and has to be added manually instead.
  • The events/functions.cfm file has been moved to global/functions.cfm.
  • The models/Model.cfc file should extend wheels.Model instead of Wheels (models/Wheels.cfc can be deleted).
  • The controllers/Controller.cfc file should extend wheels.Controller instead of Wheels(controllers/Wheels.cfc can be deleted).
  • The init function of controllers and models should now be named config instead.
  • The global setting modelRequireInit has been renamed to modelRequireConfig.
  • The global setting cacheControllerInitialization has been renamed to cacheControllerConfig.
  • The global setting cacheModelInitialization has been renamed to cacheModelConfig.
  • The global setting clearServerCache has been renamed to clearTemplateCache.
  • The updateProperties() method has been removed, use update() instead.
  • Form labels automatically generated based on foreign key properties will drop the “Id” from the end (e.g., the label for the “userId” property will be “User”, not “User Id”).
  • Routes need to be updated to use the new routing system by calling mapper().
  • JavaScript arguments like confirm and disable have been removed from the link and form helper functions (use the JS Confirm and JS Disable plugins to reinstate the old behaviour).
  • Timestamping (createdAt, updatedAt) is now in UTC by default (set the global timeStampModesetting to local to reinstate the old behaviour).
  • Blank strings in SQL are now converted to null checks (e.g. where="x=''" becomes where="x IS NULL").
  • Tags are now closed in HTML5 style (e.g. <img src="x"> instead of <img src="x" />).
  • The encode argument to mailTo now encodes tag content and attributes instead of outputting JavaScript.
  • Class output is now dasherized (e.g. field-with-errors instead of fieldWithErrors).
  • The renderPage function has been renamed to renderView.

Testing Plugins on CFWheels 2.x and Travis CI via commandbox

One of the nicest things about CFWheels 2.x is the tighter integration with command-line tools such as Commandbox. We can take advantage of the new testing suite JSON return type and the new CFWheels CLI in Commandbox 2.x to easily build a Travis CI test. It’s perhaps easiest to just show the .travis.yml file – this goes in the root of your gitHub plugin repository, and once you’ve turned on testing under, will run your test suite on every commit.

In sum, this:

  1. Installs Commandbox
  2. Installs the CFWheels CLI
  3. Installs the master branch of the CFWheels repository
  4. Installs your plugin from your repository (rather than the forgebox version which will be the version behind)
  5. Starts the local server
  6. Runs the test suite, pointing only at your plugin’s unit tests

Naturally, you could do more complex things with this, such as multiple CF Engines, and maybe even multiple CFWheels versions, but for a quick setup it’s a good starting point!

Unit Testing your new 2.x app in 2.x beta

Hands up if you’ve ever found a bug in your application..

Upgrades, feature enhancements and bug fixes are all part of the development lifecycle, but quite often with deadlines, it’s difficult to manually test the entire functionality of your application with every change you make. What if there were an automated way of checking if that change you’re making is going to break something?

Enter the CFWheels test framework!

In the past, writing an automated test suite against your application meant downloading, configuring and learning a completely separate framework. To help address this issue, CFWheels includes a small, simple, yet powerful testing framework. Whilst this has been part of the core in 1.x, it’s never been properly documented, and with 2.x, we’ve introduced lots of new features to help test your application.

Here is a simple example of unit testing a helper function that adds two numbers.

The same idea can be applied to just about any function in your application. Here are some of the things you might want to test:

  • Global helper functions return the values expected
  • That custom model validations return error messages when a value is not valid
  • Model callbacks are fired and produce the expected result
  • Controllers produce the expected output
  • Controllers redirect to the correct location

Once you have a comprehensive test suite, you can make code changes with a greater sense of confidence that you have not introduced bugs (regressions) into your application. This gives you the opportunity to implement automated test runners into a continuous integration platform like Jenkins or TravisCI.

Don’t just take our word for it.. well actually, DO take our word for it as CFWheels 2.0 has been developed exclusively against the inbuilt test framework.

For those of you who have been using the testing framework in your CFWheels 1.x applications, the 2.0 framework has a number of improvements around setup, teardown and a super handy processRequest function:

You get lots of handy information back, like the body contents, the status code of the request, and more.

Want to get going? Check the comprehensive tutorial at