Fusebox 5.1 Enhancements

This page documents the major enhancements in Fusebox 5.1.

Globally Shared Files

Circuits, plugins, errortemplates and lexicons can all be shared across multiple Fusebox applications because you can specify absolute paths, i.e., that begin with a "/" so they are webroot-relative or resolved via a ColdFusion mapping.

Globally Shared Circuits

By default, circuits paths are relative to the application root. With Fusebox 5.1, you can now specify a new attribute on a <circuit> declaration in fusebox.xml that specifies whether a circuit path is relative or not (i.e., absolute or mapped). The default is relative="true". If you specify relative="false" and your path= attribute begins with a / then the circuit path will be treated as absolute (relative to your server's webroot) or mapped (resolved via a ColdFusion mapping).

<circuits>
    <circuit alias="c" path="controller/"/> <!-- default -->
    <circuit alias="m" path="/sharedcircuits/model/" relative="false"/> <!-- absolute / mapped path -->
    <circuit alias="v" path="views/" relative="true"/> <!-- explicit relative path -->
</circuits>

Globally Shared Plugins

When you declare a plugin, you can specify a template name and, optionally, a path that is relative to the plugins subdirectory of your application root:

<plugin name="myplug" template="plugin_page" path="relative/"/>

This tells Fusebox to look for plugin_page.cfm in the plugins/relative/ subdirectory of the application root.

With Fusebox 5.1, you have several new options:

• You can specify an absolute (or mapped) path= attribute.
• You can specify an absolute (or mapped) template= attribute (in some ways this is equivalent to the path= attribute),
• You can override the default pluginsPath for the entire application.

You can either specify a relative path:

<parameter name="pluginsPath" value="../../plugins"/>

or an absolute (or mapped) path:

<parameter name="pluginsPath" value="/sharedplugins"/>

If you specify a relative path= attribute and relative template= attribute in a plugin declaration, they are relative to the pluginsPath parameter.

Globally Shared Error Templates

By default, every Fusebox application has to have a copy of the error templates. With Fusebox 5.1, you can now override the location of the error templates by specifying the errortemplatesPath parameter in fusebox.xml. You can either specify a path relative to your application root or an absolute (or mapped) path:

<parameter name="errortemplatesPath" value="/sharederrors"/>

This causes Fusebox to look in the sharederrors directory under the webroot or wherever the /sharederrors ColdFusion mapping points for any exception templates.

Globally Shared Lexicons

By default, lexicons are introduced with the xmlns declaration in a fusebox or circuit tag as a prefix and a path that is relative to the lexicon directory under your application root. With Fusebox 5.1, you now have two additional options:

• You can specify an absolute or mapped path in the xmlns declaration.
• You can override the default base directory for lexicons by specifying the lexiconPath parameter in fusebox.xml.

If you specify an absolute or mapped path in a xmlns declaration, that defines the complete path for the declared lexicon, e.g.,

xmlns:prefix="/sharedlexicon/mylexicon"

Either sharedlexicon is a directory under your webroot or /sharedlexicon is a mapping. Fusebox would look in the mylexicon directory under sharedlexicon. This allows you to override the default search path for a specific lexicon.

You can also override the default lexicon search location for the entire application by specifying lexiconPath within fusebox.xml. The default is lexicon/ which is a directory below the application root. You can either specify a different path relative to your application root such as:

<parameter name="lexiconPath" value="../../externallexicon"/>

or you can specify an absolute or mapped path:

<parameter name="lexiconPath" value="/sharedlexicon"/>

In either of these cases, a relative path in an xmlns declaration is now relative to the lexiconPath location.

Search Engine Safe URLs

Handling of self, myself, <xfa> and <relocate> has been enhanced to allow you to specify how the URLs are constructed by the framework.

<xfa> now allows child tags: <parameter> can be used to specify URL parameter name / value pairs instead of specifying them directly in the XFA value. In other words, instead of saying:

<xfa name="edit" value="app.edittask&amp;id=#attributes.id#"/>

you would now say:

<xfa name="edit" value="app.edittask">
    <parameter name="id" value="#attributes.id#"/>
</xfa>

This cleanly separates the actual XFA - the fuseaction - from the various URL parameters in the target URL.

Fusebox uses fusebox.xml parameters to construct the URL parameter string. The following (optional) fusebox.xml parameters have been added:

Parameter'	Default	Description
self	index.cfm	Intended to be the base script name used to generate URLs
queryStringStart	?	The string to use between the script name and any URL parameters
queryStringSeparator	&	The string to use to separate individual URL parameters
queryStringEqual	=	The string to use between a URL parameter name and its value
myself		This is constructed as self & queryStringStart & fuseactionVariable & queryStringEqual by default but can be overridden

This means that you can construct so-called "Search Engine Safe" URLs automatically by specifying different values for these parameters. For example, by setting them all to "/", the XFA shown above becomes:

app.edittask/id/#attributes.id#

and the myself value becomes:

index.cfm/fuseaction/

Bear in mind that you'll need to use htmlEditFormat() to ensure XHTML compliant HTML is generated.

In addition, you can now specify an XFA name in the <relocate> verb:

<relocate xfa="edit"/>

This would construct a redirect to the full URL implied by myself and the XFA:

index.cfm/fuseaction/app.edittask/id/#attributes.id#

You can retrieve the framework-generated values for self and myself, as well as updating them on a per-request basis using these new methods on the myFusebox object:

Method	Arguments	Description
getSelf		Returns the current version of self
setSelf	string self	Changes the current version of self and recalculates myself
getMyself		Returns the current version of myself
setMyself	string myself	Changes the current version of myself, allowing non-standard base URLs to be created

Using event as an alternative to attributes

For developers who want a more object-oriented way to handle data that comes in from the URL and form scope, there is now an alternative to the attributes scope. An object called event is now available in the main variables scope with methods that allow you to get and set values within the underlying attributes scope.

The following methods are available on the event object:

Method	Arguments	Description
init	struct attributes	Used by Fusebox to create the event object as a shadow of the attributes scope.
getValue	string valueName, any defaultValue	Returns the named attribute value, or the specified default if no such value exists.
valueExists	string valueName	Returns true if and only if the named attribute exists in the attributes scope.
setValue	string valueName, any newValue	Sets the named attribute to the specified value.
getAllValues		Returns the attributes scope behind the event object.
removeValue	string valueName	Removes the named attribute from the attributes scope.

The event object is automatically created in the fusebox5.cfm file and is available in the main variables scope, just like the attributes structure. The intent is that event would be more idiomatic for use with a CFC-based model. It's full component name depends on the location of the Fusebox core files (it might be fusebox5.fuseboxEvent, for example) so developers should simply declare the argument type in their model component method to be type="any" and avoid direct dependence on the Fusebox path.