allowImplicitCircuits parameter

Fusebox 5.1 introduced the parameter setting, allowImplicitCircuits, so that you could omit the circuit.xml file for a circuit that is used only as a container for fuses that are included by other circuits (via the <include> verb with the circuit= attribute). In such a situation, the circuit.xml file, if present, would be "empty", containing only <circuit/>, possibly with an access= attribute.

Fusebox 5.5 extends the meaning of allowImplicitCircuits to also indicate that circuit declarations can be omitted completely. If you omit fusebox.xml, you have no circuit declarations and so allowImplicitCircuits is automatically set to true. If fusebox.xml is present but you wish to omit the circuit declarations, you must set allowImplicitCircuits to true.

Implicitly locating a circuit

If you attempt to execute a fuseaction in a circuit that is not declared, Fusebox 5.5 attempts to deduce the location and form of the circuit using a series of conventions.

Fusebox 5.5 first attempts to find a regular circuit.xml (or circuit.xml.cfm) file by looking in the following locations relative to the application root (assuming a fuseaction of alias.action):

  • controller/alias/
  • model/alias/
  • view/alias/
  • alias/controller/
  • alias/model/
  • alias/view/
  • alias/

If a circuit file is found, it is treated as a regular Fusebox circuit that simply was not declared in fusebox.xml. Otherwise, Fusebox attempts to find a CFC that represents the circuit by looking for:

  • controller/alias.cfc [access="public"]
  • model/alias.cfc [access="internal"]
  • view/alias.cfc [access="internal"]

If such a CFC is found, it is treated as a circuit with the methods representing fuseactions. Otherwise, Fusebox looks for matching directories:

  • controller/alias/ [access="public"]
  • model/alias/ [access="internal"]
  • view/alias/ [access="internal"]
  • alias/ [access="public"]

If such a directory is found, it is treated as a circuit with the files within that directory representing fuseactions . see below. Otherwise, Fusebox throws an exception that the requested circuit is undefined. Whilst this may seem like a complicated set of rules, it is intended to support the most common conventions used today in Fusebox applications (and, in fact, in several other frameworks). The intent is that Fusebox should be intuitive to use without having to think about the rules: the common conventions should just work.

The first searches for circuit.xml files are intended to support common Fusebox conventions in the absence of a fusebox.xml file. The remaining searches are intended to support a

more object-oriented approach (CFCs-as-circuits) or a simple procedural approach (directoriesas-circuits). This is in line with Fusebox's goals of supporting a wide range of programming styles while not getting in the way of the programmer.

CFCs as Circuits

If Fusebox identifies a ColdFusion Component as a circuit, it expects to be able to call methods on that CFC corresponding to fuseactions within the specified circuit. If a request is made for alias.action and Fusebox determines that alias.cfc is the specified circuit, then the following method should exist in that CFC:

<cffunction name="action">
<cfargument name="myFusebox" />
<cfargument name="event" />
... perform the fuseaction ...
</cffunction>

The method may execute other fuseactions using the dynamic "do" operation on myFusebox and may store result data into the event object (which is an encapsulation of the Fusebox attributes scope). If a method named prefuseaction is present, it is called before each action method. If a method named postfuseaction is present, it is called after each action method. prefuseaction() and postfuseaction() methods share the same variables scope as the action method.

Results may be passed back via two mechanisms:

  • Using myFusebox.variables().key = value to assign directly into Fusebox's
common variables scope consider this to be the ?"old-school" procedural approach.

  • Using event.setValue("key",value) to assign into Fusebox's attributes scope,
which is wrapped in the event object . consider this to be the more modern, objectoriented

approach.

Directories as Circuits

If Fusebox identifies a directory as a circuit, it expects to find individual files within that directory corresponding to fuseactions within the specified circuit. If a request is made for alias.action and Fusebox determines that alias/ is the specified circuit, then one of the following files should exist in that directory:

  • action.xml
  • action.cfm
  • action.cfc

The behavior in each of these scenarios is described in the following sections.

CFML Templates as Fuseactions

A request for alias.action is resolved to the file action.cfm in the directory alias/. The behavior is as-if the following code existed in a circuit.xml file:

<fuseaction name="action">
<include template="action" />
</fuseaction>

In other words, the action.cfm file is included as a regular fuse file.

If a file named prefuseaction.cfm is present in the same directory, it is included before the action.cfm file. If a file named postfuseaction.cfm is present in the same directory, it is included after the action.cfm file.

CFCs as Fuseactions

A request for alias.action is resolved to the file action.cfc in the directory alias/. Fusebox treats the ColdFusion Component as a "command” object and the following method should exist

in that CFC:

<cffunction name="do">
<cfargument name="myFusebox" />
<cfargument name="event" />
... perform the fuseaction ...
</cffunction>

The method may execute other fuseactions – using the dynamic "do” operation on myFusebox(see below) – and may store result data into the event object (which is an encapsulation of the

Fusebox attributes scope). If a method named prefuseaction is present, it is called before the do() method. If a method named postfuseaction is present, it is called after the do method. prefuseaction() and

postfuseaction() methods share the same variables scope as the do() method.