Fusebox Plugins and XFA's for Beginners

So your curious to learn more on these things called Plugins, well lets take a look. The following consists of what files we needed to create to get it to work, what to put into those files, and How to properly use fuseactions to call a page.

If you are familiar with the <cfset> tag you should catch on to the following script pretty quick, its also a good way to start out using cfscript. What we are going to do now is create a plugin for our fusebox application. In the folder you extracted fusebox into you will see a sub folder called "Plugins" go ahead and open that bad boy up. If you open this folder you will find a text file, go ahead and delete it you don't need to be told that this folder is for plugins. Ok now back out of the folder and if it isn't already open, open up fusebox.xml again.

Scroll down the fusebox.xml file till you come to code that looks like this:

<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>

Now if you look at these tags you will get kind of a rough sense what they are. The preProcess one is things you want to run before the application starts to process. The preFuseaction is ran before the fuseaction happens. And the processError is sort of the catch all for errors. The others are outside the scope of these tutorials and basic user knowledge. I may fit them into later tutorials if I have the time. Anyway you now have the basic gist of these tags and what they mean, so what are they good for?

These tags are as good as the application.cfm file. They allow you control over how and when a script is run. Instead of huge long pages of complex cfif's and cfswitch tags and god only knows what else has come out of trying to get scripts to run only at certain times, you can now easily say, "Goodbye old clumsy pages hello little plugins!" With the power to run script before or after a page has loaded you finally have the ability to run complex scripts and get the web page to the user faster than before. Ok enough drooling over this concept lets see it in action.

Create a new page and name it plug_requestHandler.cfm save it inside your newly found plugins folder.

Now that it is saved lets put a little cfscript in there to handle a few things. I will show the cfscript and cfset way of writing the following code so those of you unfamiliar with cfscript can get a handle on it. Ok first the cfset tags:

<cfset request.dsn = "mydb">
<cfset request.images="images/">
<cfset request.firstname="myfirstname">

So now your plug_requestHandler.cfm file should look like this:

plug_requestHandler.cfm

<cfset request.dsn = "mydb">
<cfset request.images="images/">
<cfset request.firstname="myfirstname">

Now the cfscript way of writing the same script:

<cfscript>
request.dsn="mydb";
request.images="images/";
request.firstname="myfirstname";
</cfscript>

So if you do it this way your plug_requestHandler.cfm should look like this:

plug_requestHandler.cfm

<cfscript>
request.dsn="mydb";
request.images="images/";
request.firstname="myfirstname";
</cfscript>

Either way is fine, I just thought it was a great opportunity to introduce you to cfscript.

Ok save the file. Now go back to your Fusebox.xml file. Go down to the plugins and we are going to call the above script in the PreProcesstags. In between the PreProcess tags type this:

<plugin name="RequestHandler" template="plug_requestHandler.cfm"/>

So the script on the page should look like this:

Fusebox.xml

<plugins>
<phase name="preProcess">
<plugin name="RequestHandler" template="plug_requestHandler.cfm"/>
</phase>
<phase name="preFuseaction">

Ok now to see if this is working. Open up dsp_yourname.cfm and place the following script below the form.name script:

<cfoutput>#Request.firstname#</cfoutput>

Ok now lets call on the index.cfm file in our browser. You will be taken to the form and now type your name then click submit. If you typed it exactly as me you will see your first name then myfirstname after. So we now know that the plugin is working and we can call requests from anywhere in our application. Pretty cool huh? Ok I am a geek at heart I think its awesome. Now what if you want something like a pop up to happen after all the script is ran and the page is shown. A pop-up would be evil, but it is the best way to show you how to use your plugins and have control over how and when they are ran.

