With a convention-over-configuration framework like CFWheels, it's important to know these conventions. This is your guide.
There is a specific set of standards that CFWheels 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.
CFWheels 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
Consider this example URL:http://localhost/users/edit/12
This maps to the
editaction, 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
This URL pattern works up the chain and will also handle the following example URLs:
Note that the above conventions are for
GETrequests and only apply when you have a
config/routes.cfm(which is the default). See Routing for instructions on overriding this behavior and how to deal with
Controllers, actions, and views are closely linked together by default. And how you name them will influence the URLs that CFWheels will generate.
First, a controller is a CFC file placed in the
controllersfolder. It should be named in
PascalCase. For example, a site map controller would be stored at
Multi-word controllers will be delimited by hyphens in their calling URLs. For example, a URL of
/site-mapwill reference the
Methods within the controllers, known as actions, should be named in
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-engineswill reference the
searchEnginesaction in the
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.
/site-map/search-enginesURL example, the corresponding view file would be stored at
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
views/layout.cfmand is automatically used by all views in the application.
Controller-level layouts can also be set automatically by creating a file called
layout.cfmand storing it in the given controller's view folder. For example, to create a layout for the
userscontroller, the file would be stored at
When a controller-level layout is present, it overrides the default layout stored in the root
By default, the names of CFWheels models, model properties, database tables, and database fields all relate to each other. CFWheels even sets a sensible default for the CFML data source used for database interactions.
CFWheels will automatically look for a data source with the same name as the folder that your application is deployed in. If your CFWheels application is in a folder called
blog, CFWheels will look for a data source called
blog, for example.
CFWheels 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
usermodel represents a record from the
usersdatabase table. CFWheels also recognizes plural patterns like
Like controller files, models are also CFCs and are named in
PascalCase. They are stored in the
modelsfolder. So the user model would be stored at
In your database, both table names and column names should be lowercase. The
customersegmentstable could have fields called
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.
customersegmentsexample above, you could refer to the properties in your CFML as
incomeLevelto stick to CFML's Java-style roots. (Built-in CFML functions are often written in
PascalCase, after all.)
There are many default values and settings that you can tweak in CFWheels 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 CFWheels functions to keep your code DRYer.