[[Dashboard|<< Back to Dashboard]]

{| align="right"
| __TOC__
|}

= ColdBox Directory Structure & Conventions =
{{{Messagebox message="Covers up to version 3.5.0" type="info"}}}

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.

{| cellpadding="5", class="tablelisting"
! '''Convention''' !! '''Default Value''' !! '''Required''' !! '''Description''' 
|-
| '''config file location''' || ''/config/Coldbox.cfc'' || true || The location of the application configuration file
|-
| '''handlers location''' || ''/handlers'' || true || Where all event handlers are located
|-
| '''layouts location''' || ''/layouts'' || false || Where all layouts are located
|-
| '''views location''' || ''/views'' || false || Where all views are located
|-
| '''plugins location''' || ''/plugins'' || false || Where all plugins are located
|-
| '''models location''' || ''/model'' || false || Where all model objects are located
|-
| '''modules location''' || ''/modules'' || false || Where all modules are located
|-
| '''default event action'' || ''index()'' ||  false || The name of the default event action (method) to use when an event handler is called with no method
|-
| '''default event''' || '''main.index''' || false || The default event to execute when not defined in the configuration file and no incoming event is found
|} 


== 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:

<img src="/imagelibrary/ApplicationTemplate.png" alt="app" title="Super Simple Application Layout" />
<br/>
Above you will see the '''core conventions''' plus some extra files and folders:

{| cellpadding="5", class="tablelisting"
! '''Folder/File''' !! '''Required''' !! '''Description''' 
|-
| '''Application_noinheritance.cfc''' || false || The boostrap approach that uses non-inheritance (See [[Bootstrapper]])
|-
| '''Application.cfc''' || true || Used to boostrap the framework application using inheritance (See [[Bootstrapper]])
|-
| '''index.cfm''' || true || A placeholder file the framework needs for front controller operation. The file is usually empty.
|-
| '''config''' || true || Where your ColdBox configuration file goes, routing, and more.
|-
| '''handlers''' || true || Where your controller layer resides in the form of CFC event handlers
|-
| '''includes''' || false || Where you can place static assets like (css,images,i18n,js,etc)
|-
| '''layouts''' || false || Where your layout skins or themes go
|-
| '''model''' || false || Where your model layer resides
|-
| '''modules''' || false || Where all your ColdBox modules are placed.
|-
| '''test''' || false || Where all your unit, mocks and integration tests go (Yes, you need to test!)
|-
| '''views''' || false || Where your view layer resides
|} 

<div class="mynotes">Read more about our Application.cfc [[Bootstrapper]]</div>

{{{Messagebox message="Please read about our Bootstrapper to understand the difference between loading the framework using the standard inheritance Application.cfc or the non-inheritance approach.  The major difference is that the non-inheritance approach allows you to locate coldbox via per application mappings." type="info"}}}

=== 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 [[CFBuilderExtensions|ColdBox Platform Utilities extension]] for Adobe ColdFusion Builder.  Our bundle download includes the following application templates:

<img src="/imagelibrary/application-templates.png" alt="app" title="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 [[Bootstrapper|Application.cfc directives]] (See [[Recipes:Loading_a_Custom_ColdBox_Configuration_File | 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:

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

We also encourage you to review the full [[ConfigurationCFC#conventions|Configuration CFC guide]] for an in-depth review.

<div class="mynotes">
'''Important''' All conventions that are locations require a relative location to the Root of the running application. They cannot be set outside the root.
</div>


== Implicit Execution Conventions ==

ColdBox also provides you with several implicit execution conventions that are mostly used in your [[EventHandlers| 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