• Promote reuse of code
• Allow small applications to scale larger ones
• Support division of labor among content providers, programmers, graphic artists and layout workers.
• Make code easier to read and understand
• Made maintaining code more easy
• Allow programmers to "embed" an entire CF application by turning the application into a CF tag

Figure 1 Fusebox App Structure

CF files are known as "fuses". Every application has one fusebox, but may have many fuses. The architecture resembles a "hub and spoke" system, with all action returning to the "hub" (the Fusebox). Each fuse is modular in design, which makes maintaining code easier. The structure of fuses may be less defined - a single fuse is designed to have limited functionality.

A circuit application is usually a single directory of files and generally does a few related tasks such as search. Each of the circuit applications is be given its own directory

A home application is the overall application which is made up of many circuit applications. The root directory of the home app will be included in all app_locals.cfm files which are in every circuit application. The root directory of your home application may contain a circuit application itself.

There are five main types of files for building an application.s Tag library:

1. app_ Application files
2. dsp_ Display files
3. qry_ Query files
4. act_ Action files
5. CF_ custom tag extensions

• App_globals.cfm and app_locals.cfm contain global and local variables that are needed for an application.
• App_locals.cfm will always include an app_globals.cfm file
• App_locals.cfm will contain default variables specific to smaller application
• App_globals.cfm will contain variables that are global to the overall application (in the app_globals file we refer to formurl2attributes)
• App_Globals.cfm file is <CFINCLUDE>d as part of Fusebox's initialization and setup, which gives us a place to put variables that will be used by many fuses
• Application.cfm will not be used: when a file is called through a tag (CFMODULE) or when the application.cfm does not get called.
• App_locals will be CFincluded at the top of the index.cfm

<CFAPPLICATION NAME="Someapplicationname" CLIENTMANAGEMENT="YES" SESSIONMANAGEMENT="YES">

2. Display Files (i.e. - dsp_yourfilename.cfm)

When modifying applications later, all you have to work with are the display files. Display files (dsp_) contain HTML and simple CFML and do not change data on the server, they only display info on the screen to the user and gather user input

A dsp_ file will never insert a new record into a database, but it may select info from a database using CF. The dsp_ files are the only files that contain info the user will see:

• cfinclude html and graphics
• cfinclude template=/blocks/dsp_.cfm

