Perry Woodin
Updated: 16 July 2003
Core: v.045
This document is a simple "getting started" guide for migrating from Fusebox 3 to Fusebox 4. While the main concepts haven't changed much from FB3 to FB4 (your code still follows a hub and spoke model), there are some differences that make learning Fusebox 4 well worth the investment of time.
For example:
If you have taken a look at any of the examples on beta.fusebox.org, the first thing you may notice is the absence of the fbx_* files. Don't worry, the functionality of those fbx_* files is still available in Fusebox 4. You just need to know where to look.
Following is a brief overview of where to look in FB4 to find the functionality you are used to in FB3.
Starting from the top. If you open the index.cfm file the only significant difference is the name of the core file that is being included. The index.cfm file now includes <cfinclude template="fusebox40.runtime.cfmx.cfm">. As with FB3, every request is made to index.cfm.
At the top of the fusebox.xml file, you will set the circuit aliases that used to be handled by fbx_circuits.
FB3
<cfset fusebox.circuits.home = "/home">
<cfset fusebox.circuits.Users = "/home/Users">
FB4
<circuits>
<circuit alias="home" path="" parent=""/>
<circuit alias="Users" path="Users/" parent="home"/>
</circuits>
Continuing down the fusebox.xml file, you will find the parameters section. A couple of things to note here are the fuseactionVariable element, and the defaultFuseaction element.
The fuseactionVariable determines what the fuseaction should be called. If set to fuseaction, your query string would look like this: index.cfm?fuseaction=Users.Login. If set to method, your query string would look like this: index.cfm?method=Users.Login.
The defaultFuseaction determines what the default fuseaction should be. In FB3, this was typically set in the root fbx_settings as <cfparam name="attributes.fuseaction" default="Users.dspLogin">.
The remaining parameters can be left as is for now.
Following the fusebox-parameters section is the globalFuseactions section. Global fuseactions are split into preProcess and postProcess fuseactions. This is a great place to include a global header and footer.
Wrapping up the fusebox.xml file is the plugins section. Plugins allow developers to extend the core functionality without without changing the core files (more on this in the next section).
In Fusebox 3, children inherited from their parent via fbx_settings. In Fusebox 4, children still inherit from their parent, but inheritance is accomplished in a slightly different way.
If you download the Coin Toss example from beta.fusebox.org, and open the fusebox.xml file, you will see a plugin called Settings. This plugin allows you to drop a file called Settings.cfm into each directory. The new Settings.cfm file will function as fbx_settings.cfm did in FB3. If you still want your file to be called fbx_settings.cfm, you can designate the name of the file to suit your needs.
The circuits.xml file takes the place of the FB3 fbx_switch. The syntax difference may take some getting used to, but the structure of the file should look familiar.
The root element of the circuits.xml file is the circuit element. The circuit element takes a property called access with values of public or internal. If your request accesses a circuit directly, the access property will be set to public. For example: <circuit access="public">. If you are making a recursive call to a fuseaction, the access property will be set to internal.
These different values come in handy when utilizing MVC. The (C)ontroller circuits will be set to public and the (M)odel and (V)iew circuits will be set to internal.
The next element is the fuseaction element. The fuseaction element either includes a fuse or calls another fuseaction.
Including a fuse:
<fuseaction name="Login">
<include template="dspLogin.cfm"/>
</fuseaction>
Calling another fuseaction:
<fuseaction name="listProducts">
<do action="m.getProducts"/>
<do action="v.displayProducts"/>
</fuseaction>
In Fusebox 3, the cases would have looked like this:
Including a fuse:
<cfcase value="Login">
<cfinclude template="dspLogin.cfm"/>
</cfcase>
Calling another fuseaction:
<cfcase value="listProducts">
<cfmodule template="index.cfm" fuseaction="m.getProducts">
<cfmodule template="index.cfm" fuseaction="v.displayProducts">
</cfcase>
eXit FuseActions (XFAs) have made code reuse much easier. In FB3, some developers set their XFAs in the fbx_settings, some set their XFAs in each fuseaction, and some set XFAs all over the place (I'm guilty of this last offense). In FB4, you still have the same amount of flexibility.
You can:
Set an XFA in the Settings.cfm file (see Nested Settings above) with a simple <cfset xfa.submitForm = "c.dspConfirm" />.
Set an XFA in the fuseaction with <set name="xfa.submitForm" value="c.dspConfirm"/>.
Set an XFA in the fuseaction with <xfa name="submitForm" value="c.dspConfirm"/>.
This overview wouldn't be complete without talking about nested layouts. I have abandoned nested layouts in favor of using Content Component Variables (CCVs). With CCVs, you can set the content of your fuseaction to a variable which can then be output to the screen. When it comes to flexibility of layouts, CCVs can't be beat. Following is a brief description of how CCVs work
All of the content generated in v.HelloWorld will be available as the variable myContent, and thus output in Layout.simpleLayout.
There is a great deal more to Fusebox 4, but this overview should get you over the humps. I'll continue to update this document as Fusebox 4 evolves, and welcome any comments you may have. Send me an email at perry@acmearts.com.