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. Plugins were introduced at version 4.0 and are a great way to create code that is useful to a wide variety of developers but shouldn't necessarily be a part of the core files. They make a lot of sense for scenarios such as exception handling and security.

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 DealLets 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.

Additional Information

External Links