Create a new document called plug_mypopup.cfm and save it inside your plugins folder. Type in the following script: (NOTE: If you are unfamiliar with javascript don't worry so am I. But it is the easiest way to do this and it is purely for demo reasons you do not need to understand the script.)

<script language="JavaScript">
alert("this is a pop up message");
</script>

Then go to your fusebox.xml file and place this code between thepostPoccess tags:

<plugin name="Pop-up" template="plug_mypopup.cfm"/>

It should now look like this:

Fusebox.xml

</phase>
<phase name="postProcess">
<plugin name="Pop-up" template="plug_mypopup.cfm"/>
</phase>
<phase name="processError">

Ok now here comes the fun part testing our script. Close your browser. Now open you browser again and point it at the index.cfm page. You should get a pop up message that says, "this is a pop up message" and a button to click ok. If you notice that the script on the dsp_welcome page ran first. To further show this go ahead and click ok and type your name into the text box on your page. Your next page loads and you see your request feature and then the pop up message shows. Now you can see the possibilities of such a powerful feature. Ok now that we have played with plugins and you have an idea of how to use them and the awesome power they have lets go back to our plug_requestHandler.cfm page and tweak it a little.

So now its time to setup out Exit, In other words our exiting links on pages. How do you create an easy to use and control navigation system in fusebox. Also how you control things that you don't want others to see especially those pesky hackers that are after your valuable info.

Well that is easy you create a xfa! What you say? A xfa? Ok here it is: eXit Fuse Action. If you're letting out a big "Duh", its ok don't feel bad. I didn't know either when I first saw it. XFA's are a god send because now you don't need to type in the file names for things to work and you can use them in forms making it possible to re-use your forms and have multiple forms on a single page. It also makes links a breeze to fix or change. This is because they are handled by one file. You guessed it circuit.xml.cfm is the file that handles xfa's. Ok lets see them in action.

Type in the following code in the circuit.xml.cfm file between the the welcome fuseaction tags:

<xfa name="SubmitForm" value="main.DisplayName" />

So now your circuit.xml.cfm file should look like this:

<circuit access="public">

<fuseaction name="Welcome">
<xfa name="SubmitForm" value="main.DisplayName" />
<include template="qry_users.cfm" />
<include template="act_login.cfm" />
<include template="dsp_welcome.cfm" />
</fuseaction>

<fuseaction name="DisplayName">
<xfa name="Home" value="main.DisplayName" />
<include template="dsp_yourname.cfm" />
</fuseaction>

</circuit>

XFA's which are to utilize the same Circuit for the action as the one being called do not need the circuit defined in the value of the XFA (value="main.DisplayName"). By Default they will use the current fusebox (value="DisplayName"), this is also accessable via myfusebox.originalcircuit.

Notice we gave the XFA the name of "SubmitForm". Now go back to your dsp_welcome page. Edit the form's action value to the following:

<cfoutput>#myself#=#Xfa.SubmitForm#</cfoutput>

If you are wondering where the variable 'myself' came from, thats built into the Fusebox Core files, and configurable within the Fusebox.xml file.

So now your dsp_welcome page looks like this:

Dsp_welcome.cfm

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>Untitled Document</title>
</head>

<body>
<form action="<cfoutput>#myself#=#Xfa.SubmitForm#</cfoutput>" method="post">
<input name="Name" type="text"><input name="" type="submit" value="Submit">
</form>
</body>
</html>

Before you go and test it out though you may want to delete the postProcess action if you created it or you will be annoyed by your own pop-up message. You would do the same steps in creating a link to the home page. So lets create a link back to the home page inside the dsp_yourname.cfm file. It should look like this:

<a href="<cfoutput>#myself#=#Xfa.Home#</cfoutput>">Home</a>

Now open the circuit.xml.cfm file and add your new xfa to the fuseaction that will be calling it. I am not going to tell you which one, this you will have to figure out by trial and error. Once you have it working you can continue on with this tutorial. I suggest that you try to get it working before moving on.

Now just to recap again we have created a circuit called "main" and fuses called "welcome" and "Display Name". We have created XFA's and learned how to call scripts before and after a page loads. We've learned as well that all pages pass through the index.cfm page. So now that you have gotten your brain around that lets work on displays.