Configuration and Defaults

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

We all love the "Convention over Configuration" motto of CFWheels, 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 CFWheels? Gladly, that's what configuration and defaults are there for. Let's take a look at exactly how this is performed.

Where Configurations Happen

You will find configuration files in the app/config folder of your CFWheels application. In general, most of your settings will go in app/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 development mode or production mode. See the chapter on Switching Environments for more details.

How to Set Configurations

To change a CFWheels 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 CFWheels application setting. Just pass it the name of the setting.

CFScript
if (get("environment") == "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 thisscope. CFWheels still provides these options to you in the file at app/config/app.cfm.

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

config/app.cfm
this.name = "TheNextSiteToBeatTwitter";
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 CFWheels to override all those default behaviors. In CFWheels, you can find all these configuration options:

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

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.

The setting for the current environment can be found in app/config/environment.cfm and should look something like this:

app/config/environment.cfm
set(environment="development");

Full Listing of Environment Settings

URL Rewriting Settings

Sometimes it is useful for our applications to "force" URL rewriting. By default, CFWheels 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:

CFScript
set(urlRewriting="Off");

The code above will tell CFWheels 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 CFWheels 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 CFWheels, it's just as easy as the previous example:

CFScript
set(dataSourceName="yourDataSourceName");
set(dataSourceUserName="yourDataSourceUsername");
set(dataSourcePassword="yourDataSourcePassword");

Function Settings

OK, here it's where the fun begins! CFWheels 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, CFWheels lets you override those default argument values application-wide.

Let's look at a little of example:

CFScript
set(functionName="findAll", perPage=20);

That little line of code will make all calls to the findAll() method in CFWheels return a maximum 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 CFWheels default of 10 records.

Debugging and Error Settings

You'll generally want to configure how CFWheels handles errors and debugging information based on your environment. For example, you probably won't want to expose CFML errors in your production environment, whereas you would want to see those errors in your development environment.

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

CFScript
// /app/config/development/settings.cfm
set(showDebugInformation=false);

Full Listing of Debugging and Error Settings

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

Caching Settings

CFWheels 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:

CFScript
set(cacheRoutes=false);

Full Listing of Caching Settings

For more information, refer to the chapter on Caching.

ORM Settings

The CFWheels ORM provides many sensible conventions and defaults, but sometimes your data structure requires different column naming or behavior than what CFWheels expects out of the box. Use these settings to change those naming conventions or behaviors across your entire application.

For example, if we wanted to prefix all of the database table names in our application with blog_ but didn't want to include that at the beginning of model names, we would do this:

CFScript
set(tableNamePrefix="blog_");

Now your post model will map to the blog_posts table, comment model will map to the blog_comments table, etc.

Full Listing of ORM Settings

Plugin Settings

There are several settings that make plugin development more convenient. We recommend only changing these settings in development mode so there aren't any deployment issues in production, testing, and maintenancemodes. (At that point, your plugin should be properly packaged in a zip file.)

If you want to keep what's stored in a plugin's zip file from overwriting changes that you made in its expanded folder, set this in app/config/development/settings.cfm:

CFScript
set(overwritePlugins=false);

See the chapter on Installing and Using Plugins for more information.

Media Settings

Configure how CFWheels handles linking to assets through view helpers like imageTag(), styleSheetLinkTag(), and javaScriptIncludeTag().

See the chapter about Date, Media, and Text Helpers for more information.

Full Listing of Asset Settings

Routing Settings

CFWheels includes a powerful routing system. Parts of it are configurable with the following settings.

See the chapters about Using Routes and Obfuscating URLs for more information about how this all works together.

Full Listing of Miscellaneous Settings

View Helper Settings

CFWheels has a multitude of view helpers for building links, forms, form elements, and more. Use these settings to configure global defaults for their behavior.

CSRF Protection Settings

CFWheels includes built-in Cross-Site Request Forgery (CSRF) protection for form posts. Part of the CSRF protection involves storing an authenticity token in the session (default) or within an encrypted cookie. Most of the settings below are for when you've chosen to store the authenticity token within a cookie instead of the server's session store.

CORS Protection Settings

CFWheels includes built-in Cross-Origin Resource Sharing (CORS) which allows you to configure which cross-origin requests and methods are allowed. By default, this feature is turned off which will deny cross origin requests at the browser level.

In this first version, the user can enable this feature, which will allow requests from all origins and all methods.

Miscellaneous Settings

Migrator Configuration Settings

Last updated

Logo