I work with Fusebox framework since its version 2. Now we are at version 5.51. I decided to write this tutorial to help some friends who haven’t got into Fusebox yet but are anxious to jump into the bandwagon, just don’t know how to start. I recommend Jeff Peter’s books on Fusebox for those who really want to take advantage of this framework:

MVC – Model View Controller

Before going into the framework, let’s talk a little about MVC (Model, View, Controller). For those who don’t know MVC, it is a method of separating the presentation, action and control layers of the application in order to achieve better and secure way of programming, and easier maintenance.

All external calls (from the web URL) are directed to the Control layer. Then the Control will decide which actions to take, like performing a query, a calculation, etc… That is done in the Model layer, which has no access from the outside world. Then the Control will submit the results to the View (presentation layer) which will assemble the contents to the public. Basically, all public link addresses to your website will be calling the Control layer. All your queries and action pages will be in the Model, and all your display pages will be in the View, easy to find and maintain.

Example: if you have to show a list of real estate properties, the Control will call a query in the Model to obtain the data and then call a display page in the View to show all the properties selected in the query.

Fusebox

Figure 1.1
Figure 1.1

Fusebox is a methodology for developing web applications. It protects your application by forcing all calls to be made to a single template: index.cfm, which acts as the hub where all connections are made. By passing the “fuseaction” attribute, you will tell the Fusebox framework what action you want to be executed.

So, with the analogy to the “electric fusebox”, the framework is divided into “circuits” and “fuses”. Your application folders are called “circuits” and the ColdFusion templates are the “fuses”.

In this tutorial we will be referencing the Fusebox 5.51 XML version, not the non-xml one (sort of OO). Let’s start by downloading the Fusebox 5.51 Core Files, select the first link: Official FB5.5.1/CFMX core files (v5.5.1).

Unzip the contents to a folder named “fusebox5” inside your web application root if you DO NOT have access to the ColdFusion administration site. Otherwise, extract the contents to a folder outside your web root and then map it as “/fusebox5”. Doing that, you will be able to have multiple websites using the same Fusebox core installation.

Your Fusebox core structure should be like Figure 1.1 side.

Figure 1.2
Figure 1.2

We are going to create a web application for a  store called FBTutorial. Here are the initial application requirements:

  • Home Page with News Articles
  • Contact Page – form
  • Products page – catalog
  • Shopping Cart
Figure 1.3
Figure 1.3

I know two ways of creating the MVC structure for a Fusebox application. One is most used by creating 3 folders: _model, _view and _controller (the underscores are for placing the folders on top of the other regular ones), and inside those folders we would put the Fusebox circuits.

I find that more complicated and less modular. Any maintenance you need to do, you will have to look at the subfolders inside other subfolders, etc… (figure 1.3)

If you want to turn a circuit into a module that could be copied to other application, the better approach should be creating the circuits first, and then inside each circuit you create the folders “model” and “view”, being the circuit root itself working as the “controller”.

So I chose the second structure by creating the circuit folders and

Figure 1.4
Figure 1.4

then their subfolders model and view (Figure 1.4).  Here is how we will create the application structure:

  • FBTutorial
    • circuits
      • forms
      • home
      • news
      • products
      • shopping
    • other folders…

Now, inside each circuit folder, we will create the folders “model” and “view“. You decide

Figure 1.5
Figure 1.5

if you want to prefix them with underscore “_”, since you will not have any other folder in the circuits.

After creating all the necessary folders, we need to create empty control files in each folder. Those files will be named “circuit.xml.cfm”, which are XML files but with the extention CFM so they cannot be read by the browser without being parsed by ColdFusion. Just create the empty files for now.

Figure 1.5 shows the new structure with the XML files.

Do not worry about the empty files, we will fill them in later.

Figure 1.6
Figure 1.6

I’m just preparing the application structure before starting coding.