3. Query Files- (i.e. - qry_yourfilename.cfm"

Global query files will begin with qry_ - CFINCLUDE the query file to reuse.

Directory named queries will be created off the root dir of your app, this is where global query files will be stored, which begin with qry_. Query files contain queries that may be reused in multiple parts of the application, these queries are cached when possible

• cfinclude qry in display file
• cfinclude template=qry_.cfm

Query files are a new file type, useful when used with query caching and should only be used when the rest of Fusebox concepts have been mastered. Query files generally have only a single CFQUERY in them, but are not restricted to one. The tag has a "cached within" attribute built in which takes timespan of when to auto refresh.
 
 

4. Action Files (i.e. - act_yourfilename.cfm (i.e. act_searching.cfm) )

Action files (act_) contain CFML and may not contain HTML. Action files can be used to insert, delete, and update within a database or could be used to change other data such as writing to a file or making changes to the data in an LDAP server. However, no info will be displayed to the user. These files are not limited to database changes, they can also be used for doing tasks that do not fit well into a display file. act_.cfm- will do CFLDAP and CFLOOP.
 
 

5. CFX (ie - <CF_SOMETAG> or <CFX_SOMETAG>)

Exists in the custom tags directory. CF extensions are CF tag or CFX tag that have been added to the CF server. The easiest way to maintain multiple CF apps is to create CF mapping to the root directory of each app. CF mapping is specific to the CFINCLUDE and CFMODULE tags, anywhere in your site you can <CFINCLUDE template="/ROOTMAPPING /queries/qry_somequery.cfm"

<CFINCLUDE template="/ROOTMAPPING/blocks/dsp_someblock.cfm">

CF mappings are set in CF Administrator.

CFID and CFTOKEN can be used as cookie, form, or URL variables. You can then use client or session variables. If you plan on using client or session variables, it's recommended that you not rely on people using cookies. Attach #URLtoken# onto all of your links.
 
 

FuseAction

Fuse Manager File= index.cfm, acts as the box, the Fusebox is the index.cfm. This is the parent file which controls all the apps methods, known as "FuseActions". All requests for an application will go through this file. The job of the fusebox is to manage the action. It delegates actions to the fuses, which may be single or compound. The fuse-files are <CFINCLUDE>d into the fusebox which allows them to inherit all the variables of the fusebox itself.

The task of this file is to determine what CF code is necessary to do the "FuseAction" the user needs to do. For scalability with large applications, an index.cfm should be in every directory in your application. Each directory will consist of essentially a different application. The first two lines of index.cfm will refer to app locals and app_globals. Point all "href" and "action" attributes of your forms and links to the index.cfm and include the fuseaction as a form field or as a URL variable. All urls refer to index.cfm (may be something like /search/index.cfm- (absolute path)).

Note: the tags CFSWITCH/CFCASE are much faster than CFIF/CFELSEIF. When there are many ELSEIF's, the logic is exactly the same. Index.cfm will contain CFSWITCH/CFCASE to determine what the user wants to do. (Think of the index.cfm is basically one big switch statement and each CFCASE is a diff. Fuseaction. An example: fuseaction=search - might run search and then display)
 

An application is always called through the index.cfm and all links and form actions will point to the index.cfm.

All URL links, forms, and CFMODULE tags will pass an attribute called Fuseaction. This attribute is the name of the action to be performed.

Attribute Variables

All variables that are changed by users within a Fusebox application should be scoped with "attributes" in your app_globals file all Form. and URL. Scoped variables will be converted to attributes.variable, this allows an application to become both a standalone application and a CF Tag, which is exactly what Fusebox applications are trying to accomplish

The custom tag FormURL2Attributes converts form and URL-style variables to attributes variables. The use of attributes variables is essential to encapsulating an entire app so that it can be called as if it were a custom tag, using <CF_tagname> or <Cf_module>. You can get minor increase in speed using CFINCLUDE instead of CFMODULE.

App_globals.cfm contains info that is needed for every page of the application. This file will need to include the <CF_FORMURL2ATTRIBUTES> tag which will change all "form" and "URL" scoped variables to the "attributes" scope. It allows you to call index.cfm using CFMODULE along with being able to call the application from a standard browser.

When you call a custom tag (i.e. FormURL2Attributes.cfm) CF takes any variables passed and makes them part of the attributes collection- to reference them you must use the "attributes." Prefix- this custom tag converts both form and URL variables into attributes. Variables -cfmodule can call circuit app as a tag.

cfmodule template=/ has to be an attributes variable- within the custom tag you must refer to any variables with the "attributes."

If no Attributes.Fuseaction variable exists, then the default page will be displayed. In the app_locals.cfm file, a default value will be set for attributes.fuseaction using the CFPARAM tag.

General Fusebox issues

When dealing with multiple file web apps it is important to realize that there are two types of Fusebox Tag Objects:

1. Single page Tag Objects- fairly simple to integrate into other apps.
2. Dual page Tag Objects- requires user interaction

The CF (fusebox) file is made up of only two sections:

1. The first is responsible for a definition of variables that will affect the entire application. You can either define each variable in the fusebox or <CFINCLUDE> a page that holds this info (the latter is better for large projects).
2. The second part of fusebox is responsible for direction. At any one time, the app has only one fuseaction, each user action is associated with a fuseaction- a single <CFSWITCH> statement determines the value of this variable that directs the program flow.

Create Fuse cards to design architecture:

• Fuseactions- dsp_, act_
• Reponsibilities
• Required attributes
• Optional attributes
• Return attributes
• RFA (Return Fuseaction)

Other CF programming tips

If you.re building a database from scratch, it is recommended that when creating a new table within your database to always use a single "number/integer" datatype as your primary and foreign key fields. This allows for the most integration with other database systems.

It's important that <CFTRANSACTION> be used when incrementing your primary key on the application side. By using CFTRANSACTION, your INSERT SQL statement and the MAX_ID will be treated as a single SQL statement on the database.
 
 

Sample Fusebox app

The follow index.cfm page is part of Steve.s SpecTool app. Fuses are marked in blue

<!---

// Copyright (C) 1999 Steve Nelson

// Distributed under the terms of the GNU Library General Public License

--->

<cfinclude template="app_globals.cfm">

<cfinclude template="app_locals.cfm">

<cf_bodycontent>

<cfswitch expression="#attributes.fuseaction#">

<cfcase value="createnewfile">

<cfinclude template="act_createnewfile.cfm">

<cflocation url="index.cfm?fuseaction=editspec&filename=#attributes.filename#" addtoken="No">

</cfcase>

<cfcase value="deletefile">

<cfinclude template="act_deletefile.cfm">

<cflocation url="index.cfm?fuseaction=choosefile" addtoken="No">

</cfcase>

<cfcase value="choosefile">

<cfinclude template="dsp_choosefile.cfm">

</cfcase>

<cfcase value="download">

<cfinclude template="act_download.cfm">

</cfcase>

<cfcase value="uploadspec">

<cfinclude template="act_uploadspec.cfm">

<cfinclude template="act_validupload.cfm">

<cflocation url="index.cfm?fuseaction=choosefile&validupload=#validupload#" addtoken="No">

</cfcase>

<cfcase value="viewspec">

<cfinclude template="act_getfile.cfm">

<cfinclude template="act_orderapplications.cfm">

<cfinclude template="dsp_viewspec.cfm">

</cfcase>

<cfcase value="viewspecflow">

<cfinclude template="act_getfile.cfm">

<cfinclude template="act_orderapplications.cfm">

<cfinclude template="dsp_viewspecflow.cfm">

</cfcase>

<cfcase value="wddx2datasource">

<cfinclude template="act_getfile.cfm">

<cfinclude template="act_orderapplications.cfm">

<cfinclude template="act_wddx2datasource.cfm">

</cfcase>

<cfcase value="editspec">

<cfinclude template="act_getfile.cfm">

<cfinclude template="act_orderapplications.cfm">

<cfinclude template="dsp_editspec.cfm">

</cfcase>

<cfcase value="save">

<cfinclude template="act_getfile.cfm">

<cfset maketree="no">

<cfinclude template="act_orderapplications.cfm">

<cfinclude template="act_saveapplication.cfm">

<cflocation url="index.cfm?fuseaction=editspec&filename=#attributes.filename#&applicationid=#thisapplicationid#&saved=yes" addtoken="No">

</cfcase>

<cfcase value="deletesection">

<cfinclude template="act_getfile.cfm">

<cfinclude template="act_deletesection.cfm">

<cflocation url="index.cfm?fuseaction=editspec&filename=#attributes.filename#" addtoken="No">

</cfcase>

<cfcase value="deleteaction">

<cfinclude template="act_getfile.cfm">

<cfinclude template="act_deleteaction.cfm">

<cflocation url="index.cfm?fuseaction=editspec&filename=#attributes.filename#" addtoken="No">

</cfcase>

<cfcase value="faq">

<cfinclude template="dsp_faq.cfm">

</cfcase>

</cfswitch>

</cf_bodycontent>

<cfinclude template="dsp_body.cfm">