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 easier. It is up to you to organize your code. Also, ColdBox provides you with the ability to change these conventions for your applications. This is a great feature, since it lets developers create their own conventions on the internal structure of ColdBox Applications. The required conventions for a ColdBox Application are:

Required Conventions

• config file location
• handlers location
• layouts location
• views location
• plugins location

Modifying Conventions

There are two ways to modifying the framework's conventions: ColdBox Dashboard or directly via the framework's settings.xml file. The ColdBox Dashboard provides an intuitive GUI to modifying and maintaining 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/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{sep}coldbox.xml.cfm,config{sep}config.xml.cfm</configLocation>
   <handlerLocation>handlers</handlerLocation>
   <layoutsLocation>layouts</layoutsLocation>
   <viewsLocation>views</viewsLocation>
   <pluginsLocation>plugins</pluginsLocation>
</Conventions>

IMPORTANT NOTE: The most important part of the convention snippet is the '''{sep}''' characters. This is IMPORTANT and NECESSARY. This is how the framework will replace your OS File Separator. So please be aware of it in the config location setting ONLY

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 a typical directory layout:

+ApplicationRoot
|---+ config (REQUIRED where your coldbox.xml.cfm file goes or any other config files)
|---+ handlers (REQUIRED where your event handler cfc's go. You can use packages)
|---+ plugins (OPTIONAL where all your custom plugins go)
|---+ layouts (REQUIRED where all your layouts go)
|---+ views (REQUIRED where all your views go, you can use packages)
|---+ includes (OPTIONAL where your includes go:styles, images, etc. REQUIRED for i18N resource bundle locations.)
|---+ interceptors (OPTIONAL where your interceptors can go)
|---+ model (OPTIONAL where your model cfc's go, this can be whatever name you want)
|---+ logs (OPTIONAL where ColdBox can store the log files)
|---+ Application.cfc 
|---+ index.cfm

Layout Screenshot: