DirectoryStructure-Conventions

<< Back to Dashboard

ColdBox Directory Structure & Conventions

In order to create a ColdBox application you must adhere to some naming conventions and a directory structure. This is needed in order for ColdBox to find what it needs and to help you find modules more easily. Also, ColdBox provides you with the ability to change these conventions for your applications.

Core Conventions

The core conventions delineate the contract between ColdBox and you for file/directory locations and more.

Directory Structure

Please note that the directory structure of your application relies on the conventions that you setup. So the structure changes according to the settings described above. Below is the simplest form of a ColdBox application directory layout:

Above you will see the core conventions plus some extra files and folders:

Application Templates

The ColdBox bundle download includes several application templates that can help you get started with ColdBox. Also, the best way to create or generate applications is via our ColdBox Platform Utilities extension for Adobe ColdFusion Builder. Our bundle download includes the following application templates:

Modifying Application Conventions

The only convention you can not directly modify in the configuration file is well, the location of the configuration file. However, you can still do this by setting up the location via the Application.cfc directives (See Loading a custom configuration file). These per-app conventions increase the portability of the ColdBox application, as now you can override any setting a framework-wide installation might have implemented and you are guaranteed that they will work. All you need to do is add the following to the configuration file:

//Conventions
conventions = {
	handlersLocation = "handlers",
	pluginsLocation  = "plugins",
	viewsLocation 	 = "views",
	layoutsLocation  = "layouts",
	modelsLocation 	 = "model",
	modulesExternalLocation  = "",
	eventAction 	 = "index"
};

We also encourage you to review the full Configuration CFC guide for an in-depth review.

Modifying Framework-Wide Conventions

As you saw from the section above, you can have application conventions, but you can also define your own conventions for a single framework installation. This is useful to maintain integrity in development teams or if they are applicable to your applications. Custom app-conventions exist with portability in mind. There are two ways to modify the framework's conventions: ColdBox Dashboard or directly via the framework's settings.xml file. The ColdBox Dashboard provides an intuitive GUI to modify and maintain your ColdBox installation. So I strongly suggest using the Dashboard. If you would like to do this manually, you will first need to open the following file: coldbox/system/web/config/settings.xml. You will then see the following snippet and modify as needed. This will become your new application layout:

<-- <Conventions -->
<Conventions>
    <configLocation>config/coldbox.xml.cfm,config/Coldbox.cfc</configLocation>
    <handlerLocation>handlers</handlerLocation>
    <pluginsLocation>plugins</pluginsLocation>
    <layoutsLocation>layouts</layoutsLocation>
    <viewsLocation>views</viewsLocation>
    <eventAction>index</eventAction>
    <modelslocation>model</modelslocation>
	<modulesLocation>modules</modulesLocation>		
</Conventions>

Implicit Execution Conventions

ColdBox also provides you with several implicit execution conventions that are mostly used in your event handlers. Basically by creating a method with a certain signature or name, ColdBox will call it for you. Below is just a listing of these method conventions.

• preHandler(event,action,eventArguments) - Ocurrs before any action event in a handler CFC
• postHandler(event,action,eventArguments) - Ocurrs after any action event in a handler CFC
• aroundHandler(event,targetAction,eventArguments) - Ocurrs around any action event in a handler CFC
• onMissingAction(event,missingAction,eventArguments) - Ocurrs when a requested action is missing in the handler CFC
• onError(event,action,exception,eventArguments) - Ocurrs when an exception ocurrs within any action in the handler CFC
• onDIComplete() - Ocurrs after handler creation and dependency injection has been performed