Fusebox Technical FAQ
What is a fuseaction?
A fuseaction is a request handler, usually for a public method. When a Circuit gets a request to perform some action, it receives the request in the form of a fuseaction. A fuseaction is passed or defined for every request the user makes to the application.
What is a circuit?
A circuit is a cohesive group of related fuseactions. A Fusebox application is made up of one or (more often) multiple circuits.
What is a fuse?
A fuse is an individual, atomic code file. Fuses are the most basic building block of a Fusebox application. When a fuseaction is passed to a circuit, one or more fuse files are called to actually fulfill the request. A fuse is always a private, so fuses are never called directly by a user making a request to a Fusebox application.
What are XFAs?
XFA stands for eXit FuseAction. XFAs are a powerful idea that compliments Fusebox. Instead of hard-coding the fuseactions, an XFA variable is used instead. The XFA variables are defined in the circuit.xml file. By using a variable to define the next fuseaction, code becomes more reusable. Also, it becomes possible to change, at runtime, what a given fuseaction will actually do.
Does Fusebox scale to large, enterprise-level applications?
Yes. One of the design goals of Fusebox was to minimize overhead and maximize performance and robustness without sacrificing functionality. Just like any enterprise-level application, a properly architected and coded Fusebox application, running on appropriate hardware, can scale to very large numbers of users.
What is MVC?
MVC stands for Model-View-Controller, and is a well established design pattern. It concerns itself with the overall architecture of an application and tries to provide a classification of the different kinds of objects that make up an application. In MVC, there are three types of objects: model objects, view objects, and controller objects. The controller receives a request from the user and determines how to process it. Model objects are then called to handle the individual processing chores. Finally, the view object displays the output to the user. MVC is used extensively in the Java world, and is gaining popularity among ColdFusion developers as a way to organize their applications.
I've heard of other frameworks called Mach-II and Model-Glue. What are they and how do they relate or compare to Fusebox?
Mach-II and Model-Glue are also frameworks for building web-based applications. However, both Mach-II and Model-Glue are completely object-oriented approaches to building ColdFusion applications. Both the framework code and the application code make heavy use of ColdFusion Components (CFCs). It is strongly recommended that before building either a Mach-II or Model-Glue application, a developer have a firm grasp of object-oriented programming. The Fusebox 4 and 5 core files do not require use of CFCs so the framework code is procedural rather than object-oriented. However, it is still possible (and in many ways advantageous) to use CFCs in your Fusebox applications.
Are Fusebox and Mach-II or Model-Glue competing frameworks?
Not really. They represent two different approaches to building an application. Both Mach-II and Model-Glue require an object-oriented approach to development. Fusebox does not require an object-oriented approach, but can support an OO approach if necessary.
I've built my first Fusebox 4 application. But now when I make changes to any of the XML files my changes are not used! It's like Fusebox is ignoring my changes. Why is this and how do I fix it?
Chances are your application is set to "production mode". In the fusebox.xml file there is a parameter for "mode". The mode can be set to various development modes or "production". The difference is that in development-full-load mode, the core files reparses the XML files only if they have changed and re-builds all the Fusebox memory structures on every request. Development-circuit-load, does not re-load the fusebox.xml file, doesn't re-build the Fusebox memory structures but does reload any circuit.xml files required by the current request. In production mode, after the first request the core files do not reparse or re-build anything. Obviously production mode is many times faster than either of the development modes. However, once production mode has been set, you must tell your application to reparse the XML to incorporate your changes (and this includes changing from production mode back to development mode). Luckily this is pretty easy to do. It's done using a URL with some special variables attached. By calling your application like this:index.cfm?fusebox.password=&fusebox.parse=true&fusebox.load=true&fusebox.execute=true you'll force the core files to reparse your XML and your changes will be incorporated. Note that by default fusebox.password is an empty string, but this can be set in the fusebox.xml file with the "password" parameter. If you've set your own password, you'll need to specify that password in the URL when you pass the "fusebox.password". For best results if you are moving from production mode to one of the development modes, make sure to delete all your parsed files in the parsed directory as well.
Do I need to have a circuit.xml.cfm file in the root folder of my Fusebox 4 application?
No, not unless you want to use the root folder as a circuit. Only folders you have set up as circuits in fusebox.xml.cfm need to contain a circuit.xml.cfm file.
Why do I get the message "You specified a Fuseaction of [Name of Fuseaction] which is not defined in Circuit [Name of Circuit]"? I swear the fuseaction is listed properly in the relevant circuit.xml file.
Validate your circuit.xml file. Erratic XML markup sometimes causes this error.
Can I locate the parsed and plugins folder outside the web root?
You can, but only if you move all the directories so that they stay relative to each other. The directories "fusebox5", "lexicon", "parsed" and "plugins" must stay at the same relative position to each other. If you move the files, make sure that your index file correctly finds the fusebox5 directory and the circuit definitions in the fusebox.xml file correctly find your circuits.
Is there a switch statement available in Fusebox.xml or Circuit.xml? I only see loops and if-thens.
No, there is no switch verb in the core files. However, there are lexicons which incorporate the switch grammar for Fusebox 5+.
How do I add comments to my circuit.xml.cfm files? If I use <!--- ---> I get an error.
Use XML comments which are the same as HTML comments and use 2 dashes instead of 3 for ColdFusion comments. <!-- My XML comment -->
Are there any reasons I might prefer Fusebox 3 to Fusebox 4 or Fusebox 5+(or prefer to stay with Fusebox 3 rather than 'upgrade')?
In most cases, no. Fusebox 5 has many advantages over Fusebox 3. However, a rewrite could be expensive, since only your Fusebox 3 fuses will be reused. The fbx_switch, fbx_circuits, and fbx_settings files must be converted into XML files. So converting an existing application that is seldom updated from Fusebox 3 to Fusebox 5 may not be worth the effort. For new development, however, Fusebox 5 is the recommended way to go.
I'm trying to use the tag in one of my circuits but keep getting an error which says "Error reading circuit.xml.cfm".
Check to see if the "url" attribute of your tag contains any ampersands (&). In XML ampersands have to be "escaped" to avoid confusion by changing them to "&" (without the quotes). Example: <relocate template="#myself#circuit.fuseaction&id=#id#" />
needs to be changed to:
<relocate template="#myself#circuit.fuseaction&id=#id#" />
What is the fusebox.init and why is it in some of the sample apps but not in the Core Files? Is it required?
The fusebox.init file was added in Fusebox 4.1. It is a "globals" file. It is included on every request, if it exists. It runs after the attributes are loaded, but before any fuseactions are run so you can do neat things with it like run security and change attributes.fuseaction for login. It's also a handy place to put your db settings. It's not "required" to run Fusebox, but it is part of the "official core." Note that the fusebox.init file replaces the need for using the old Globals plugin (although you can still use that w/ fusebox 4+ if you care to).