Now, let’s create the Fusebox required and optional files on the application root.  Starting with the Application.cfc (capital “A”), fusebox.appinit.cfm, fusebox.init.cfm, fusebox.xml.cfm and index.cfm (create those empty files and we’ll work on them next. Your structure now should be like Figure 1.6.

Application Root

Let’s start now working on the Fusebox files on the application root. First of all, the Application.cfc component which is always the first to run on each request.
The basic methods in the Application.cfc component are:

  • onApplicationStart,
  • onApplicationEnd,
  • onSessionStart,
  • onSessionEnd,
  • onRequestStart

You may have additional methods like onRequestEnd, onError… but right now we are interested in the Fusebox method: onFuseboxApplicationStart. That method is called when the Fusebox application initiates. It replaces the template fusebox.appinit.cfm in the application root. So if you may decide to use this method instead of that template, then it’s one less file to maintain.

Here is our Application.cfc template:
{code type=xhtml}<cfcomponent extends=”fusebox5.Application” output=”false”>
<cfscript>
this.name = right(REReplace(expandPath(‘.’),'[^A-Za-z]’,”,’all’),64);
this.applicationTimeout = createTimeSpan(0,6,0,0);
this.sessionManagement = true;
this.sessionTimeout = createTimeSpan(0,0,30,0);
this.clientManagement = true;
this.mainDSN = “myDSN”;
this.webmasterEmail = “myEmail@myDomain.com”;
</cfscript>
<!— trap non-index.cfm requests – must be outside onXxxYyy() handlers —>
<cfif right(cgi.script_name, len(“index.cfm”)) neq “index.cfm” and
right(cgi.script_name, 3) neq “cfc”>
<cflocation url=”index.cfm” addtoken=”no” />
</cfif>
<cffunction name=”onApplicationStart” returntype=”boolean” output=”false”>
<cfreturn True>
</cffunction>
<cffunction name=”onApplicationEnd” output=”false”>
<cfargument name=”applicationScope” required=”true” />
</cffunction>
<cffunction name=”onSessionStart” output=”false”>
</cffunction>
<cffunction name=”onSessionEnd” output=”false”>
</cffunction>
<cffunction name=”onFuseboxApplicationStart”>
<cfset super.onFuseboxApplicationStart() />
<!— code formerly in fusebox.appinit.cfm —>
<cfif not structKeyExists(application,”mainDSN”)>
<cflock name=”mainDSN” type=”exclusive” timeout=”10″>
<cfset application.mainDSN = this.mainDSN />
</cflock>
</cfif>
</cffunction>
<cffunction name=”onRequestStart”>
<cfargument name=”targetPage” />
<cfscript>
super.onRequestStart(arguments.targetPage);
//code formerly in fusebox.init.cfm
self = myFusebox.getSelf();
myself = myFusebox.getMyself();
if (listFirst(CGI.SERVER_NAME, “.”) == “www”) {
FUSEBOX_PARAMETERS.mode = “production” ;
} else {
FUSEBOX_PARAMETERS.mode = “development-circuit-load” ;
}
// request scope
request.applicationName = this.name;
request.mainDSN = this.mainDSN;
request.webmasterEmail = this.webmasterEmail;
request.baseDir = GetDirectoryFromPath(GetBaseTemplatePath());
request.componentPath = “assets.components.”;
request.imagePath = “assets/images/”;
request.cssPath = “assets/css/”;
request.jsPath = “assets/js/”;
request.flashPath = “assets/multimedia/”;
request.videoPath = “assets/multimedia/”;
request.ppsPath = “assets/multimedia/”;
</cfscript>
</cffunction>
</cfcomponent>
{/code}

Now, here is the deal. Since the Fusebox core also has an Application.cfc with the same methods, we need to extend our Application.cfc to the Fusebox one and make use of the “call super” to invoke those methods first in order to use ours. On the first line, we extend the component. Remember to map /fusebox5 in your ColdFusion adminstration to the folder were you saved the core files.

{code type=xhtml}<cfcomponent extends=”fusebox5.Application” output=”false”>
{/code}

The method onFuseboxApplicationStart must have the call super:
{code type=xhtml}<cffunction name=”onFuseboxApplicationStart”>
<cfset super.onFuseboxApplicationStart() />
… … …
{/code}
onRequestStart should have also the call super:
{code type=xhtml}<cffunction name=”onRequestStart”>
<cfargument name=”targetPage” />
<cfscript>
super.onRequestStart(arguments.targetPage);
… … …
{/code}
Some code that was formerly in fusebox.init.cfm:
{code type=xhtml}self = myFusebox.getSelf();
myself = myFusebox.getMyself();
if (listFirst(CGI.SERVER_NAME, “.”) == “www”) {
FUSEBOX_PARAMETERS.mode = “production” ;
} else {
FUSEBOX_PARAMETERS.mode = “development-circuit-load” ;
}
{/code}

Fusebox.init.cfm

We basically wrote all the necessary code for starting with the Application.cfc, now let’s concentrate on the Fusebox template fusebox.init.cfm. It is included by the framework at the start of every request. It is included within a cfsilent tag so it cannot generate output. It is intended to be for per-request initialization and manipulation of the fuseaction variables.

You can set attributes.fuseaction, for example, to override the default fuseaction. Fusebox 5.1 and later – set variables implicitly from the Fusebox itself.

Could also modify the self location here:
{code type=xhtml}<cfset myFusebox.setSelf(“/myapp/start.cfm”) />
{/code}
For now, just write the following code in your fusebox.init.cfm template:
{code type=xhtml}<cfprocessingdirective suppresswhitespace=”true”>
<!— some future code here —>
</cfprocessingdirective>
{/code}

Index.cfm

The index.cfm template will have only one statement:
{code type=xhtml}<cfinclude template=”/fusebox5/fusebox5.cfm” />
{/code}
In a Fusebox application the index.cfm template has no use other than to include the framework.

Fusebox.xml.cfm

The last file on the application root we have to work on is the fusebox.xml.cfm, which is the file that controls all the fusebox circuits, parameters, classes, plugins and global actions.
In the “circuits” block we define the paths and aliases for the circuits. You may chose any name as an alias to a circuit, does not have to be the same name of the folder, you will see below that we are calling “cart” the circuit in the folder “shopping”.
The “parameters” block contains Fusebox default settings, and it is customizable.
Here is our fusebox.xml.cfm file:
{code type=xhtml}<?xml version=”1.0″ encoding=”UTF-8″?>
<!DOCTYPE fusebox>
<!–Example fusebox.xml control file. Shows how to define circuits, classes, parameters and global fuseactions. This is just a test namespace for the plugin custom attribute example –>
<fusebox xmlns:test=”test”>
<circuits>
<!– Home circuit –>
<circuit alias=”home” path=”circuits/home/” parent=”” />
<circuit alias=”mhome” path=”circuits/home/model/” parent=”home” />
<circuit alias=”vhome” path=”circuits/home/view/” parent=”home” />
<!– Forms circuit –>
<circuit alias=”forms” path=”circuits/forms/” parent=”home” />
<circuit alias=”mforms” path=”circuits/forms/model/” parent=”forms” />
<circuit alias=”vforms” path=”circuits/forms/view/” parent=”forms” />
<!– News circuit –>
<circuit alias=”news” path=”circuits/news/” parent=”home” />
<circuit alias=”mnews” path=”circuits/news/model/” parent=”news” />
<circuit alias=”vnews” path=”circuits/news/view/” parent=”news” />
<!– Products circuit –>
<circuit alias=”products” path=”circuits/products/” parent=”home”/>
<circuit alias=”mproducts” path=”circuits/products/model/” parent=”products” />
<circuit alias=”vproducts” path=”circuits/products/view/” parent=”products” />
<!– shopping circuit –>
<circuit alias=”cart” path=”circuits/shopping/” parent=”home” />
<circuit alias=”mcart” path=”circuits/shopping/model/” parent=”cart” />
<circuit alias=”vcart” path=”circuits/shopping/view/” parent=”cart” />
<!– Layout circuit –>
<circuit alias=”layout” path=”circuits/layout/” />
</circuits>
<classes>
</classes>
<parameters>
<parameter name=”defaultFuseaction” value=”home.main” />
<!– you may want to change this to development-full-load mode: –>
<parameter name=”mode” value=”development-full-load” />
<!– change this to something more secure: –>
<parameter name=”password” value=”” />
<parameter name=”strictMode” value=”true” />
<!– These are all default values that can be overridden:
<parameter name=”fuseactionVariable” value=”fuseaction” />
<parameter name=”precedenceFormOrUrl” value=”form” />
<parameter name=”scriptFileDelimiter” value=”cfm” />
<parameter name=”maskedFileDelimiters” value=”htm,cfm,cfml,php,php4,asp,aspx” />
<parameter name=”characterEncoding” value=”utf-8″ />
<paramater name=”strictMode” value=”false” />
<parameter name=”allowImplicitCircuits” value=”false” />
<parameter name=”debug” value=”false” /> –>
</parameters>
<globalfuseactions>
<preprocess>
</preprocess>
<postprocess>
</postprocess>
</globalfuseactions>
<plugins>
<phase name=”preProcess”>
</phase>
<phase name=”preFuseaction”>
</phase>
<phase name=”postFuseaction”>
</phase>
<phase name=”fuseactionException”>
</phase>
<phase name=”postProcess”>
</phase>
<phase name=”processError”>
</phase>
</plugins>
</fusebox>{/code}
We define the circuits in the “circuits” block by assigning an alias to the path. In the application we will call the index.cfm passing the circuit,fuse and fuseaction we want to execute. Example:

Figure 1.7
Figure 1.7

index.cfm?fuseaction=home.main
index.cfm?fuseaction=products.showProduct&productID=1234
index.cfm?fuseaction=cart.addToCart

With Fusebox, everything is assembled in the root. The index.cfm loads Fusebox and it prepares the request to be served without the customer seeing in which folders the templates are.
We added a circuit named “layout” which will handle all the layouts for our application. Since it is for the presentation layer, we do not have to create the “model” folder. Figure 1.7 shows an updated version of our structure.

Circuit.xml.cfm

Now we are going to look at the circuit.xml.cfm file placed in all circuits.
Let’s start with the “home” main circuit, the controller one” /circuits/home/circuit.xml.cfm:
For now we will not have any actions to call, just a display page to show the homepage, then our circuit.xml.cfm file will have the following code:
{code type=xhtml}<?xml version=”1.0″ encoding=”UTF-8″?>
<!– home –>
<circuit access=”public” xmlns:cf=”cf/”>
<fuseaction name=”main”>
<do action=”vhome.main” />
</fuseaction>
</circuit>
{/code}
You noticed that we here we are calling an action on another circuit, the “vhome”, in the “view” part of the MVC, to display the homepage. If we had to calculate anything or grab any information from a database in order to populate that homepage, then we would call the “model” layer before the “view”.

The call to “index.cfm?fuseaction=home.main” will get to this circuit which will call the “vhome.main” fuseaction in the “view” area. Subsequently that fuseaction, “vhome.main”, will include the template “dspMain.cfm” with the contents of the homepage, and then Fusebox will assemble the full page for ColdFusion to render to the browser. Note that the attribute “access” for this circuit is set to “public”. That means it can be accessed by the web browser, it is a public fuse.

Here is the circuit.xml.cfm file in the “view” area:
{code type=xhtml}<?xml version=”1.0″ encoding=”UTF-8″?>
<!DOCTYPE circuit>
<!– vhome –>
<circuit access=”internal” xmlns:cf=”cf/”>
<fuseaction name=”main”>
<include template=”dspMain.cfm” required=”true” />
</fuseaction>
</circuit>
{/code}
In this case, the “access” attribute is set to “internal” which means this circuit can be only called by another circuit, it will not respond to browser calls.

The fuseaction “main” will include the template dspMain.cfm.
Just for testing purpose, create the file dspMain.cfm with the following HTML code:
{code type=xhtml}<h1>Hello World</h1>{/code}

Now, let’s test the site. If you have ColdFusion Developer Edition installed in your machine, just browse to: “http://localhost/FBtutorial“. You do not have to specify any attributes, because the Fusebox configuration file (fusebox.xml.cfm) will take care of calling the default fuseaction “home.main”.
You should get the page “Hellow World”.

On the next part we will start handling layouts.

I hope you have liked this tutorial and please feel free to comment if you have questions.

Part 2

23 thoughts on “Fusebox 5.51 With MVC Tutorial Part 1

  1. Thanks to James Husum to point me an error on the Application.cfc, which I already corrected, on line 11 the close comment was HTML and not CFML and caused error.
    Here is his message:
    Greetings,

    I was looking at your post on the Fusebox MVC tutorial (http://ricardo.parente.us/2009/08/fusebox-5-51-with-mvc-tutorial-part-1/). On line 11 in the code for the Application.cfc template there is a problem if you try to run the code.

    You need to have a CF style closing comment tag(—>), instead of an HTML style (–>). At least when I was trying it out on my local system it threw an error.

    Hope this helps.

    James Husum
    RIAH Software
    http://www.riahsoftware.com/

  2. @Kevin
    Yes, I’m working on part 2 and also on a PDF file with the complete tutorial. I hope I can finish before end of September.
    Thanks for your comment.

  3. I followed your tutorial and thought I would mention that you should point out that the circuit.xml.cfm files cannot be empty for the hello world to work. At a minimum they needed an empty circuit so the xml could be interpretted correctly. I’ve ordered books by Jeff Peters to pick up on fine points, but hope you will continue your tutorials. The logic and organization to your approach is much better than others I have seen.

  4. @Kevin
    You’re right, I missed that point. The circuit.xml.cfm files must have the XML (at least with the empty circuit declaration). Thanks for your comments, I’ll definitely continue the tutorial. I’m currently working on the project http://ensina.me/coldfusion which is a translation of the ColdFusion Cookbook into Portuguese for the Brazilian CF Community. I’ll jump back into the tutorial just after that project.

  5. @David
    Yes, there is a part 2.
    I just put the link at the bottom of the article.
    Sorry for the inconvenience and thanks for reminding me.

  6. Ricardo…can you pls provide a download version of what you have built?

    I tried your approach, but its giving me error.
    Error says :

    “Error reading circuit.xml
    A problem was encountered while reading the circuit file circuit.xml.cfm for circuit forms. This is usually caused by unmatched XML tag-pairs. Close all XML tags explicitly or use the / (slash) short-cut. ”

    I am totally new to Fusebox and liked your approach of keeping model and view folder in each circuit.

    Thanks in advance

    Meghu

  7. Ricardo…
    I tried your approach, but its giving me error.
    Error says :

    Error reading circuit.xml
    A problem was encountered while reading the circuit file circuit.xml.cfm for circuit mhome. This is usually caused by unmatched XML tag-pairs. Close all XML tags explicitly or use the / (slash) short-cut.

    The error occurred in C:\ColdFusion9\wwwroot\fusebox5\fuseboxCircuit.cfc: line 173
    Called from C:\ColdFusion9\wwwroot\fusebox5\fuseboxCircuit.cfc: line 81
    Called from C:\ColdFusion9\wwwroot\fusebox5\fuseboxApplication.cfc: line 950
    Called from C:\ColdFusion9\wwwroot\fusebox5\fuseboxApplication.cfc: line 314
    Called from C:\ColdFusion9\wwwroot\fusebox5\fuseboxApplication.cfc: line 108
    Called from C:\ColdFusion9\wwwroot\fusebox5\Application.cfc: line 341
    Called from C:\ColdFusion9\wwwroot\fusebox5\Application.cfc: line 334
    Called from C:\ColdFusion9\wwwroot\fusebox5\Application.cfc: line 119
    Called from C:\ColdFusion9\wwwroot\fusebox5\Application.cfc: line 97
    Called from C:\ColdFusion9\wwwroot\FBTutorial\Application.cfc: line 40

    171 :
    175 :

    i downloaded your code that you give to meghu but is shows same above error. Please can you provide me solution for this error. very very thanks….

  8. @haroon,
    I just downloaded the sample code in the second part of this tutorial and it works fine.
    According to the error you pasted, it seems that you have some strange character in the XML file “circuit.xml.cfm” in the folder “circuits/home/model”. Maybe you got that when you copied the code from the blog. Sometimes the single quotes are showed as a special character.
    Try to download the code here: http://ricardo.parente.us/wp-content/uploads/2009/09/FBTutorial.zip
    Let me know if it works.
    Thanks.

  9. Can we use CFC’s with your configuration. I absolutely love how you use the circuit as the controller, that makes total sense to me.

  10. Also, how would we construct XFA’s, would you provide an example for form, link, and ? so I can wrap my brain around your concept?

  11. @Eric,
    Sure, you can use CFC’s.
    I usually create a folder ouside the “circuits” folder and call it “components”, where I put all global CFC’s that I can instantiate from any circuit. But there are other ways to use them, like together with the model circuit if it is an action CFC or with the view circuits if it generates any output.
    My approach is to set the path in the Application.cfc like:
    <cfset application.componentPath = “components.” />
    and in my code I instantiate it like:
    <cfscript>
    myObj = createObject(“component”, application.componentPath & “myComponent”).init();
    </cfscript>

    I hope this help you.
    Thanks.
    Ricardo

  12. @Eric,
    The XFA is used to allow you to maintain the logic of your code in the XML, so if you ever need to change the action of a form, or a link, you can do it without changing the code itself, but just changing the circuit.xml file.

    So, suppose you have a contact form that you call from your “contact” circuit:
    <fuseaction name=”contactUsForm”>
    <xfa name=”formSubmit” value=”cforms.contactUsAct” />
    <include template=”dspContactUsForm” required=”true” />
    </fuseaction>

    Then in your template dspContactUsForm.cfm you will write:
    <form name=”contactUs” action=”#myself##xfa.formSubmit# method=”post”>
    …..
    </form>

    If you ever need to change the action, just change the XFA in the circuit file.

    Best regards,
    Ricardo

  13. Ricardo, your explanation definitely helps and I am glad we can use CFC’s with your method which makes total sense in my brain.

    I appreciate your immediate feedback on both of my questions! It’s great to know we have community support. Your tutorials have greatly exceeded my expectations with the framework!

    From one developer to another, thank you!

  14. @Eric,
    You are using “#self#” instead of “#myself#”, I believe that’s the problem.
    self = “index.cfm”
    myself = “#self#?#methodvariable#=”
    (in your case myself = “index.cfm?fuseaction=”)

    Make a test page and do a <cfdump var=”#myfusebox#” /> in one of your templates, and you will see several variables that you can use too, like myFusebox.thisCircuit, myFusebox.thisFuseaction, etc.

    Thank you for your kind words. It’s a pleasure to help the developers community. I learn a lot from it, so I’m happy to pay forward the little I know.

    Best regards,
    Ricardo

  15. The part 2 of this tutorial is just having a heading and the smiley..Please provide the link to part 2

  16. Thanks for this, just in case someone else has dilufcfity. I had to enable relaying for it to work for me. To do this:1. Right click on Default SMTP Virtual Server’ in IIS admin, select Properties.2. Click Access tab, then Relay ‘3. Switch radio button to All except the list below’This should get it working, I used 127.0.0.1 as my mail server address in CF Admin.To debug watch the /Spool /Undelivr directories in CF, and check the mail.log.Enjoy.

Leave a Reply