Vinny: Yeah, that's clear, clear as mud. What's with this "self" and "XFA." stuff?
Me: Self is a variable that's set to the home circuit's default page.
Vinny: So, why don't you just say that: "index.cfm"?
Me: What happens if your code is deployed on a server that uses "default.cfm"? By using a variable, the code is more portable.
Vinny: What about these XFA things?
Me: XFAs stand for eXit FuseActions. They're also variables.
Vinny: Why do we need those?
Me: Well, two of the design goals of Fusebox 3.0 are to make code more reusable and more maintainable. Imagine that you wrote some code that performs a user login and validation.
Vinny: Yeah, we're gonna need that.
Me: Sure. But lots of applications need the same basic functionality. However, where you head to after validation differs for each application. In some applications, after the user is validated, we want them to go to a catalog. Other applications might send them to a personalized home page, or maybe to an admin page.
Vinny: Okay. But what's that got to do with XFAs?
Me: Well, look at this code that validates a user. I wrote it for another application several months ago. I'll take out the XFAs:

<cfif UserInfo.recordCount>
<cflocation url="#self#?fuse-
action=catalog.personalized">
<cfelse>
<cflocation url="#self#?fuse-
action=login.badLogin">
</cfif>

<cfif UserInfo.recordCount>
<cflocation url="#self#?fuse-
action=#XFA.success#">
<cfelse>
<cflocation url="#self#?fuse-
action=#XFA.failure#">
</cfif>

Vinny: Wait, those all seem like pretty much the same file, no?
Me: Yes, they are. This is the true core Fusebox file and it comes in different flavors, depending on the version of ColdFusion server you're running.
Vinny: But you said that this "self" thing is where everything goes back to, so isn't that really the true core file?
Me: No, all that does is call the core Fusebox file. In fact, "self" can be as simple as this:

<cfinclude template="FBX_Fusebox30_CF50.cfm">

Vinny: Okay, go on with the other core files.
Me: There's a file called FBX_ Circuits.cfm. This lets you define aliases for directory names (or circuits).
Vinny: Why would you want to do that?
Me: Because you may have more than one circuit with the same name. Look at the directory structure in Figure 3.

Here you have two circuits with the same name, "Users." How will the core FBX_Fusebox file know which one you mean?
Vinny: That FBX_Circuits file?
Me: Right. You provide aliases for the directories. Here's the FBX_ Circuits.cfm file for the "sample-app" application:

<cfset fusebox.Circuits.home="
sampleapp">
<cfset fusebox.Circuits.admin =
"sampleapp/Admin">
<cfset fusebox.Circuits.inventory
= "sampleapp/Admin/Inventory">
<cfset fusebox.Circuits.users =
"sampleapp/Admin/Users">
<cfset fusebox.Circuits.main =
"sampleapp/Users">

On the left side of each definition is an entry into a structure called "fusebox.Circuits". That structure is automatically created by the core file.

Vinny: FBX_Fusebox_thingamajig.
Me: Right. The alias to be used is really a key in this circuit. On the right side of the equals sign is the path to the appropriate circuit beginning with the home circuit.

Now when you make a call back to the default page - remember I showed you several examples? - you provide the circuit alias name, followed by a dot separator, and then the name of the fuseaction you want performed, like this:

<cflocation url="#self#?fuseaction=users.newUser">

Vinny: That answers my question about the dot stuff. But I thought you said we don't use the fuseaction name itself, that we use an XFA?
Me: That's right. It would really look more like:

<cflocation url="#self#?fuseaction=#XFA.addUser#">

Vinny: Two questions: Where did you get that name "XFA.addUser"? There's no "addUser" in the schematic you did.
Me: That's easy: I made it up. I make up XFAs to describe as best I can the condition under which an XFA would be called. They don't have to correspond with the actual fuseaction name. Remember, that's just a variable name.
Vinny: Okay, but it looks like a circuit alias - dot - fuseaction thing, and you don't have a circuit called "XFA".
Me: No, "XFA" is a structure that's set in the FBX_Fusebox file. I'm just using a key to that structure.
Vinny: I got it. But where does the value of that key get set?
Me: Good question. For that we have to go to the FBX_Switch.cfm file. First, you need to know a little about what the FBX_Fusebox file is doing.
Vinny: Okay.
Me: When the core file gets a request for a compound fuseaction, something like "Users.newUser" (and for now, just trust that XFA.addUser gets resolved to that), it uses the FBX_Circuits file.

The core file says in effect, "You said 'Users.newUser', but you really mean 'sampleApp/Admin/Users'."
Vinny: This it gets from FBX_ Circuits?
Me: Right! With that knowledge it calls the file FBX_Switch.cfm that's found in the target directory.
Vinny: The target directory being "sampleApp/Admin/Users"?
Me: Right again. It also strips off the circuit alias and the dot separator and presents what's left as the variable "fusebox.fuseaction".
Vinny: When it gets to the FBX_Switch file in sample/App/Admin/Users, that file sees a variable called "fusebox.fuseaction"?
Me: Yes. Let's look at that file. Here's a portion of it:

