Fusebox (An Overview) Part III : The Finer Points of Fusebox

Aug 07, 2000

By Eron Cohen and Michael Smith

AppGlobals.cfm and AppLocals.cfm

In parts I and II of this series, you've seen us go through the physical setup and the coding logistics of a Fusebox application. Now, in part III, get ready to discuss the finer points of coding in Fusebox.

As we discussed in part II of this article, one of the most important ideas in the Fusebox methodology is that you break your code up into small modules and then use the ColdFusion CFINCLUDE statement to reconstitute the needed pieces back into your application on the fly. CFINCLUDE simply embeds the requested code back into your application as required.

A typical application is going to need more than just a few CFINCLUDES to make it complete. There needs to be a vehicle to set default variable values and to hold important ColdFusion tags such as CFAPPLICATION. In a Fusebox application, this is done through two files that always get included at the top of every INDEX.CFM file BEFORE your CFSWITCH statement. These are your app_locals.cfm and app_globals.cfm files.

These two files are really going to save you time! Any Fusebox application will always contain one and only one app_globals.cfm file. Its purpose is to house global variables, default values and any directives that will be needed for every part of your application. Its contents will always wind up at the top of every page of your application. This is accomplished by using CFINCLUDE to include the file's contents at the top of the app_locals.cfm file. Aside from conveying the values of the app_globals.cfm file, the app_locals.cfm file is basically used to house the values of variables that will only be needed for "local" sections of your application. A simple Fusebox application will only need one app_locals.cfm file. A more complex application could have many of them. To help clarify this, have a look at these two file listings:

App_Globals.cfm:

<CF_FORMURL2ATTRIBUTES>
<!---Set up the application file --->

<cfapplication name="MyApplication" sessionmanagement="yes" 
     clientmanagement="YES" setclientcookies="YES">

<!---Set up the default database name for the entire application --->

<CFPARAM NAME="application.dsn" DEFAULT="MyDatabaseName">

App_Locals.cfm:

<CFINCLUDE TEMPLATE="app_globals.cfm">

<!--- set the default fuseaction for this section of the app, 
     in case none is given --->

<cfparam name="fuseaction" default=" Sign_Up_For_Newsletter_Form ">

At the top of your INDEX.CFM file, you would need the following statement:

<CFINCLUDE TEMPLATE="app_locals.cfm">

As explained above, this would cause the app_locals.cfm file to be included, which in turn would include the app_globals.cfm file. You?ll want to put default values for your application in these two files. This way, whenever someone needs to change default values of some variable in your application, they can avoid opening up your code to search for the values. If they?re familiar with Fusebox, they?ll know right away that they can go directly to these two files.

Attribute Variables and <CF_FORMURL2ATTRIBUTES>

The use of attributes variables is essential to encapsulating an entire application so that it can be called as a custom tag, using <CF_TAGNAME> or <CF_MODULE>. To help facilitate this, all variables that are changed by users within a Fusebox application should be scoped with "attributes" in your app_globals file. This is done with a custom tag, which you'll see at the top of the app_globals.cfm file listed above: <CF_FORMURL2ATTRIBUTES>. This tag is an important part of a standard Fusebox application. It can be downloaded from www.fusebox.org?s custom tags area. Its main purpose is to change the scope of "URL." and "form." variables and convert them to the "attributes." scope. This allows a Fusebox application to become both a standalone application and a CF Tag, which makes it much more portable.

Index.cfm

The ColdFusion Fusebox file (Index.cfm) is made up of only two sections:

The first is responsible for a definition of variables that will affect the entire application. The normal way to do this is to CFINCLUDE your app_locals.cfm file, which in turn includes your app_globals.cfm file.
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.

A Sample Index.cfm File:

<!-- Part I: Definition of Variables
	Includes app_locals.cfm, which includes appglobals.cfm --->

<CFINCLUDE TEMPLATE="app_locals.cfm">

<!-- Part II: Direction of Fusebox Flow 
	Each CFCASE statement indicates a different fuseaction,
	and involves different fuses (all CFINCLUDEd)  --->

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

	<CFCASE value=?Sign_Up_For_Newsletter_Form">
		<CFINCLUDE template="/public/Main/blocks/dsp_html_header.cfm">
		<CFINCLUDE template="/public/Newsletter/blocks/dsp_reg_form.cfm">
		<CFINCLUDE template="/public/Main/blocks/dsp_html_footer.cfm">
	</CFCASE> 

	<CFCASE value=?Sign_Up_For_Newsletter_Form_Submitted">
		<CFINCLUDE template="/public/Main/blocks/dsp_html_header.cfm">
		<CFINCLUDE template="/public/Newsletter/queries/qry_chk_for_dups.cfm">
		<CFINCLUDE template="/public/Newsletter/blocks/dsp_reg_thnk_you.cfm">
		<CFINCLUDE template="/public/Main/blocks/dsp_html_footer.cfm">
	</CFCASE> 
	
</CFSWITCH>

Designing for Fusebox

One way to design a Fusebox application is to write down the elements of the program on 4 x 6 index cards. These "Fusecards" can then be shuffled to design the architecture. The follow elements can be put on a Fusecard:

Fuseactions: dsp_, act_
Responsibilities
Required attributes
Optional attributes
Return attributes
RFA (Return Fuseaction)

This system has been written about extensively by Hal Helms from TeamAllaire. See his website (http://www.teamallaire.com/hal) for more information about fusecards and how they can help you organize your site. Specifically, check out the Fusebox Primer at http://www.teamallaire.com/hal/articles/Fusebox1.htm (the section titled "Making Fuse-Responsibilities-Attributes Cards").

Other CF Programming Tips

We recommend that you always use a single "number/integer" datatype for your primary and foreign key fields when creating a new table within your database. This allows for the most integration with other database systems. You should specifically avoid using autonumber fields because many databases do not have this datatype. Don't forget that without the use of autonumber, you will need to manually increment your primary key. (The CF_MAX_ID tag from the Fusebox.org tag gallery makes this simple.)

We also strongly recommend that when maintaining the primary key manually, you turn on unique index for the field in question. This helps maintain referential integrity of the database by preventing contention between two people who happen to update the database simultaneously. In case a conflict does occur, use the CFTRY tags around your INSERT statements with a CFCATCH that retries the query. This way, you can be certain that the update will execute properly.

RULES ARE MADE TO BE BROKEN

The Fusebox standard is meant more as a series of guidelines. There is plenty of room built into the standard to allow for individual programmers' styles. Also, the standard is not perfect. Occasionally you may run across a site that will need to improvise on the Fusebox techniques. In this case, the recommendation is to try to stay as close as possible to the standard styles specified.

Keep your eyes open for more Fusebox articles on Fusion Authority, and for further news about the upcoming Fusebox book.