You are viewing documentation for v1.0.x. Change

Configuration and Defaults

An overview of Wheels configuration and how is it used in your applications. Learn how to override a Wheels convention to make it your own.

We all love the "Convention over Configuration" motto of Wheels, but what about those two cases that pop into everyone's head? What if I want to develop in my own way? Or, What about an existing application that I need to port into Wheels? Gladly, that's what configuration and defaults are there for. Let's take a look at exactly how is this performed.

Where Configurations Happen

You will find configuration files in the config folder of your Wheels application. In general, most of your settings will go in config/settings.cfm.

You can also set values based on what environment you have set. For example, you can have different values for your settings depending on whether you're in design mode or production mode. See the chapter on Switching Environments for more details.

How to Set Configurations

To change a Wheels application default, you generally use the set() function. With it, you can perform all sorts of tweaks to the framework's default behaviors.

How to Access Configuration Values

Use the get() function to access the value of a Wheels application setting. Just pass it the name of the setting.

<cfif get("environment") is "production">
    <!--- Do something for production environment --->

Setting CFML application Configurations

In CFML's standard Application.cfc, you can normally set values for your application's properties in the this scope. Wheels still provides these options to you in the file at config/app.cfm.

Here is an example of what can go in config/app.cfm:

<cfset = "TheNextSiteToBeatTwitter">
<cfset this.sessionManagement = false>
this.customTagPaths = ListAppend(
this.customTagPaths, ExpandPath("../customtags")

Types of Configurations Available

There are several types of configurations that you can perform in Wheels to override all those default behaviors. In Wheels, you can find all these configuration options:

  • URL rewrite settings
  • Data source settings
  • Environment settings
  • Caching settings
  • Function settings
  • Miscellaneous settings

Let's take a closer look at each of these options.

URL Rewrite Settings

Sometimes it is useful for our applications to "force" URL rewriting. By default, Wheels will try to determinate what type of URL rewriting to perform and set it up for you. But you can force in or out this setting by using the example below:

<cfset set(urlRewriting="Off")>

The code above will tell Wheels to skip its automatic detection of the URL Rewriting capabilities and just set it as "Off".

You can also set it to "Partial" if you believe that your web server is capable of rewriting the URL as folders after index.cfm.

For more information, read the chapter about URL Rewriting.

Data Source Settings

Probably the most important configuration of them all. What is an application without a database to store all of its precious data?

The data source configuration is what tells Wheels which database to use for all of its models. (This can be overridden on a per model basis, but that will be covered later.) To set this up in Wheels, it's just as easy as the previous example:

<cfset set(dataSourceName="yourDataSourceName")>
<cfset set(dataSourceUserName="yourDataSourceUsername")>
<cfset set(dataSourcePassword="yourDataSourcePassword")>

Environment Settings

Not only are the environments useful for separating your production settings from your "under development" settings, but they are also opportunities for you to override settings that will only take effect in a specified environment.

For example, let's say that we want to enable debugging information in our "devlopment" environment temporarily:

<!--- /config/development/settings.cfm --->
<cfset set(showDebugInformation=false)>

Full Listing of Environment Settings

Name Type Default Description
showDebugInformation boolean Enabled in design and development When set to true, Wheels will show debugging information in the footers of your pages.
showErrorInformation boolean Enabled in design, development, maintenance, and testing When set to false, Wheels will run and display code stored at events/onerror.cfm instead of revealing CFML errors.
sendEmailOnError boolean Enabled in production environments that have a TLD like .com, .org, etc. When set to true, Wheels will send an email to administrators whenever Wheels throws an error.
errorEmailAddress string [empty string] Comma-delimited list of email address to send error notifications to. Only applies if sendEmailOnError is set to true.

For more information, refer to the chapter about Switching Environments.

Caching Settings

Wheels does a pretty good job at caching the framework and its output to speed up your application. But if personalization is key in your application, finer control over caching settings will become more important.

Let's say your application generates dynamic routes and you need it to check the routes on each request. This task will be as simple as this line of code:

<cfset set(cacheRoutes=false)>

Full Listing of Caching Settings

Name Type Default Description
cacheDatabaseSchema boolean Enabled in development, maintenance, testing, and production When set to false, you can add a field to the database, and Wheels will pick that up right away.
cacheFileChecking boolean Enabled in development, maintenance, testing, and production When set to true, Wheels will cache whether or not controller, helper, and layout files exist
cacheImages boolean Enabled in development, maintenance, testing, and production When set to true, Wheels will cache general image information used in imageTag() like width and height.
cacheModelInitialization boolean Enabled in development, maintenance, testing, and production When set to false, any changes you make to the init() function in the model file will be picked up immediately.
cacheControllerInitialization boolean Enabled in development, maintenace, testing, and production When set to false, any changes you make to the init() function in the controller file will be picked up immediately.
cacheRoutes boolean Enabled in development, maintenance, testing, and production When set to true, Wheels will cache routes across all pageviews.
cacheActions boolean Enabled in maintenance, testing, and production When set to true, Wheels will cache output generated by actions when specified (in a caches() call, for example).
cachePages boolean Enabled in maintenance, testing, and production When set to true, Wheels will cache output generated by a view page when specified (in a renderPage() call, for example).
cachePartials boolean Enabled in maintenance, testing, and production When set to true, Wheels will cache output generated by partials when specified (in a includePartial() call for example).
cacheQueries boolean Enabled in maintenance, testing, and production When set to true, Wheels will cache SQL queries when specified (in a findAll() call, for example).
maximumItemsToCache numeric 5000 Maximum number of items to store in Wheels's cache at one time. When the cache is full, items will be deleted automatically at a regular interval based on the other cache settings.
cacheCullPercentage numeric 10 If you set this value to 10, then at most, 10% of expired items will be deleted from the cache.
cacheCullInterval numeric 5 Number of minutes between each culling action. The reason the cache is not culled during each request is to keep performance as high as possible.
defaultCacheTime numeric 60 Number of minutes an item should be cached when it has not been specifically set through one of the functions that perform the caching in Wheels (i.e., caches(), findAll(), includePartial(), etc.)

For more information, refer to the chapter on Caching.

Function Settings

OK, here it's where the fun begins! Wheels includes a lot of functions to make your life as a CFML developer easier. A lot of those functions have sensible default argument values to minimize the amount of code that you need to write. And yes, you guessed it, Wheels lets you override those default argument values application-wide.

Let's look at a little of example:

<cfset set(functionName="findAll", perPage=20)>

That little line of code will make all calls to the findAll() method in Wheels return a maximun number of 20 record per page (if pagination is enabled for that findAll() call). How great is that? You don't need to set the perPage value for every single call to findAll() if you have a different requirement than the Wheels default of 10 records.

Miscellaneous Settings

How about situations that don't fit into those previous 5 categories? Well, they all fall right into this miscellaneous section.

Let's say you don't like the convention name for the soft delete feature of Wheels. Changing it is as easy as this:

<cfset set(softDeleteProperty="trashedAt")>

This will enable soft delete on all models that contains the trashedAt property instead of the Wheels default, deletedAt.

Full Listing of Miscellaneous Settings

Name Type Default Description
tableNamePrefix string [empty string] String to prefix all database tables with so you don't need to define your model objects including it. Useful in environments that have table naming conventions like starting all table names with tbl
obfuscateUrls boolean false Set to true to obfuscate primary keys in URLs.
reloadPassword string [empty string] Password to require when reloading the Wheels application from the URL. Leave empty to require no password.
softDeleteProperty string deletedAt Name of database column that Wheels will look for in order to enforce soft deletes.
timeStampOnCreateProperty string createdAt Name of database column that Wheels will look for in order to automatically store a "created at" time stamp when records are created.
timeStampOnUpdateProperty string updatedAt Name of the database column that Wheels will look for in order to automatically store an "updated at" time stamp when records are updated.
ipExceptions string [empty string] IP addresses that Wheels will ignore when the environment is set to maintenance. That way administrators can test the site while in maintenance mode, while the rest of users will see the message loaded in events/onmaintenance.cfm.
overwritePlugins boolean true When set to true, Wheels will overwrite plugin files based on their source zip files on application reload. Setting this to false makes plugin development easier because you don't need to keep rezipping your plugin files every time you make a change.

Wrapping It Up

There are literally hundreds of configurations options in Wheels for you to play around with. So go ahead and sink your teeth into Wheels configuration and defaults.

^ Top
Table of Contents


Read and submit questions, clarifications, and corrections about this chapter.

[Add Comment]

  1. Alexei's Gravatar Alexei says:

    How can I access variables from config/app.cfm?
    I want to set up default email like <cfset = "xx@yy.zz"> and be able to use in any of the /views files.
    But it doesn't work :-(

  2. Joey's Gravatar Joey says:

    In my settings.cfm I added <cfset set(myEmail="xx@yy.zz") />; then when I need it in my controller or view I simply call <cfset get("myEmail") />;

  3. Chris Peters's Gravatar Chris Peters says:

    Joey, I should probably make these docs a little clearer for your scenario in particular. I only recommend using set() when you want to set a _Wheels_ configuration.

    If you're setting a custom variable like myEmail, I recommend setting it like this:
    <cfset application.myEmail = "xx@yy.zz">

    This keeps it out of the Wheels application namespace, which will reduce the odds of collisions for you in the future.

    You then can access it in your controllers as application.myEmail elsewhere in your application.

    Where you set this application value depends on your preferences. I prefer to keep it in config/settings.cfm (and related environment files), but I know that others prefer events/onapplicationstart.cfm as well.

  4. Joey's Gravatar Joey says:

    Hey Chris,

    Thanks for the tip. I see your point, I think this was discussed in the group as well. Lucky I only have a couple of settings. If you could add the comments to the actual header of the settings.cfm would be great too. I was mislead by the examples of setting dataSourceName, etc...

  5. Daniel's Gravatar Daniel says:

    How do you access the application scope from view pages? I added some variables into app.cfm but I cannot access them in the views...

  6. Chris Peters's Gravatar Chris Peters says:


    I recommend setting your application scope variables in one of two places: events/onapplicationstart.cfm or config/settings.cfm. config/app.cfm is specifically for setting Application.cfc setting files like and this.customTagPaths.

    If you do want to set your values there anyway though, try putting them in the this scope. app.cfm gets run at the Application.cfc-level, so I believe that the this scope in that file becomes the application scope elsewhere.

    Lastly, I don't recommend accessing application-scoped values in the view. From the purest MVC point of view, you only want your controllers to be accessing and manipulating scopes like application and session. If you need to consistently be accessing values from the application scope, try setting up a filter to do it for all actions.

  7. Dorin's Gravatar Dorin says:

    If you use the 'reloadPassword' option in settings.cfm like
    <cfset set(reloadPassword="foo")>
    then, in order to reload the framework, you need to pass the following parameters in the URL:
    Also, when you use the 'reloadPassword' option, if you are on 'design' or 'developoment' environments, the links to reload CFWheels and change the environment will no longer be displayed in the debug bar.

  8. Gary Taylor's Gravatar Gary Taylor says:

    Just an FYI:
    The description for "errorEmailSubject" appears to be just copied from "errorEmailAddress"

  9. Andy Bellenie's Gravatar Andy Bellenie says:

    I think we should probably add a complete list of all config options, I have a hard time remembering them.

  10. Chris Peters's Gravatar Chris Peters says:


    This is meant to be a complete list. If you find any that are missing, be sure to add them to the wiki.

  11. Matt's Gravatar Matt says:

    If I wanted to set the location of the /wheels directory to somewhere other than the default, is there a setting to do so?

    My goal is to make a central, global location for the wheels directory. Each application I create would then reference that single wheels directory. I would like to cut down on the number of files the server needs to load for my applications and, subsequently cut the initial load time on the applications.

    Thanks for the help, and for a great framework!

  12. Rickey's Gravatar Rickey says:

    If i have two folders (app1, app2) each running cfwheels and the is the same in both of there app.cfm files, app2 always tries to run app1 code and vice versa when i do reload = true.  Is there a way to get them to not do this

  13. keshav's Gravatar keshav says:

    how can i change the default location of imageTag(). like my site is hosted at c:/sites and i want to acess images from d:/images by just passing image name to imagetag() . ie . i have an image called abc.jpg in d:/images and i want to acess it in my site hosted at c:/site by j#imageTag("abc.jpg")#.......

  14. Andor Admiraal's Gravatar Andor Admiraal says:

    Hi Keshav,

    By default, you cannot set an external path as the image directory. It will add the full path (starting with http://) to the root directory on the local server.

    In order to achieve what you want, you need to update the file

    Look for the following two lines:
    if(Left(arguments.source, 7) == "http://"; || Left(arguments.source, 8) == "https://";)
    loc.localFile = false;

    And replace it with this code:
    if(Left(arguments.source, 7) == "http://"; || Left(arguments.source, 8) == "https://";)
    loc.localFile = false;
    arguments.src = arguments.source;
    else if(Left(application.wheels.imagePath, 7) == "http://"; || Left(application.wheels.imagePath, 8) == "https://";)
    loc.localFile = false;
    arguments.src = application.wheels.imagePath & "/"; & arguments.source;

    Now you can set an external path as your default image directory for the imageTag() function without messing up anything else. Be careful when updating to a newer wheels version though, you will need to adjust the same code again!

Add Comment