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 --->
</cfif>

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 this.name = "TheNextSiteToBeatTwitter">
<cfset this.sessionManagement = false>
<cfset
    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.

« Previous Chapter
Conventions

^ Top
Table of Contents

Next Chapter »
Directory Structure

Comments

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

[Add Comment]

Alexei says:

January 2, 2010 at 3:18 am

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

April 14, 2010 at 12:05 am

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") />
Chris Peters says:

April 14, 2010 at 5:59 am

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.
Joey says:

April 28, 2010 at 2:39 am

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...
Daniel says:

May 4, 2010 at 4:48 pm

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...
Chris Peters says:

May 4, 2010 at 4:57 pm

Daniel,

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 this.name 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.
http://cfwheels.org/docs/chapter/filters-and-verification
Dorin says:

October 7, 2010 at 2:19 pm

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:
?reload=true&password=foo
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.
Gary Taylor says:

November 10, 2010 at 7:55 am

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

February 5, 2011 at 1:40 pm

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

February 5, 2011 at 1:42 pm

Andy,

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

April 28, 2011 at 8:19 am

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!
Rickey says:

August 30, 2011 at 6:57 pm

If i have two folders (app1, app2) each running cfwheels and the this.name 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
keshav says:

July 30, 2012 at 6:27 am

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")#.......
Andor Admiraal says:

August 28, 2012 at 6:33 am

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
wheels/view/assets.cfm

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!