Conventions
With a convention-over-configuration framework like Wheels, it's important to know these conventions. This is your guide.
Last updated
Was this helpful?
3.0.0-SNAPSHOT
With a convention-over-configuration framework like Wheels, it's important to know these conventions. This is your guide.
Last updated
Was this helpful?
There is a specific set of standards that Wheels follows when you run it in its default state. This is to save you time. With conventions in place, you can get started coding without worrying about configuring every little detail.
But it is important for you to know these conventions, especially if you're running an operating system and/or DBMS configuration that's picky about things like case sensitivity.
Wheels uses a very flexible routing system to match your application's URLs to controllers, views, and parameters.
Within this routing system is a default route that handles many scenarios that you'll run across as a developer. The default route is mapped using the pattern [controller]/[action]/[key].
Consider this example URL:http://localhost/users/edit/12
http://localhost/users/edit/12
This maps to the Users controller, edit action, and a key of 12. For all intents and purposes, this will load a view for editing a user with a primary key value in the database of 12.
This URL pattern works up the chain and will also handle the following example URLs:
users
edit
12
users
new
users
index
Note that the above conventions are for GET requests and only apply when you have a wildcard() call in app/config/routes.cfm (which is the default). See for instructions on overriding this behavior and how to deal with PUT, POST etc.
Controllers, actions, and views are closely linked together by default. And how you name them will influence the URLs that Wheels will generate.
First, a controller is a CFC file placed in the controllers folder. It should be named in PascalCase. For example, a site map controller would be stored at app/controllers/SiteMap.cfc.
Multi-word controllers will be delimited by hyphens in their calling URLs. For example, a URL of /site-map will reference the SiteMap controller.
Methods within the controllers, known as actions, should be named in camelCase.
Like with controllers, any time a capital letter is used in camelCase, a hyphen will be used as a word delimiter in the corresponding URL. For example, a URL of /site-map/search-engines will reference the searchEngines action in the SiteMap controller.
By default, view files are named after the action names and are stored in folders that correspond to controller names. Both the folder names and view file names should be all lowercase, and there is no word delimiter.
In our /site-map/search-engines URL example, the corresponding view file would be stored at app/views/sitemap/searchengines.cfm.
A special type of view file called a layout defines markup that should surround the views loaded by the application. The default layout is stored at app/views/layout.cfm and is automatically used by all views in the application.
Controller-level layouts can also be set automatically by creating a file called layout.cfm and storing it in the given controller's view folder. For example, to create a layout for the users controller, the file would be stored at app/views/users/layout.cfm.
When a controller-level layout is present, it overrides the default layout stored in the root app/views folder.
By default, the names of Wheels models, model properties, database tables, and database fields all relate to each other. Wheels even sets a sensible default for the CFML data source used for database interactions.
By default, the datasource is set to wheels.dev in the app/config/settings.cfm file. You can change the value in the set(dataSourceName="wheels.dev") function to whatever you want the name of the datasource to be.
Wheels adopts a Rails-style naming conventions for database tables and model files. Think of a database table as a collection of model objects; therefore, it is named with a plural name. Think of a model object as a representation of a single record from the database table; therefore, it is named with a singular word.
For example, a user model represents a record from the users database table. Wheels also recognizes plural patterns like binary/binaries, mouse/mice, child/children, etc.
Like controller files, models are also CFCs and are named in PascalCase. They are stored in the app/models folder. So the user model would be stored at app/models/User.cfc.
In your database, both table names and column names should be lowercase. The customersegments table could have fields called title, regionid, and incomelevel, for example.
Because of CFML's case-insensitive nature, we recommend that you refer to model names and corresponding properties in camelCase. This makes for easier readability in your application code.
In the customersegments example above, you could refer to the properties in your CFML as title, regionId, and incomeLevel to stick to CFML's Java-style roots. (Built-in CFML functions are often written in camelCase and PascalCase, after all.)
There are many default values and settings that you can tweak in Wheels when you need to. Some of them are conventions and others are just configurations available for you to change. You can even change argument defaults for built-in Wheels functions to keep your code DRYer.
new
See for instructions on overriding this behavior.
See for instructions on overriding this behavior.
For information on overriding this behavior, refer to documentation for the function and read the chapter.
For information on overriding the layout file to be loaded by an action, see the chapter on and documentation for the function.
Refer to the chapter for instructions on overriding data source information.
For instructions on overriding database naming conventions, refer to documentation for the function and the chapter on .
For information on overriding column and property names, refer to documentation for the function and the chapter.
For more details on what you can configure, read the chapter.