Plugins

Added by Adam Haskell, last edited by Adam Haskell on Apr 12, 2009 (view change)

Fusebox

Plugins are a way to extend the functionality of the Fusebox core files. Plugins are executed at designated times during the Fusebox request lifecycle.

The plugins element can contain several phase elements which define six possible places where the fusebox core can be extended.

An individual plugin can be declared like this inside any given phase:

This tells Fusebox to execute pluginFile.cfm during the appropriate phase of the request lifecycle. You can optionally specify a path attribute which specifies the path of the template relative to the plugins folder. As of Fusebox 5.1, you can specify an absolute (or mapped) path which then ignores the plugins folder and uses a path relative to the webroot or resolved via a mapping. The template attribute itself can specify an absolute (or mapped) path which will ignore the path attribute as well as the plugins folder.

As of Fusebox 5.1, the plugin declaration may also include custom attributes that use XML prefixes declared on the <fusebox> tag at the head of the Fusebox XML file.

Extending The FB5 Framework With Plugins

::TODO:: Complete documentation on Plugins. Below are the changes in FB5.

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.