{"__v":9,"_id":"550977ac4c7c3f2300aabefb","category":{"__v":5,"_id":"550974cc368a56170041475a","project":"55070e814bb83b2500ec9404","version":"550974cb368a561700414757","pages":["550977a44c7c3f2300aabef9","550977ac4c7c3f2300aabefb","550977c1aa9bd525001a064b","550977e24c7c3f2300aabefd","550977e8dd77250d007369ee"],"reference":false,"createdAt":"2015-03-18T11:08:15.581Z","from_sync":false,"order":2,"slug":"working-with-cfwheels","title":"Working with CFWheels"},"project":"55070e814bb83b2500ec9404","user":"55070d24d30b3f190011b941","version":{"__v":1,"_id":"550974cb368a561700414757","forked_from":"55070e814bb83b2500ec9407","project":"55070e814bb83b2500ec9404","createdAt":"2015-03-18T12:51:23.709Z","releaseDate":"2015-03-18T12:51:23.709Z","categories":["550974cc368a561700414758","550974cc368a561700414759","550974cc368a56170041475a","550974cc368a56170041475b","550974cc368a56170041475c","550974cc368a56170041475d","550974cc368a56170041475e"],"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.4.0","version":"1.4"},"updates":[],"createdAt":"2015-03-18T13:03:40.599Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"order":1,"body":"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 is this performed.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Where Configurations Happen\"\n}\n[/block]\nYou will find configuration files in the `config` folder of your CFWheels application. In general, most of your settings will go in `config/settings.cfm`.\n\nYou 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](doc:switching-environments) for more details.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"How to Set Configurations\"\n}\n[/block]\nTo change a CFWheels application default, you generally use the [set()](doc:set) function. With it, you can perform all sorts of tweaks to the framework's default behaviors.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"How to Access Configuration Values\"\n}\n[/block]\nUse the [get()](doc:get) function to access the value of a CFWheels application setting. Just pass it the name of the setting.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<cfif get(\\\"environment\\\") is \\\"production\\\">\\n    <!--- Do something for production environment --->\\n</cfif>\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Setting CFML application Configurations\"\n}\n[/block]\nIn CFML's standard `Application.cfc`, you can normally set values for your application's properties in the `this` scope. CFWheels still provides these options to you in the file at `config/app.cfm`.\n\nHere is an example of what can go in `config/app.cfm`:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<cfset this.name = \\\"TheNextSiteToBeatTwitter\\\">\\n<cfset this.sessionManagement = false>\\n<cfset this.customTagPaths = ListAppend(\\n    this.customTagPaths,\\n    ExpandPath(\\\"../customtags\\\")\\n)>\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Types of Configurations Available\"\n}\n[/block]\nThere 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:\n\n* Environment settings\n* URL rewriting settings\n* Data source settings\n* Function settings\n* Debugging and error settings\n* Caching settings\n* Media settings\n* Routing settings\n* View helper settings\n\nLet's take a closer look at each of these options.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Environment Settings\"\n}\n[/block]\nNot 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.\n\nThe setting for the current environment can be found in `config/environment.cfm` and should look something like this:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<cfset set(environment=\\\"development\\\")>\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n**Full Listing of Environment Settings** \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Default\",\n    \"h-3\": \"Description\",\n    \"0-0\": \"environment\",\n    \"1-0\": \"reloadPassword\",\n    \"2-0\": \"ipExceptions\",\n    \"0-1\": \"string\",\n    \"1-1\": \"string\",\n    \"2-1\": \"string\",\n    \"0-2\": \"development\",\n    \"1-2\": \"[empty string]\",\n    \"2-2\": \"[empty string]\",\n    \"0-3\": \"Environment to load. Set this value in config/environment.cfm. Valid values are design, development, testing, maintenance, and production.\",\n    \"1-3\": \"Password to require when reloading the CFWheels application from the URL. Leave empty to require no password.\",\n    \"2-3\": \"IP addresses that CFWheels 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.\"\n  },\n  \"cols\": 4,\n  \"rows\": 3\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"URL Rewriting Settings\"\n}\n[/block]\nSometimes 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:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<cfset set(urlRewriting=\\\"Off\\\")>\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nThe code above will tell CFWheels to skip its automatic detection of the URL Rewriting capabilities and just set it as `\"Off\"`.\n\nYou can also set it to \"Partial\" if you believe that your web server is capable of rewriting the URL as folders after `index.cfm`.\n\nFor more information, read the chapter about [URL Rewriting](doc:url-rewriting).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Data Source Settings\"\n}\n[/block]\nProbably the most important configuration of them all. What is an application without a database to store all of its precious data?\n\nThe 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:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<cfset set(dataSourceName=\\\"yourDataSourceName\\\")>\\n<cfset set(dataSourceUserName=\\\"yourDataSourceUsername\\\")>\\n<cfset set(dataSourcePassword=\\\"yourDataSourcePassword\\\")>\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Function Settings\"\n}\n[/block]\nOK, 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.\n\nLet's look at a little of example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<cfset set(functionName=\\\"findAll\\\", perPage=20)>\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nThat little line of code will make all calls to the [findAll()](doc:findall) method in CFWheels return a maximun number of 20 record per page (if pagination is enabled for that [findAll()](doc:findall) call). How great is that? You don't need to set the `perPage` value for every single call to [findAll()](doc:findall) if you have a different requirement than the CFWheels default of 10 records.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Debugging and Error Settings\"\n}\n[/block]\nYou'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 design and development environments.\n\nFor example, let's say that we want to enable debugging information in our \"development\" environment temporarily:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<!--- /config/development/settings.cfm --->\\n<cfset set(showDebugInformation=false)>\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n**Full Listing of Debugging and Error Settings** \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Default\",\n    \"h-3\": \"Description\",\n    \"0-0\": \"errorEmailServer\",\n    \"1-0\": \"errorEmailAddress\",\n    \"2-0\": \"errorEmailSubject\",\n    \"3-0\": \"excludeFromErrorEmail\",\n    \"4-0\": \"sendEmailOnError\",\n    \"5-0\": \"showDebugInformation\",\n    \"6-0\": \"showErrorInformation\",\n    \"0-1\": \"string\",\n    \"1-1\": \"string\",\n    \"2-1\": \"string\",\n    \"3-1\": \"string\",\n    \"4-1\": \"boolean\",\n    \"5-1\": \"boolean\",\n    \"6-1\": \"boolean\",\n    \"0-2\": \"[empty string]\",\n    \"1-2\": \"[empty string]\",\n    \"3-2\": \"[empty string]\",\n    \"2-2\": \"Error\",\n    \"4-2\": \"Enabled in production environments that have a TLD like .com, .org, etc.\",\n    \"5-2\": \"Enabled in design and development\",\n    \"6-2\": \"Enabled in design, development, maintenance, and testing\",\n    \"0-3\": \"Server to use to send out error emails. When left blank, this defaults to settings in the ColdFusion Administrator (if set).\",\n    \"1-3\": \"Comma-delimited list of email address to send error notifications to. Only applies if sendEmailOnError is set to true.\",\n    \"2-3\": \"Subject of email that gets sent to administrators on errors. Only applies if sendEmailOnError is set to true.\",\n    \"3-3\": \"List of variables (or entire scopes) to exclude from the scope dumps included in error emails. Use this to keep sensitive information from being sent in plain text over email.\",\n    \"4-3\": \"When set to true, CFWheels will send an email to administrators whenever CFWheels throws an error.\",\n    \"5-3\": \"When set to true, CFWheels will show debugging information in the footers of your pages.\",\n    \"6-3\": \"When set to false, CFWheels will run and display code stored at events/onerror.cfm instead of revealing CFML errors.\"\n  },\n  \"cols\": 4,\n  \"rows\": 7\n}\n[/block]\nFor more information, refer to the chapter about [Switching Environments](doc:switching-environments).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Caching Settings\"\n}\n[/block]\nCFWheels 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.\n\nLet'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:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<cfset set(cacheRoutes=false)>\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n**Full Listing of Caching Settings** \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Default\",\n    \"h-3\": \"Description\",\n    \"0-0\": \"cacheActions\",\n    \"1-0\": \"cacheControllerInitialization\",\n    \"2-0\": \"cacheCullInterval\",\n    \"3-0\": \"cacheCullPercentage\",\n    \"4-0\": \"cacheDatabaseSchema\",\n    \"5-0\": \"cacheFileChecking\",\n    \"6-0\": \"cacheImages\",\n    \"7-0\": \"cacheModelInitialization\",\n    \"8-0\": \"cachePages\",\n    \"9-0\": \"cachePartials\",\n    \"10-0\": \"cacheQueries\",\n    \"11-0\": \"clearQueryCacheOnReload\",\n    \"12-0\": \"cacheRoutes\",\n    \"13-0\": \"defaultCacheTime\",\n    \"14-0\": \"maximumItemsToCache\",\n    \"0-1\": \"boolean\",\n    \"1-1\": \"boolean\",\n    \"4-1\": \"boolean\",\n    \"5-1\": \"boolean\",\n    \"6-1\": \"boolean\",\n    \"7-1\": \"boolean\",\n    \"8-1\": \"boolean\",\n    \"9-1\": \"boolean\",\n    \"10-1\": \"boolean\",\n    \"12-1\": \"boolean\",\n    \"11-1\": \"boolean\",\n    \"14-1\": \"numeric\",\n    \"13-1\": \"numeric\",\n    \"2-1\": \"numeric\",\n    \"3-1\": \"numeric\",\n    \"0-2\": \"Enabled in maintenance, testing, and production\",\n    \"1-2\": \"Enabled in development, maintenace, testing, and production\",\n    \"2-2\": \"5\",\n    \"3-2\": \"10\",\n    \"4-2\": \"Enabled in development, maintenance, testing, and production\",\n    \"5-2\": \"Enabled in development, maintenance, testing, and production\",\n    \"6-2\": \"Enabled in development, maintenance, testing, and production\",\n    \"7-2\": \"Enabled in development, maintenance, testing, and production\",\n    \"8-2\": \"Enabled in maintenance, testing, and production\",\n    \"9-2\": \"Enabled in maintenance, testing, and production\",\n    \"10-2\": \"Enabled in maintenance, testing, and production\",\n    \"11-2\": \"true\",\n    \"12-2\": \"Enabled in development, maintenance, testing, and production\",\n    \"13-2\": \"60\",\n    \"14-2\": \"5000\",\n    \"0-3\": \"When set to true, CFWheels will cache output generated by actions when specified (in a caches() call, for example).\",\n    \"1-3\": \"When set to false, any changes you make to the init() function in the controller file will be picked up immediately.\",\n    \"2-3\": \"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.\",\n    \"3-3\": \"If you set this value to 10, then at most, 10% of expired items will be deleted from the cache.\",\n    \"4-3\": \"When set to false, you can add a field to the database, and CFWheels will pick that up right away.\",\n    \"5-3\": \"When set to true, CFWheels will cache whether or not controller, helper, and layout files exist\",\n    \"6-3\": \"When set to true, CFWheels will cache general image information used in imageTag() like width and height.\",\n    \"7-3\": \"When set to false, any changes you make to the init() function in the model file will be picked up immediately.\",\n    \"8-3\": \"When set to true, CFWheels will cache output generated by a view page when specified (in a renderPage() call, for example).\",\n    \"9-3\": \"When set to true, CFWheels will cache output generated by partials when specified (in a includePartial() call for example).\",\n    \"10-3\": \"When set to true, CFWheels will cache SQL queries when specified (in a findAll() call, for example).\",\n    \"11-3\": \"Set to true to clear any queries that CFWheels has cached on application reload.\",\n    \"12-3\": \"When set to true, CFWheels will cache routes across all pageviews.\",\n    \"13-3\": \"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 CFWheels (i.e., caches(), findAll(), includePartial(), etc.)\",\n    \"14-3\": \"Maximum number of items to store in CFWheels'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.\"\n  },\n  \"cols\": 4,\n  \"rows\": 15\n}\n[/block]\nFor more information, refer to the chapter on [Caching](doc:caching).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"ORM Settings\"\n}\n[/block]\nThe 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.\n\nFor 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:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<cfset set(tableNamePrefix=\\\"blog_\\\")>\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nNow your `post` model will map to the `blog_posts` table, `comment` model will map to the `blog_comments` table, etc.\n\n**Full Listing of ORM Settings** \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Default\",\n    \"h-3\": \"Description\",\n    \"0-0\": \"afterFindCallbackLegacySupport\",\n    \"0-1\": \"boolean\",\n    \"1-1\": \"boolean\",\n    \"2-1\": \"boolean\",\n    \"3-1\": \"string\",\n    \"4-1\": \"string\",\n    \"5-1\": \"string\",\n    \"6-1\": \"string\",\n    \"7-1\": \"string\",\n    \"8-1\": \"boolean\",\n    \"9-1\": \"boolean\",\n    \"1-0\": \"automaticValidations\",\n    \"2-0\": \"setUpdatedAtOnCreate\",\n    \"3-0\": \"softDeleteProperty\",\n    \"4-0\": \"tableNamePrefix\",\n    \"5-0\": \"timeStampOnCreateProperty\",\n    \"6-0\": \"timeStampOnUpdateProperty\",\n    \"7-0\": \"transactionMode\",\n    \"8-0\": \"useExpandedColumnAliases\",\n    \"9-0\": \"modelRequireInit\",\n    \"9-2\": \"false\",\n    \"8-2\": \"true\",\n    \"7-2\": \"commit\",\n    \"6-2\": \"updatedAt\",\n    \"5-2\": \"createdAt\",\n    \"4-2\": \"[empty string]\",\n    \"3-2\": \"deletedAt\",\n    \"2-2\": \"true\",\n    \"1-2\": \"true\",\n    \"0-2\": \"true\",\n    \"0-3\": \"When this is set to false and you're implementing an afterFind() callback, you need to write the same logic for both the this scope (for objects) and arguments scope (for queries). Setting this to false makes both ways use the arguments scope so you don't need to duplicate logic. Note that the default is true for backwards compatibility.\",\n    \"1-3\": \"Set to false to stop CFWheels from automatically running object validations based on column settings in your database.\",\n    \"2-3\": \"Set to false to stop CFWheels from populating the updatedAt timestamp with the createdAt timestamp's value.\",\n    \"3-3\": \"Name of database column that CFWheels will look for in order to enforce soft deletes.\",\n    \"4-3\": \"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\",\n    \"5-3\": \"Name of database column that CFWheels will look for in order to automatically store a \\\"created at\\\" time stamp when records are created.\",\n    \"6-3\": \"Name of the database column that CFWheels will look for in order to automatically store an \\\"updated at\\\" time stamp when records are updated.\",\n    \"7-3\": \"Use commit, rollback, or none to set default transaction handling for creates, updates and deletes.\",\n    \"8-3\": \"When set to true, CFWheels will always prepend children objects' names to columns included via findAll()'s include argument, even if there are no naming conflicts. For example, model(\\\"post\\\").findAll(include=\\\"comment\\\") in a fictitious blog application would yield these column names: id, title, authorId, body, createdAt, commentID, commentName, commentBody, commentCreatedAt, commentDeletedAt. When this setting is set to false, the returned column list would look like this: id, title, authorId, body, createdAt, commentID, name, commentBody, commentCreatedAt, deletedAt.\",\n    \"9-3\": \"Set to true to have CFWheels throw an error when it can't find an init() method for a model. If you prefer to always use init() methods, this setting could save you some confusion when it appears that initializer code isn't running due to misspelling init.\"\n  },\n  \"cols\": 4,\n  \"rows\": 10\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Plugin Settings\"\n}\n[/block]\nThere are several settings that make plugin development more convenient. We recommend only changing these settings in `design` or `development` modes so there aren't any deployment issues in `production`, `testing`, and `maintenance` modes. (At that point, your plugin should be properly packaged in a zip file.)\n\nIf 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 `config/design/settings.cfm` and/or `config/development/settings.cfm`:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<cfset set(overwritePlugins=false)>\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nSee the chapter on [Using and Creating Plugins](doc:using-and-creating-plugins) for more information.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Default\",\n    \"h-3\": \"Description\",\n    \"0-0\": \"deletePluginDirectories\",\n    \"1-0\": \"loadIncompatiblePlugins\",\n    \"2-0\": \"overwritePlugins\",\n    \"0-1\": \"boolean\",\n    \"1-1\": \"boolean\",\n    \"2-1\": \"boolean\",\n    \"0-2\": \"true\",\n    \"1-2\": \"true\",\n    \"2-2\": \"true\",\n    \"0-3\": \"When set to true, CFWheels will remove subdirectories within the plugins folder that do not contain corresponding plugin zip files. Set to false to add convenience to the process for developing your own plugins.\",\n    \"1-3\": \"Set to false to stop CFWheels from loading plugins whose supported versions do not match your current version of CFWheels.\",\n    \"2-3\": \"When set to true, CFWheels 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.\"\n  },\n  \"cols\": 4,\n  \"rows\": 3\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Media Settings\"\n}\n[/block]\nConfigure how CFWheels handles linking to assets through view helpers like [imageTag()](doc:imagetag), [styleSheetLinkTag()](doc:stylesheetlinktag), and [javaScriptIncludeTag()](doc:javascriptincludetag).\n\nSee the chapter about [Date, Media, and Text Helpers](doc:date-media-and-text-helpers)  for more information.\n\n**Full Listing of Asset Settings**\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"assetQueryString\",\n    \"1-0\": \"assetPaths\",\n    \"0-1\": \"boolean\",\n    \"0-2\": \"false in design and development environments, true in the others\",\n    \"h-0\": \"Name\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Default\",\n    \"h-3\": \"Description\",\n    \"0-3\": \"Set to true to append a unique query string based on a time stamp to JavaScript, CSS, and image files included with the media view helpers. This helps force local browser caches to refresh when there is an update to your assets. This query string is updated when reloading your CFWheels application. You can also hard code it by passing in a string.\",\n    \"1-3\": \"Pass false or a struct with up to 2 different keys to autopopulate the domains of your assets: http (required) and https. For example: {http=\\\"asset0.domain1.com,asset2.domain1.com,asset3.domain1.com\\\", https=\\\"secure.domain1.com\\\"}\",\n    \"1-1\": \"struct\",\n    \"1-2\": \"false\"\n  },\n  \"cols\": 4,\n  \"rows\": 2\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Routing Settings\"\n}\n[/block]\nCFWheels includes a powerful routing system. Parts of it are configurable with the following settings.\n\nSee the chapters about [Using Routes](doc:using-routes) and [Obfuscating URLs](doc:obfuscating-urls) for more information about how this all works together.\n\n**Full Listing of Miscellaneous Settings**\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Default\",\n    \"h-3\": \"Description\",\n    \"0-0\": \"loadDefaultRoutes\",\n    \"1-0\": \"obfuscateUrls\",\n    \"0-1\": \"boolean\",\n    \"1-1\": \"boolean\",\n    \"0-2\": \"true\",\n    \"1-2\": \"false\",\n    \"0-3\": \"Set to false to disable CFWheels's default route patterns for controller/action/key, etc.\",\n    \"1-3\": \"Set to true to obfuscate primary keys in URLs.\"\n  },\n  \"cols\": 4,\n  \"rows\": 2\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"View Helper Settings\"\n}\n[/block]\nCFWheels has a multitude of view helpers for building links, forms, form elements, and more. Use these settings to configure global defaults for their behavior.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Default\",\n    \"h-3\": \"Description\",\n    \"0-0\": \"dataAttributeDelimiter\",\n    \"0-1\": \"string\",\n    \"0-2\": \"_\",\n    \"0-3\": \"Delimeter to use for inserting hyphens in HTML5 data attributes. By default, data_topnav will be converted to an attribute of data-topnav. To use camelCase instead, set this setting to A-Z, and dataTopnav will be converted to data-topnav.\",\n    \"1-0\": \"booleanAttributes\",\n    \"1-1\": \"any\",\n    \"1-2\": \"allowfullscreen, async, autofocus, autoplay, checked, compact, controls, declare, default, defaultchecked, defaultmuted, defaultselected, defer, disabled, draggable, enabled, formnovalidate, hidden, indeterminate, inert, ismap, itemscope, loop, multiple, muted, nohref, noresize, noshade, novalidate, nowrap, open, pauseonexit, readonly, required, reversed, scoped, seamless, selected, sortable, spellcheck, translate, truespeed, typemustmatch, visible\",\n    \"1-3\": \"A list of HTML attributes that should be allowed to be set as boolean values when added to HTML tags (e.g. `disabled` instead of `disabled=\\\"disabled\\\"`). You can also pass in `true` (all attributes will be boolean) or `false` (no boolean attributes allowed, like in XHTML).\"\n  },\n  \"cols\": 4,\n  \"rows\": 2\n}\n[/block]","excerpt":"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.","slug":"configuration-and-defaults","type":"basic","title":"Configuration and Defaults"}

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 is this performed. [block:api-header] { "type": "basic", "title": "Where Configurations Happen" } [/block] You will find configuration files in the `config` folder of your CFWheels 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](doc:switching-environments) for more details. [block:api-header] { "type": "basic", "title": "How to Set Configurations" } [/block] To change a CFWheels application default, you generally use the [set()](doc:set) function. With it, you can perform all sorts of tweaks to the framework's default behaviors. [block:api-header] { "type": "basic", "title": "How to Access Configuration Values" } [/block] Use the [get()](doc:get) function to access the value of a CFWheels application setting. Just pass it the name of the setting. [block:code] { "codes": [ { "code": "<cfif get(\"environment\") is \"production\">\n <!--- Do something for production environment --->\n</cfif>", "language": "text" } ] } [/block] [block:api-header] { "type": "basic", "title": "Setting CFML application Configurations" } [/block] In CFML's standard `Application.cfc`, you can normally set values for your application's properties in the `this` scope. CFWheels 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`: [block:code] { "codes": [ { "code": "<cfset this.name = \"TheNextSiteToBeatTwitter\">\n<cfset this.sessionManagement = false>\n<cfset this.customTagPaths = ListAppend(\n this.customTagPaths,\n ExpandPath(\"../customtags\")\n)>", "language": "text" } ] } [/block] [block:api-header] { "type": "basic", "title": "Types of Configurations Available" } [/block] 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: * Environment settings * URL rewriting settings * Data source settings * Function settings * Debugging and error settings * Caching settings * Media settings * Routing settings * View helper settings Let's take a closer look at each of these options. [block:api-header] { "type": "basic", "title": "Environment Settings" } [/block] 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 `config/environment.cfm` and should look something like this: [block:code] { "codes": [ { "code": "<cfset set(environment=\"development\")>", "language": "text" } ] } [/block] **Full Listing of Environment Settings** [block:parameters] { "data": { "h-0": "Name", "h-1": "Type", "h-2": "Default", "h-3": "Description", "0-0": "environment", "1-0": "reloadPassword", "2-0": "ipExceptions", "0-1": "string", "1-1": "string", "2-1": "string", "0-2": "development", "1-2": "[empty string]", "2-2": "[empty string]", "0-3": "Environment to load. Set this value in config/environment.cfm. Valid values are design, development, testing, maintenance, and production.", "1-3": "Password to require when reloading the CFWheels application from the URL. Leave empty to require no password.", "2-3": "IP addresses that CFWheels 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." }, "cols": 4, "rows": 3 } [/block] [block:api-header] { "type": "basic", "title": "URL Rewriting Settings" } [/block] 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: [block:code] { "codes": [ { "code": "<cfset set(urlRewriting=\"Off\")>", "language": "text" } ] } [/block] 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](doc:url-rewriting). [block:api-header] { "type": "basic", "title": "Data Source Settings" } [/block] 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: [block:code] { "codes": [ { "code": "<cfset set(dataSourceName=\"yourDataSourceName\")>\n<cfset set(dataSourceUserName=\"yourDataSourceUsername\")>\n<cfset set(dataSourcePassword=\"yourDataSourcePassword\")>", "language": "text" } ] } [/block] [block:api-header] { "type": "basic", "title": "Function Settings" } [/block] 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: [block:code] { "codes": [ { "code": "<cfset set(functionName=\"findAll\", perPage=20)>", "language": "text" } ] } [/block] That little line of code will make all calls to the [findAll()](doc:findall) method in CFWheels return a maximun number of 20 record per page (if pagination is enabled for that [findAll()](doc:findall) call). How great is that? You don't need to set the `perPage` value for every single call to [findAll()](doc:findall) if you have a different requirement than the CFWheels default of 10 records. [block:api-header] { "type": "basic", "title": "Debugging and Error Settings" } [/block] 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 design and development environments. For example, let's say that we want to enable debugging information in our "development" environment temporarily: [block:code] { "codes": [ { "code": "<!--- /config/development/settings.cfm --->\n<cfset set(showDebugInformation=false)>", "language": "text" } ] } [/block] **Full Listing of Debugging and Error Settings** [block:parameters] { "data": { "h-0": "Name", "h-1": "Type", "h-2": "Default", "h-3": "Description", "0-0": "errorEmailServer", "1-0": "errorEmailAddress", "2-0": "errorEmailSubject", "3-0": "excludeFromErrorEmail", "4-0": "sendEmailOnError", "5-0": "showDebugInformation", "6-0": "showErrorInformation", "0-1": "string", "1-1": "string", "2-1": "string", "3-1": "string", "4-1": "boolean", "5-1": "boolean", "6-1": "boolean", "0-2": "[empty string]", "1-2": "[empty string]", "3-2": "[empty string]", "2-2": "Error", "4-2": "Enabled in production environments that have a TLD like .com, .org, etc.", "5-2": "Enabled in design and development", "6-2": "Enabled in design, development, maintenance, and testing", "0-3": "Server to use to send out error emails. When left blank, this defaults to settings in the ColdFusion Administrator (if set).", "1-3": "Comma-delimited list of email address to send error notifications to. Only applies if sendEmailOnError is set to true.", "2-3": "Subject of email that gets sent to administrators on errors. Only applies if sendEmailOnError is set to true.", "3-3": "List of variables (or entire scopes) to exclude from the scope dumps included in error emails. Use this to keep sensitive information from being sent in plain text over email.", "4-3": "When set to true, CFWheels will send an email to administrators whenever CFWheels throws an error.", "5-3": "When set to true, CFWheels will show debugging information in the footers of your pages.", "6-3": "When set to false, CFWheels will run and display code stored at events/onerror.cfm instead of revealing CFML errors." }, "cols": 4, "rows": 7 } [/block] For more information, refer to the chapter about [Switching Environments](doc:switching-environments). [block:api-header] { "type": "basic", "title": "Caching Settings" } [/block] 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: [block:code] { "codes": [ { "code": "<cfset set(cacheRoutes=false)>", "language": "text" } ] } [/block] **Full Listing of Caching Settings** [block:parameters] { "data": { "h-0": "Name", "h-1": "Type", "h-2": "Default", "h-3": "Description", "0-0": "cacheActions", "1-0": "cacheControllerInitialization", "2-0": "cacheCullInterval", "3-0": "cacheCullPercentage", "4-0": "cacheDatabaseSchema", "5-0": "cacheFileChecking", "6-0": "cacheImages", "7-0": "cacheModelInitialization", "8-0": "cachePages", "9-0": "cachePartials", "10-0": "cacheQueries", "11-0": "clearQueryCacheOnReload", "12-0": "cacheRoutes", "13-0": "defaultCacheTime", "14-0": "maximumItemsToCache", "0-1": "boolean", "1-1": "boolean", "4-1": "boolean", "5-1": "boolean", "6-1": "boolean", "7-1": "boolean", "8-1": "boolean", "9-1": "boolean", "10-1": "boolean", "12-1": "boolean", "11-1": "boolean", "14-1": "numeric", "13-1": "numeric", "2-1": "numeric", "3-1": "numeric", "0-2": "Enabled in maintenance, testing, and production", "1-2": "Enabled in development, maintenace, testing, and production", "2-2": "5", "3-2": "10", "4-2": "Enabled in development, maintenance, testing, and production", "5-2": "Enabled in development, maintenance, testing, and production", "6-2": "Enabled in development, maintenance, testing, and production", "7-2": "Enabled in development, maintenance, testing, and production", "8-2": "Enabled in maintenance, testing, and production", "9-2": "Enabled in maintenance, testing, and production", "10-2": "Enabled in maintenance, testing, and production", "11-2": "true", "12-2": "Enabled in development, maintenance, testing, and production", "13-2": "60", "14-2": "5000", "0-3": "When set to true, CFWheels will cache output generated by actions when specified (in a caches() call, for example).", "1-3": "When set to false, any changes you make to the init() function in the controller file will be picked up immediately.", "2-3": "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.", "3-3": "If you set this value to 10, then at most, 10% of expired items will be deleted from the cache.", "4-3": "When set to false, you can add a field to the database, and CFWheels will pick that up right away.", "5-3": "When set to true, CFWheels will cache whether or not controller, helper, and layout files exist", "6-3": "When set to true, CFWheels will cache general image information used in imageTag() like width and height.", "7-3": "When set to false, any changes you make to the init() function in the model file will be picked up immediately.", "8-3": "When set to true, CFWheels will cache output generated by a view page when specified (in a renderPage() call, for example).", "9-3": "When set to true, CFWheels will cache output generated by partials when specified (in a includePartial() call for example).", "10-3": "When set to true, CFWheels will cache SQL queries when specified (in a findAll() call, for example).", "11-3": "Set to true to clear any queries that CFWheels has cached on application reload.", "12-3": "When set to true, CFWheels will cache routes across all pageviews.", "13-3": "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 CFWheels (i.e., caches(), findAll(), includePartial(), etc.)", "14-3": "Maximum number of items to store in CFWheels'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." }, "cols": 4, "rows": 15 } [/block] For more information, refer to the chapter on [Caching](doc:caching). [block:api-header] { "type": "basic", "title": "ORM Settings" } [/block] 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: [block:code] { "codes": [ { "code": "<cfset set(tableNamePrefix=\"blog_\")>", "language": "text" } ] } [/block] 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** [block:parameters] { "data": { "h-0": "Name", "h-1": "Type", "h-2": "Default", "h-3": "Description", "0-0": "afterFindCallbackLegacySupport", "0-1": "boolean", "1-1": "boolean", "2-1": "boolean", "3-1": "string", "4-1": "string", "5-1": "string", "6-1": "string", "7-1": "string", "8-1": "boolean", "9-1": "boolean", "1-0": "automaticValidations", "2-0": "setUpdatedAtOnCreate", "3-0": "softDeleteProperty", "4-0": "tableNamePrefix", "5-0": "timeStampOnCreateProperty", "6-0": "timeStampOnUpdateProperty", "7-0": "transactionMode", "8-0": "useExpandedColumnAliases", "9-0": "modelRequireInit", "9-2": "false", "8-2": "true", "7-2": "commit", "6-2": "updatedAt", "5-2": "createdAt", "4-2": "[empty string]", "3-2": "deletedAt", "2-2": "true", "1-2": "true", "0-2": "true", "0-3": "When this is set to false and you're implementing an afterFind() callback, you need to write the same logic for both the this scope (for objects) and arguments scope (for queries). Setting this to false makes both ways use the arguments scope so you don't need to duplicate logic. Note that the default is true for backwards compatibility.", "1-3": "Set to false to stop CFWheels from automatically running object validations based on column settings in your database.", "2-3": "Set to false to stop CFWheels from populating the updatedAt timestamp with the createdAt timestamp's value.", "3-3": "Name of database column that CFWheels will look for in order to enforce soft deletes.", "4-3": "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", "5-3": "Name of database column that CFWheels will look for in order to automatically store a \"created at\" time stamp when records are created.", "6-3": "Name of the database column that CFWheels will look for in order to automatically store an \"updated at\" time stamp when records are updated.", "7-3": "Use commit, rollback, or none to set default transaction handling for creates, updates and deletes.", "8-3": "When set to true, CFWheels will always prepend children objects' names to columns included via findAll()'s include argument, even if there are no naming conflicts. For example, model(\"post\").findAll(include=\"comment\") in a fictitious blog application would yield these column names: id, title, authorId, body, createdAt, commentID, commentName, commentBody, commentCreatedAt, commentDeletedAt. When this setting is set to false, the returned column list would look like this: id, title, authorId, body, createdAt, commentID, name, commentBody, commentCreatedAt, deletedAt.", "9-3": "Set to true to have CFWheels throw an error when it can't find an init() method for a model. If you prefer to always use init() methods, this setting could save you some confusion when it appears that initializer code isn't running due to misspelling init." }, "cols": 4, "rows": 10 } [/block] [block:api-header] { "type": "basic", "title": "Plugin Settings" } [/block] There are several settings that make plugin development more convenient. We recommend only changing these settings in `design` or `development` modes so there aren't any deployment issues in `production`, `testing`, and `maintenance` modes. (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 `config/design/settings.cfm` and/or `config/development/settings.cfm`: [block:code] { "codes": [ { "code": "<cfset set(overwritePlugins=false)>", "language": "text" } ] } [/block] See the chapter on [Using and Creating Plugins](doc:using-and-creating-plugins) for more information. [block:parameters] { "data": { "h-0": "Name", "h-1": "Type", "h-2": "Default", "h-3": "Description", "0-0": "deletePluginDirectories", "1-0": "loadIncompatiblePlugins", "2-0": "overwritePlugins", "0-1": "boolean", "1-1": "boolean", "2-1": "boolean", "0-2": "true", "1-2": "true", "2-2": "true", "0-3": "When set to true, CFWheels will remove subdirectories within the plugins folder that do not contain corresponding plugin zip files. Set to false to add convenience to the process for developing your own plugins.", "1-3": "Set to false to stop CFWheels from loading plugins whose supported versions do not match your current version of CFWheels.", "2-3": "When set to true, CFWheels 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." }, "cols": 4, "rows": 3 } [/block] [block:api-header] { "type": "basic", "title": "Media Settings" } [/block] Configure how CFWheels handles linking to assets through view helpers like [imageTag()](doc:imagetag), [styleSheetLinkTag()](doc:stylesheetlinktag), and [javaScriptIncludeTag()](doc:javascriptincludetag). See the chapter about [Date, Media, and Text Helpers](doc:date-media-and-text-helpers) for more information. **Full Listing of Asset Settings** [block:parameters] { "data": { "0-0": "assetQueryString", "1-0": "assetPaths", "0-1": "boolean", "0-2": "false in design and development environments, true in the others", "h-0": "Name", "h-1": "Type", "h-2": "Default", "h-3": "Description", "0-3": "Set to true to append a unique query string based on a time stamp to JavaScript, CSS, and image files included with the media view helpers. This helps force local browser caches to refresh when there is an update to your assets. This query string is updated when reloading your CFWheels application. You can also hard code it by passing in a string.", "1-3": "Pass false or a struct with up to 2 different keys to autopopulate the domains of your assets: http (required) and https. For example: {http=\"asset0.domain1.com,asset2.domain1.com,asset3.domain1.com\", https=\"secure.domain1.com\"}", "1-1": "struct", "1-2": "false" }, "cols": 4, "rows": 2 } [/block] [block:api-header] { "type": "basic", "title": "Routing Settings" } [/block] CFWheels includes a powerful routing system. Parts of it are configurable with the following settings. See the chapters about [Using Routes](doc:using-routes) and [Obfuscating URLs](doc:obfuscating-urls) for more information about how this all works together. **Full Listing of Miscellaneous Settings** [block:parameters] { "data": { "h-0": "Name", "h-1": "Type", "h-2": "Default", "h-3": "Description", "0-0": "loadDefaultRoutes", "1-0": "obfuscateUrls", "0-1": "boolean", "1-1": "boolean", "0-2": "true", "1-2": "false", "0-3": "Set to false to disable CFWheels's default route patterns for controller/action/key, etc.", "1-3": "Set to true to obfuscate primary keys in URLs." }, "cols": 4, "rows": 2 } [/block] [block:api-header] { "type": "basic", "title": "View Helper Settings" } [/block] 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. [block:parameters] { "data": { "h-0": "Name", "h-1": "Type", "h-2": "Default", "h-3": "Description", "0-0": "dataAttributeDelimiter", "0-1": "string", "0-2": "_", "0-3": "Delimeter to use for inserting hyphens in HTML5 data attributes. By default, data_topnav will be converted to an attribute of data-topnav. To use camelCase instead, set this setting to A-Z, and dataTopnav will be converted to data-topnav.", "1-0": "booleanAttributes", "1-1": "any", "1-2": "allowfullscreen, async, autofocus, autoplay, checked, compact, controls, declare, default, defaultchecked, defaultmuted, defaultselected, defer, disabled, draggable, enabled, formnovalidate, hidden, indeterminate, inert, ismap, itemscope, loop, multiple, muted, nohref, noresize, noshade, novalidate, nowrap, open, pauseonexit, readonly, required, reversed, scoped, seamless, selected, sortable, spellcheck, translate, truespeed, typemustmatch, visible", "1-3": "A list of HTML attributes that should be allowed to be set as boolean values when added to HTML tags (e.g. `disabled` instead of `disabled=\"disabled\"`). You can also pass in `true` (all attributes will be boolean) or `false` (no boolean attributes allowed, like in XHTML)." }, "cols": 4, "rows": 2 } [/block]