The circuit.xml file

While there is only one fusebox.xml file in a Fusebox application, you need a circuit.xml file in each circuit's directory. This file is used to define a circuit's fuseactions as well as setting access modifiers and permissions. Here is an example of an circuit.xml file for you to refer to as we discuss the different elements of this file:

<circuit access="public">
<prefuseaction callsuper="true">
<do action="sayings.whatsUpDoc"/>
</prefuseaction>
<fuseaction name="welcome">
<include template="dspWelcome.cfm"/>
</fuseaction>
<postfuseaction>
<do action="sayings.thatsAllFolks"/>
</postfuseaction>
</circuit>

circuit

The root element of the circuit.xml file are the circuits. Within the circuit element are three possible sub-elements: fuseaction, prefuseaction, and postfuseaction.

The circuit element has two optional attributes, access and permissions. They are used to set default values for the same attributes on the fuseactions within the circuit.

Allowed values for access are: public, internal, and private. If no access attribute is specified for the circuit, the default will be set to internal.

There is no default value for permissions.

You can also specify XML namespaces, a.k.a. lexicons, in the <circuit> tag:

<circuit xmlns:prefix="path/to/verbs/">

This defines an XML namespace, prefix, that allows you to use custom verbs (<prefix:verb/>) and custom attributes (prefix:attr=value) throughout the circuit file. Custom verbs can be used in any fuseaction. Custom attributes can be specified on any <fuseaction> tag.

fuseaction

The name attribute is required and identifies each fuseaction uniquely. You cannot have duplicate values for this attribute within a single circuit (although different circuits may have identically named fuseactions).

The access parameter allows you to determine how the fuseaction can be called. If no access attribute is specified for a fuseaction element, the access set in the circuit element is used. Allowed values are: public, internal, and private.

An access value of public means that the fuseaction can be called from anywhere within the Fusebox application, as well as by a user through their web browser.

When an access attribute is given the value of internal, the circuit cannot be called by a user from a web browser, but can be called from other fuseactions in the application.

The third access modifier is private, signifying that the fuseaction can only be called by a fuseaction within the same circuit. If no access attribute is specified, it takes on the access modifier of its circuit or internal if no access modifier is specified in the circuit element.

The permissions attribute is a list of permissions that can access a given circuit or fuseaction. There is no built in security mechanism in Fusebox and applying security based on the permissions attribute is usually handled with a plugin. There are several chapters in this book that demonstrate how to use the permissions attribute with a security plugin for Fusebox that you may wish to use or adapt.

prefuseaction, postfuseaction

There are two other main elements of a circuit: prefuseaction and postfuseaction. The prefuseaction element holds fuseactions to be executed automatically before the initially called fuseaction is executed. That is, if you have a request of index.cfm?fuseaction=user.bar and you have a fuseaction of home.foo within your prefuseaction element, home.foo will be executed, followed by user.bar. The postfuseaction element automatically executes after the called fuseaction is completed.

Both prefuseaction and postfuseaction elements have a common Boolean attribute: callsuper. When callsuper is set to true in a prefuseaction, Fusebox 4 will first run the prefuseaction in the parent circuit. Once done, any prefuseaction fuseactions will be run. If, within the parent circuit's prefuseaction element, callsuper is again set to true, the prefuseaction of the grandparent circuit will first be called. The same applies to using callsuper with postfuseaction, except that parent circuit's postfuseaction code runs after the current postfuseaction is completed.

Additional Information