Extending The Fusebox Framework With Plugins

A plugin is a code set that can be executed during a specific "plugin point" during a Fusebox request.

Fusebox 4 introduced the idea of extending the core functionality of Fusebox through "plugins" -- templates that are registered in Fusebox.xml and are called at each "plugin point". At present, there are six plugin points, corresponding to the six Phases mentioned earlier: Good candidates for plugins include security and validation, logging, and layouts/skins. Note that plugins for a given plugin point "fire" in the order specified in your fusebox.xml file. The preprocess plugins fire before any preProcess global fuseactions, and the preFuseaction plugins fire before any preFuseaction fuseactions. Conversely, the postFuseaction plugins fire after any postFuseaction fuseactions, and the postProcess plugins fire after any postProcess global fuseactions.

Plugins are initiated, and ran, within your fusebox.xml.cfm file, within the Plugin Processing Phase. The following is an example taken from the Lets Make a Deal Sample Application:

<plugins>
<phase name="preProcess">
<plugin name="Globals" template=" Globals.cfm"/>
<plugin name="SimpleSecurity" template="SimpleSecurity.cfm"/>
</phase>
<phase name="preFuseaction">
</phase>
<phase name="postFuseaction">
</phase>
<phase name="fuseactionException">
</phase>
<phase name="postProcess">
</phase>
<phase name="processError">
<plugin name="exceptionHandler" template="ExceptionHandler.cfm"/>
<plugin name="SecurityException" template=" SecurityException.cfm"/>
</phase>
</plugins>

Fusebox 5

Although nothing has really changed in this area of the framework - most Fusebox 4.1 plugins should continue to work with Fusebox 5 without any changes - there are two changes that will impact the lives of plugin authors:

  • The parsed XML is no longer available as part of the application.fusebox structure
  • There are a number of "convenience" methods in the myFusebox object
The former change will break some advanced plugins. Sorry. I just don't think the framework itself should have exposed those XML fragments and, with the revised compilation engine in Fusebox 5, the framework does not actually break the XML down the same way so it would actually be difficult to expose the same specific XML fragments that Fusebox 4.x exposed. However, in order to make it relatively easy for a plugin to find out the directory path and filename for the XML files, convenience methods are available on the fuseboxApplication and fuseboxCircuit objects.

Turning to the myFusebox object, there are the following convenience methods which may be useful to plugin authors:

  • getApplication() - returns the fuseboxApplication object that represents the application
  • getCurrentCircuit() - returns the fuseboxCircuit object that represents the currently executing circuit (if applicable)
  • getCurrentFuseaction() - returns the fuseboxAction object that represents the currently executing fuseaction (if applicable)
These methods are just shorthand for accessing the follow data respectively:

  • application![FUSEBOX_APPLICATION_KEY]
  • application![FUSEBOX_APPLICATION_KEY].circuits![myFusebox.thisCircuit]
  • application![FUSEBOX_APPLICATION_KEY].circuits![myFusebox.thisCircuit].fuseactions![myFusebox.thisFuseaction]
Locating the XML files is possible using these method calls on the myFusebox object:

  • myFusebox.getApplication().getApplicationRoot() & myFusebox.getApplication().getFuseboxXMLFilename() - returns the full filesystem path of the fusebox.xml (or fusebox.xml.cfm) file for this application
  • myFusebox.getCurrentCircuit().getCircuitRoot() & myFusebox.getCurrentCircuit().getCircuitXMLFilename() - returns the full filesystem path of the circuit.xml (or circuit.xml.cfm) file for the currently executing circuit
If a plugin needs to loop over all the circuit objects, it can do the following:

<cfloop collection="#myFusebox.getApplication().circuits#" item="circuitName">

All of the public methods in the various framework objects are documented (using the hint attribute) so that plugin authors can take advantage of all of the exposed framework functionality. View the automatically generated documentation.

Fusebox Framework Plugin Files

  • Nested Settings Plugin to mimic Fusebox 3 nested settings. Placed in the [refuseaction plugin point.
  • Globals Plugin Allows a single top-level include during the preprocess plugin point.
  • Exception Handler Plugin for simple exception handling at the fuseaction, circuit and application level. Used in the fuseactionException plugin point.

Related Links