<cfswitch expression = "#fuse
box.fuseaction#">
<cfcase value="newUser">
<cfset XFA.submitForm =
"Users.addUser">
<cfset XFA.cancelForm =
"Home.main">
<cfinclude template="dsp_New-
UserForm.cfm">
</cfcase>
</cfswitch>

Vinny: Yeah, so that's where they get set.
Me: Yes. You can look at XFAs as "candidate fuseactions." When the fuse returns to self, it does so with only one fuseaction, right?
Vinny: Yeah. That's the <cflocation url="#self#?fuseaction=#XFA.something#">.
Me: Right, and the value of the fuseaction depends on the exit path chosen. If the user clicks the submit button on the form, we'll use the value of "XFA.submitForm" as the fuseaction's value.
Vinny: What would that look like? The code, I mean.
Me: Like this:

<form action="#self#"
method="post">
<input type="hidden"
name="fuseaction" value="#XFA.submitForm#">
...
<input type="submit" value=" OK ">
</form>

After we set the values of the XFAs, we include whatever fuses are needed to perform the task at hand. Here, we just call "dsp_NewUserForm.cfm".
Vinny: Where would you ever need more than one?
Me: Well, you might need to include a query file prior to calling another display file, that's one example.
Vinny: Yeah, okay.
Me: Now we have to deal with the question of where we set common variables.
Vinny: Like what?
Me: Like "self," for example. Or maybe the data source for a database used throughout the application. We've got another core file for that, FBX_Settings.cfm.
Vinny: Is that just in the home circuit?
Me: No, it goes in every circuit. This enables Fusebox to implement a simple inheritance mechanism, while allowing children to override their parents' settings.
Vinny: It just has "self" and the data source?
Me: No, it can have anything you want. For example, you could put the "<cfapplication>" tag in the home circuit's FBX_Settings.cfm file. If you had common XFAs across an application, you could put those in FBX_Settings.
Vinny: When do I call them - the FBX_Settings files?
Me: They're called automatically by the core Fusebox file. In fact, the core file uses the directory path for the target circuit...
Vinny: Wait, what's that mean again?
Me: The directory path is the part on the right side of the equal sign in FBX Circuits. This code in FBX_ Circuits

<cfset fusebox.Circuits.users = "sampleapp/Admin/Users">

is used by the core file to create a list of circuits whose FBX_Settings.cfm files it will include.

Vinny: It will first include the FBX_Settings file in "sampleApp", then in "Admin", and then in "Users"?
Me: Right, and it does it in that order. That lets the coder set variables higher "up" the tree if he or she wants them to be inherited by children circuits. Those variables can always be overridden by one of the children, if needed.
Vinny: Huh, that makes sense.
Me: There's just one other thing you would need to know. Fusebox 3 has the concept of nested layouts.
Vinny: How does that work?
Me: Well, it lets you "wrap" the content generated by your fuses in a layout file. Figure 4 shows an example of one I did for teaching purposes. See how many layouts you can spot.

I'll give you a couple of hints. Figure 5 provides the circuit structure for the application. I'll also tell you that the fuseaction being called was "grandson.sayHi".
Vinny: Hmmm...well, I'm thinking that "Hi there!" is what the fuse in the grandson circuit did. Is that right?
Me: So far, so good.
Vinny: Then I'm thinking that each box is a layout applied to that content. That right?
Me: Right again.
Vinny: There would be four levels of layout applied: grandson, son, father, and home. But we don't have a "home" circuit.
Me: Well, those are the alias names, and if you looked at that application's FBX_Circuit's file, you'd see that I aliased the grandparent circuit as "home".
Vinny: Hey, I like that!
Me: Me, too. Nested layouts are immensely powerful stuff.
Vinny: You just gotta remember to call them in the right order.
Me: No, the core Fusebox file takes care of that for you. It uses that same "fuseaction path", sample-app/Admin/Users in our example, and reverses it to Users/Admin/ sampleApp. Then it walks "up" that tree, including FBX_Layouts.cfm for each circuit.
Vinny: Yeah, that's cool.
Me: See, Vinny? Face it, you were born to be a programmer. Ditch this gangster stuff and...
Vinny: Yeah, I wanna discuss that very shortly. For now, though, is there anything else I need to know to get my application completed?
Me: Well, the FBX_Layouts.cfm file sets two variables: "fusebox.layoutfile" and "fusebox.layoutdir". Unless you want to have a separate directory for layout files, you can set "fusebox.layoutdir" to an empty string:

<cfset fusebox.layoutdir = "">

Vinny: What about "fusebox.layoutfile"?
Me: That points to a file that, well, take a look at the one I used for that sample application I just showed you:

<cfoutput>
<style>
.#Fusebox.thisCircuit# {
border : double Silver;
}
</style>
<table class="#Fusebox.thisCircuit#">
<tr>
<td>
<font size="-2">Don't mind me, I'm just the #Fusebox.thisCircuit#</font>
</td>
</tr>
<tr>
<td>
#Fusebox.layout#
</td>
</tr>
</table>

</cfoutput>

Editor's Note: The last section planned for this article, "Final Thoughts," had to be omitted since, at this point, we stopped receiving updates from the author. More information may be found at www.halhelms.com.