In the previous section, planning your application, we arrived at an outline of objects and actions. In this section, we will turn that outline into a structure of directories and files for CFML code.

Directory and file structure

It is always good practice to separate different ColdFusion applications into different directories. FuseBox applications follow these general rules for organizing code within the main application directory:

1. For each object:

   • Create a subdirectory named after the object

   • Create an index.cfm file in that subdirectory

2. For each action:

   • Create a file in the directory of the object it corresponds to

The FuseBox methodology includes conventions for naming action files (also called fuses). These are optional but are strongly recommended to make it easier for other developers to "read" your application. The following conventions are the most common:

An ideal action file -- or fuse -- is short and carries out a quite specific task. As you work from your outline to create a framework of directories and files, you may find yourself adding actions that were not in your original outline, or even removing actions. For example:

• The action of editing an object typically consists of two parts, that of displaying a form with information for the user to edit, and that of updating a database after the user has submitted the form.

• The action of adding an object also typically consists of two parts, that of displaying a form for the user to add information about the new object, and that of inserting a new database record after the user has submitted the form. Furthermore, the same form that is used to edit an object can typically be re-used as the form for adding information about a new object.

• When two objects have a many-to-many relationship, editing that relationship typically takes place on a separate web page because of the limitations of the HTML web interface. (For an example of a many-to-many relationship, consider tasks and staff assigned to them. A task may have many staff associated with it, and a staff member usually works on several tasks.)

Returning to our example from the prior section, our directories and files might look like this:

As you apply the FuseBox methodology to multiple applications and objects, you will find that the lists of files in object directories start to look remarkably similar. In fact, it is possible to create application templates and literally cut and paste code for common actions.

The function of object index.cfm files

So far FuseBox is just a consistent way of arranging directories and files corresponding to objects and actions. Now we will consider how FuseBox helps control the flow of program control through the files in a ColdFusion application.

Typical ColdFusion application		FuseBox application

The index.cfm file for each object in a FuseBox application controls the application's use of all the actions associated with the object. The action files for an object are never linked to directly. Instead, you specify the object's index.cfm file, an Action parameter for the action you need, and any other necessary parameters.

Each object's index.cfm file is made up mostly of a CFSWITCH statement that considers the specified Action parameter and routes the program to the right code for the action. Here is what part of the CFSWITCH statement in the index.cfm file for the staff object in our example might look like:

<cfswitch expression="#Action#">

<cfcase value="List">

<cfinclude template="dsp_List.cfm">

</cfcase>

...

<cfdefaultcase>

<cflocation url="index.cfm?Action=List">

</cfdefaultcase>

</cfswitch>

As you can see, the index.cfm file uses CFINCLUDE to include the code of the relevant action file. In this example, if a user linked to "index.cfm?Action=List" the ColdFusion application server would process the content of the index.cfm file, including the content of the dsp_List.cfm file. If no action is specified, the object responds with a default action. For a more complete example, see the index.cfm file in our first application template.

Centralizing program flow in the object index.cfm files conveys several important benefits:

1. Each index.cfm file provides an overview of the actions related to each object. It is an ideal place for documentation, and in some cases servers as documentation all by itself.

2. The index.cfm file provides a "bottleneck" at which to check for the existence of vital parameters and other conditions for successfully executing each action.

3. Code common to all the actions for an object can be centralized in the index.cfm file. For example, HTML headers and footers can be written once. If desired, error checking using CFTRY and CFCATCH can be written once (see the index.cfm file in the second application template). If applicable, user authentication or authorization can be performed in one place.

4. An object's actions can be added, removed, or modified in a centralized way. While a developer is working on a new action, it is not available until it is specified in the index.cfm file. When an action or an entire object needs maintenance, it can be disabled in a graceful way. Furthermore, action files can be renamed at will and the index.cfm file updated.

Typically it is desirable to prevent users from accessing parts of an application without getting there as you intended. For this reason, most FuseBox applications include in their Application.cfm file a piece of code such as this one, which effectively prevents a user from accessing any action file on its own (without the object's index.cfm):

<cfif ListLast(GetTemplatePath(),"\") is not "index.cfm">

<cflocation url="index.cfm">

</cfif>

At this point you may wish to move on to our application templates site, where you will find working examples of FuseBox applications at different levels of complexity. Or you read on to find out what the FuseBox methodology has to say about documenting your application.