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 disable debugging information in our development environment temporarily:

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

Full Listing of Environment Settings

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

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

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.