TestBox BDD v2.1.0 and MockBox Released!

CommandBox, MockBox, News, Releases, TestBox

We are so excited to bring you TestBox 2.1.0 and MockBox 3.1.0!  These releases are minor releases of our libraries and include not only great features but a slew of fixes.  You can read all about the exciting features in our What's New Guide!  They have also been integrated with CommandBox, our new ColdFusion CLI and package manager, to allow you to download, install and even execute tests in the command line.  We have also made available our integration server builds which can also be installed via our CLI.

You can now do this to install TestBox or MockBox.

// install testbox
box install testbox

// install testbox bleeding edge
box install testbox-be

// install mockbox
box install mockbox

// Execute tests
box testbox run runner="runner path"

// Generate a bdd spec
box testbox create bdd MySpec


Release Notes

Bugs Fixed

  • [TESTBOX-96] - isEqual on Query fails when queries are equal
  • [TESTBOX-97] - equalize fails on struct/objects/arrays when null values exist within them
  • [TESTBOX-98] - Floating Point Number isEqual Fails
  • [TESTBOX-100] - Specs with the same name cause thread name exceptions when using async
  • [TESTBOX-101] - Download file has "samples" instead of "tests" directory
  • [TESTBOX-102] - tobe() cannot handle sparse arrays on Adobe CF
  • [TESTBOX-103] - xUnit compatibility CF9 broken due to isClosure() being utilized
  • [TESTBOX-105] - skip closures get more metadata arguments when being executed.
  • [TESTBOX-115] - testbox errors when using complete null support in railo


  • [TESTBOX-40] - Have debug() include information about where it came from
  • [TESTBOX-95] - remove extra whitespace in text reporter
  • [TESTBOX-110] - Remove CF7,8 incompatibilities
  • [TESTBOX-118] - ColdFusion 11 cfinclude compatibilities

New Feature

  • [TESTBOX-106] - BDD run() method now receive the TestResults argument for usage in their definitions.
  • [TESTBOX-107] - BDD runner and specs receive reference to the TestBox calling class via the run() method
  • [TESTBOX-108] - Update the apidocs with our new DocBox skin
  • [TESTBOX-109] - Debug labels and telemetry additions
  • [TESTBOX-112] - Add "top" attribute to debug method
  • [TESTBOX-114] - HTMLRunner add big request timeout setting to avoid server cut offs
  • [TESTBOX-116] - have expectations assertions return the expectation to allow chaining
  • [TESTBOX-117] - Simple reporter includes now a test bundle filter
  • [TESTBOX-119] - New lifecycle method: aroundEach() so you can do a full AOP advice on any spec




New Compatibility Module released to help get you on ColdBox 4.0

CommandBox, Modules, Releases

ColdBox 4.0 is now in Release Candidate and we're tightening down all the screws for the big release.  As 4.0 is a major release of the platform, we've taken the opportunity to really clean up the code, making changes and improvements where necessary.  This includes the exodus of 75% of ColdBox's core code into pluggable modules so you can truly pick and choose what parts of the framework you want.  Some methods such as getPlugin() and getColdBoxOCM() were also removed.  This has naturally modified the framework's API a bit and your 3.x ColdBox app might not run without some tweaking.  

We have a What's New doc as well as a Compatibility Guide for ColdBox 4.0 where we have tried to document any changes necessary to get your codebase switched over.  However, we realize that some of this may take time for you to refactor if you have a larger codebase and we don't want it to keep you from looking at ColdBox 4.0  

That's why I've created a compatibility module for ColdBox 3.x code bases to help them run on the new 4.0 version of the ColdBox platform.  We feel this is a  much better solution than littering the core codebase with additional settings and feature flags.  ColdBox is the only framework with a first-class modular architecture.  Mix that with the incredible extensibility options, and this module has be ability to alter just about anything it wants.  

Only install it if you need it, and remove it once you're finished refactoring your code to the 4.0 standards.  This isn't meant to be a permanent install-- it's just a stepping stone to help you get your codebase up and running until you have time to finish refactoring.  Do feel free to use it in production, though it comes with no warranties or guarantees.  Here's a list of the modifications this module will make to ColdBox 4.x to make it work like the 3.x versions.

Functions and behaviors restored

  • Original getModuleSettings() behavior
  • getPlugin() function
  • getMyPlugin() function
  • getColdBoxOCM() function
  • UDFLibraryFile setting
  • "model" convention for WireBox scan locations
  • coldbox.system.plugin base class

The following WireBox mapping DSL namespaces are restored

  • ocm
  • ocm:{keyName}
  • coldbox:plugin:{pluginName}
  • coldbox:myplugin:{pluginName}
  • coldbox:myplugin:{pluginName@moduleName}
  • coldbox:fwconfigbean
  • coldbox:configbean
  • coldbox:cacheManager
  • coldbox:mailsettingsbean (requires mailservices module)
  • coldbox:debuggerService (requires cbdebugger module)
  • coldbox:validationManager (requires validation module)

This module also comes packaged with all the original ColdBox 3.8.1 plugins, so you only need to install this module and you'll have it all back again.   If you need any of the functionality that was refactored into modules such as ORM, validation, or i18n, just install those modules.  

Known issues:

  • When this module loads, it will copy Plugin.cfc to the coldbox/system directory.  If you uninstall this module, it will not remove that file.
  • Plugins only work for the default convention location of "plugins". 
  • You will still need to change the Application.cfc to use coldbox.system.Bootstrap instead of coldbox.system.ColdBox.  There's really no way around that one.


The preferred way to install this module is via CommandBox because using a package manager is just so fast and easy.  If you don't have Command Box, grab it real quick from here.  Then CD to your site's web root and run the following:

CommandBox> install cbcompat

If you want to do an old-fashioned installation, just click the download link from ForgeBox, and uncompress the contents of the zip file into your app's modules directory.

If you have questions or suggestions, hit me up on the ColdBox list, or feel free to submit a pull request.

ColdBox 4.0 Release Candidate Avaialble


We've been hard at work on on ColdBox 4.0 ever since we announced the public roadmap back in February.  There has been two good rounds of feedback in our Alpha and Beta cycles and we are pleased to announce the general availability of our first release candidate for ColdBox 4.0.

ColdBox 4.0 is a major release of the software with a completely revamped core that's seen a complete modularization of 75% of of the features.  That means ColdBox is now leaner, faster, and more focused.  Don't worry, all your  favorite libraries are still available to you, but they've been moved to ForgeBox and you can install them easily with our new CLI and package manager CommandBox.

Please take ColdBox 4.0 out for a spin and kick the tires.  If  you're currently using an older version of ColdBox, start by reading our Compatibility Guide here:


You can also get a leg up on the long list of the new features on our What's New page here:


Once you're ready to give it a spin, download ColdBox 4.0 Release Candidate from the "Upcoming Release" portion of our download page:


Or better yet, fire up CommandBox, CD into your web root and run

install coldbox-be

And as usual, please report any issues or questions you have to our Google Group.



Thanks for making ColdBox Developers Week 2014 a success!

ColdBox Developer Week

As we're recovering from our third annual ColdBox Developers Week, we'd like to give a shout out of thanks to everyone who participated.  From our sponsors, to the speakers and the attendees; everyone helped play a part in making these 21 training sessions fun and informative.  We hope everyone had as much fun learning as we did putting this on.


Thanks to our sponsors, Ortus Solutions and Computer Know How, we had tons of prizes to give away. Here's a recap of the winners.  Congratulations!

Furthermore, we offered additional prizes to the first two people to submit new packages to ForgeBox-- CFML's newest and most comprehensive code repository.  The following two people stepped up:


The most common question I've gotten is, "Was this session recorded?"  The answer is, YES!  Every session including our special guest session by Gert Franz of Railo was recorded and is posted along with the slide decks over on the CBDW 2014 recording page.



Hopefully you came away from CBDW excited to try out some of the tooling you learned about.  We're here to help you with that.  Here's some links for you to get started:


Ortus Solutions spends a lot of time putting on free training for the CFML community.  If your company benefited from this free event, please consider donating back so we can do even more free stuff for the CF community.

Secure Donation via PayPal

CBDW Bonus Session with Gert Franz on the Future of Railo

ColdBox Developer Week

ColdBox Developers Week has been progressing along nicely with one great session after another.  We're excited to announce that we've finalized a special BONUS session presented by guest speaker Gert Franz!  Gert will be sharing about the exciting future of Railo including what we have to look forward to in Railo 5.  Railo is an open source CFML engine and if you're using it you'll want to come see what's in store.  But even if you're not a Railo user, you'll still want to see what great innovations are happening over in Switzerland that are driving the CFML community forward and keeping us relevant.

This extra session will begin 1 hour before the first slot Friday morning (the 26th) which is 8am Pacific time.  The bonus session will be held in the same Adobe Connect room which is located here:


We will record the session and post it to our recording page.  Please show up and join in the fun!

Announcing ColdBox Developer Week 2014

ColdBox Developer Week


We are pleased to announce that ColdBox Developers Week (CBDW) is back for the third year now.  CBDW is a full week of completely free webinars (4-a-day) put on by Team ColdBox and other smart ColdFusion bods from around the world.  We've got some great topics this year that will discuss NoSQL, ColdBox 4.0, ContentBox CMS, and our newest project: CommandBox.  Sign up and come to as many sessions as you like.  We'll also be recording every session as well for you to watch afterwards if you can't make it during the scheduled time.

So, here's the details.  CBDW will  be happening THIS month, September 22nd-26th.  There will be four sessions each day that week starting at 11am, 1pm, 3pm, and 5pm Central time.  Want to know what that is in your time zone?  Head over to our site where we have every time zone in the world including yours (based on your IP address).

But wait there's more!  As if the training itself isn't enough, we're going to sweeten the deal with some free giveaways.  During the last session of each day, we're going to randomly select a winner from the full list of registrants to get one of these (one prize per day):

  • $50 Amazon gift card
  • $50 Amazon gift card
  • Sublime Text license ($70 value)
  • DataBoss Standalone license ($149 value)
  • DataBoss Standalone license ($149 value)


A big thanks to our sponsors Ortus Solutions and Computer Know How for donating these prizes.


Register Today   View Schedule

ColdBox 4 & CommandBox Beta have arrived!

CommandBox, ForgeBox, News, Releases


After almost half a year worth of work, we are finally here, ColdBox 4 & CommandBox CLI Beta have arrived.  For those of you who don't know what CommandBox is, CommandBox is our very own ColdFusion (CFML) Command Line Interface, package manager, REPL and recipe runner.  It connects to our ForgeBox online community for package repositories, installation and tracking.  It also has a very extensible commands interface that allows any CFML developer to contribute commands into CommandBox.  It ships with tons of commands for Coldbox 4 integration as well as the other boxes.  Check out the product pagedocumentation and Command API docs as well.  You can also check out the intro video below:


ColdBox 4 Major Features

So what's going with ColdBox 4.  ColdBox 4 is a major release in our ColdBox Platform series and includes a new revamped MVC core, extreme focus on Modularity and all extra functionality has been refactored into ColdBox modules. We have pushed the modular architecture to 1st class citizen even in the core itself. There are several compatibility updates that you must do in order to upgrade your ColdBox 3.X applications to CodlBox 4 standards. You will notice that the source and download of ColdBox 4 has been reduced by almost 75% in size. This is now due to our modular approach were functionality can just be brought in dynamically via CommandBox.  This has in turn made our release the smallest, fastest and most flexible ever. For in-depth guide, check out the What's New with ColdBox 4.0.0 guide and our Compatibility Guide.  Here is a breakdown of the major updates for this release.


Converting Fusebox 5.1 Sample App to ColdBox MVC - Part 2

Sample Apps, Tips & Tricks, Tutorials, Walkthroughs

This is the second half of our two-part conversion of a FuseBox 5.1 sample app to ColdBox MVC.  If you haven't been following our blog series on converting your legacy FuseBox apps over to ColdBox MVC you may want to back up and read the previous post first..  In that post we took a look at the different files in each version of the app.  We talked about how each framework bootstraps itself up, as well as settings and circuits/handlers.  We'll pick up right were we left off in this post and finish off the code by looking at how we converted the views, models, and error handling.


ColdBox will automatically look for a view file named after your action in a folder named after your handler.  Of course, all this happens in our "/views" convention folder.  You are free to name your view files whatever you want though.  Just use the following code to tell the framework what view to include:

// Include /views/randomFolder/randomFile.cfm
event.setView( "randomFolder/randomFile" );

Our views are almost identical.  There are two main differences.  The first is that our views "get" data from the handler by accessing the readily-available rc (request collection) and prc (private request collection) scopes.  rc is used for any input from the user via FORM or URL scopes.  prc is for any other data the handler wants to pass along to the view.  The second is in how we build links.


<a href="#self##xfa.conform#">Return to Connect Form</a>


<a href="#event.buildLink( prc.xeh.conform )#">Return to Connect Form</a>

ColdBox gives you a nice helper method in the event object to build links for you.  It automatically handles HTTPS, the base domain, app mapping, and query string.  event.buildLink() can also generate SES URLs with no changes when you have it enabled.


ColdBox layouts are placed in a folder called /layouts by default and unless you've specified something else, will look for a file called Main.cfm.


			<link href="/includes/getmymail.css" rel="stylesheet" type="text/css" />

The renderView() call is where the output from the view will be placed.


Your models are your services, beans, and DAO that represent the business logic in your application.  In ColdBox, these go under a folder called /model.  I created a MailService.cfc which encapsulates getting a list of messages and getting a single message.  


component singleton {
	property name="attachmentPath" inject="coldbox:setting:attachmentPath";
	property name='sessionStorage' inject='coldbox:plugin:sessionStorage';
	function getAllMessages( required numeric start	) {
		// Get connection Info
		var connectionInfo = sessionStorage.getVar( 'connectionInfo' );
		return new pop().getHeaderOnly(
			server = connectionInfo.serverName,
			username = connectionInfo.userName,
			password = connectionInfo.password,
			port = connectionInfo.serverPort,
			maxrows = connectionInfo.msgsPerPage,
			startrow = arguments.start
	function getMessage( required string uid ) {
		// Get connection Info
		var connectionInfo = sessionStorage.getVar( 'connectionInfo' );
		return new pop().getAll(
			server = connectionInfo.serverName,
			username = connectionInfo.userName,
			password = connectionInfo.password,
			port = connectionInfo.serverPort,
			uid = arguments.uid,
			attachmentpath = attachmentPath,
			generateuniquefilenames = true

Note the singleton annotation at the top in the component definition.  This tells WireBox to only create one instance of this service that the entire application shares.  I'm also using properties to inject a reference to my attachmentPath setting as well as the sessionStorage plugin again.  No configuration is necessary for WireBox to find the MailService CFC since we've placed it in the /model convention folder.  Unfortunately, I found that Railo doesn't support the same script syntax for the CFPOP tag so I also created a RailoMailService.cfc file in the /model folder and created the following WireBox configuration file.


component extends='coldbox.system.ioc.config.Binder' {
	function configure() {		
		// Use this to detect the CFML engine
		var CFMLEngine = new coldbox.system.core.util.CFMLEngine(); 
		// Railo uses a different script syntax
		if( CFMLEngine.getEngine() == CFMLEngine.RAILO ) {
			// This will override the default MailService mappings
			map( 'MailService' ).to( 'model.RailoMailService' );		
		// No "else" needed for Adobe CF. WireBox will simply "find" the 
		// "MailService" CFC in the "/model" folder automatically.		

This file uses a utility built into ColdBox called CFMLEngine to detect the engine in use and conditionally overwrite the MailService mapping to point to the Railo version.

Error Handling

In the FuseBox code, there are try/catches around a lot of code in the "model" files.  If an error occurs, a custom error page is included.  

<cfpop  .../>
		<cfinclude template="../view/error/connectionError.cfm" />

What if an error occurs somewhere else in the request though?  What if you add new code and forget to wrap it in a try/catch.  Even worse, what if you decide to rename your error template after it's referenced everywhere?  In ColdBox, error handling is built in.  All of your code is run in a try/catch at the framework level, and there's a nice default error template that displays.  In your production settings though, you'll want to override this to a more secure page that doesn't divulge information with the customErrorTemplate setting.

customErrorTemplate = "includes/templates/oops_sorry.cfm"

You can read more about the exception handling provided to you in ColdBox here.


To see all the code, please visit this repo on GitHub: https://github.com/bdw429s/FuseBox-5.1-Sample-App-Conversion

This sample app was a little more involved than the last one, and hopefully everything makes sense even though I included a lot more code.  If clone the Git repo you can unzip the FuseBox code and open them side by side.  Please comment below if you have any questions or suggestions, and here's our list of handy resources:



Brad Wood Presenting on ColdBox to Chicagoland User Group 8/13 @ 6:30pm Central


This August 13th at 6:30 pm Brad Wood will be presenting an introduction to the ColdBox MVC Platform to the Chicagoland user group.  If you're in the area, please attend in person.  For everyone else, I'll be presenting via Adobe Connect and you can join the room to listen in.


Converting Fusebox 5.1 Sample App to ColdBox MVC

Sample Apps, Tips & Tricks, Training, Walkthroughs

Welcome back to our blog series on converting your legacy FuseBox apps over to ColdBox MVC.  In our last post we converted the sample app for FuseBox 3 to ColdBox.  In this post we'll be taking the FuseBox 5.1 sample app from fusebox.org and converting it over to ColdBox MVC.  This is a later version of FuseBox that relies on XML controllers so it may be a bit more familiar.  Let's get started!

To run the FuseBox sample app, I downloaded the FuseBox 5.1 core files from fusebox.org.  I had issues getting the code to run on Railo 4.2 due to component creation paths and relative file directories not agreeing with the framework so I switched over to ColdFusion 9.  The ColdBox code, however, will run on CF9+ or Railo.  I had to put in a some code to handle Adobe and Railo's different script implementations, but I'll cover that later.


This sample app is called "Get My Mail' and is a simple POP3 client that will list out all the messages in your inbox.  It only has three screens-- the connection information form, the E-mail list, and viewing a single message.  To use the app, you'll need to have the server and login info for a POP3 server handy.  I'll also note that I wrote the ColdBox code all in CFScript except for views and layouts, of course.  This is simply my preference.  You are free to use tags with the ColdBox Platform.  

Here's a screenshot of the files in the Fusebox and ColdBox code side-by-side. There are fewer ColdBox files, but not quite as few as the image might imply.  Several of the files on the FuseBox side are auto-generated or empty.  I'll cover each of them as we go.

FuseBox 5.1 has no inherent MVC patterns per se, but this sample app was structured with MVC in mind which help the conversion.  The controller and model folders are basically FuseBox circuits that roughly represent those breakdowns.  The first thing you might notice is that ColdBox has NO XML! We believe CFML programmers should use what they're most familiar with to describe their app-- CFML! The parsed folder in FuseBox is where .cfm files are automatically generated by the framework from the XML controllers.  Since ColdBox has you write your code in CFML, there's no need for an equivalent.  You'll also notice that the FuseBox "models" are just .cfm files.  I went ahead to moved the equivalent code into an actual CFC in the ColdBox example.  

circuit.dtd and fusebox.dtd are just the XML definition for each of the circuits and the fusebox.xml file.  Naturally there is no equivalent file in ColdBox.  If you want to know what options you have in a ColdBox handler or config file, the easiest thing to do would be look in the docs, or use one of our application templates as an example. Handler Docs  Config Docs

fusebox.init.cfm is included at the start of each FuseBox request.  One way to do that in ColdBox would be to register a requestStartHandler setting in /config/ColdBox.cfc to run before every request.  Another way would be to register a preProcess interceptor.  Since the fusebox.init.cfm file in this sample app doesn't do anything, I didn't bother creating an equivalent in the ColdBox app.

fusebox.appinit.cfm is included every time the framework reloads.  Again, this can be easily duplicated in ColdBox by registering an applicationStartHandler in the config file.  There are also several interception points you can listen to as well.  

Core Framework

The FuseBox framework is self-contained within the fusebox5 folder.  The ColdBox framework is in the coldbox folder.  The easiest place for the coldbox folder to live is in your web root so CF will automatically resolve CFC paths that start with "coldbox" there.  For the security-minded, you can also move the folder elsewhere and create a server or app-specific mapping that points to it. This is especially handy if you have multiple ColdBox site and want to only maintain one copy of the framework.


ColdBox bootstraps itself up by being the super class to the Application.cfc and leeching off the application and request lifecycle methods within.  

component extends='coldbox.system.Coldbox' {
	this.name = 'FuseBoxSampleConversion';
	this.sessionmanagement = "true";

FuseBox on the other hand has a bit of code in the index.cfm file that invokes the framework.  It's worth noting the ColdBox app has an index.cfm, but is a blank placeholder just there to satisfy the CF engine.

<cfinclude template="fusebox5/fusebox5.cfm" />

The FuseBox app has a CFApplication tag in the index.cfm, but since the ColdBox app uses Application.cfc, that information is stored there.  If you ever need to add methods to Application.cfc, make sure you continue to call the super-scoped method as well.  If you want to use an app-specific mapping for "/coldbox", you'll need to use our non-inheritance template.  Read more about this here.


The Fusebox app uses a fusebox.xml.cfm file that contains settings for the app.  In ColdBox, we have a "/config" convention folder where we place all our configuration.  The ColdBox.cfc file contains general configuration for the app.  The WireBox.cfc file is optional but we used it to map a special model for Railo that I'll talk about under Models.  The only requirements of /config/ColdBox.cfc is that it contains a method called configure() and defines a variable called coldbox.appName.  There are a number of optional settings you can define here as well additional methods for environment control that override settings for you automatically on your development or staging servers.  You can read about this here.


<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE fusebox SYSTEM "fusebox.dtd">
		<circuit alias="m" path="model" />
		<circuit alias="v" path="view"/>
		<circuit alias="mail" path="controller"/>
		<parameter name="fuseactionVariable" value="view" />
		<parameter name="defaultFuseaction"  value="mail.home" />
		<parameter name="precedenceFormOrUrl" value="form"/>
		<parameter name="debug" value="true"/>
		<parameter name="mode" value="development-full-load"/>
		<parameter name="password" value=""/>
		<parameter name="parseWithComments" value="true" />
		<parameter name="conditionalParse" value="true" />
		<parameter name="scriptlanguage"  value="cfmx" />
		<parameter name="scriptFileDelimiter" value="cfm"/>
		<parameter name="maskedFileDelimiters" value="htm,cfm,cfml,php,php4,asp,aspx"/>
		<parameter name="characterEncoding" value="utf-8"/>

		<appinit />
			<do action="m.setup"/>
		<postprocess />



component {
	function configure(){	
		coldbox = {
			appName 			= "getMyMail",
			reinitPassword			= "",
			defaultEvent			= "mail.home",
			handlersIndexAutoReload	        = true,
			debugMode			= true
		settings = {
			attachmentPath = expandPath('/attachments/')

In fusebox.xml.cfm, the <circuits> defines the main areas of the application: "m" (model), "v" (views), and "mail" (controller).  ColdBox handles each of these by convention so there's not need for configuration.  The ColdBox models will all go in the "/model" folder, the views in the "/views" folder, and the controllers in the "/handlers" folder.

The defaultFuseaction setting is done in ColdBox with the defaultEvent setting.  I've created a "mail" handler with a "home" action, so the value is still "mail.home".  The debug setting becomes debugMode and pretty much as the same purpose.  Additional framework-specific debugging information is appended to the end of every request.  Password becomes reinitPassword and is required to reload the application from the URL with ?fwreinit=password  (or ?fwreinit=1 if no password is set).  On your production servers you'll want to specify a password to use in the URL so only you can reload your site.  Mode set to development-full-load is partially covered by handlersIndexAutoReload which reloads the handlers on each request.  The rest of the settings don't apply to ColdBox or don't appear to be used.

The <globalfuseactions> and <preprocess> tags specify a fuseaction that is run before each request.  This can be done with a requestStartHandler setting in /config/ColdBox.cfc or a preProcess interceptor.  In this app, there is only one handler, so I put that logic in a preHandler method in my mail handler which the framework automatically runs before each action in mail.  You'll see I also created a setting for the location of the attachments folder which I'll inject into my model later.

Circuits and Handlers

Fusebox breaks a site up into circuits, and ColdBox breaks it up via handlers. Circuits are divided into fuseactions, and handlers, are divided into actions.  Instead of using an XMl file to define this, ColdBox handlers are defined by convention by a CFC in your /handlers directory. The name of the CFC determines the name of the handler.  Actions are simply methods in your CFC, and the names of the methods are the names of the actions.  ColdBox also allows for very powerful routes to be defined ad hoc by you to make up nice descriptive URLs that don't have to match your file/method names.  Read more about that here.

The Fusebox site has circuits called "m" and "v" but ColdBox treats models and views as first-class conventions we'll cover shortly.  


<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE circuit SYSTEM "../circuit.dtd">
<!-- Controller Circuit -->
<circuit access="public">


component {
	property name='sessionStorage' inject='coldbox:plugin:sessionStorage';
	property name='mailService' inject='MailService';



Our circuit definition is an XML file, but our handler is just a CFC.  The name of the handler is derived from the file name by default.  The properties in the CFC represent other objects that the code in the handler is dependant upon.  When WireBox creates the handler, it will inspect it for any properties containing an inject attribute and inject a reference to them in the variables scope (by default) using the name specified in the name attribute.  coldbox:plugin:sessionStorage refers to the sessionStorage plugin which is a wrapper for the session scope.  If you want to use the session scope directly, there's NOTHING STOPPING YOU!  However, there are benefits to abstracting it.  Namely, encapsulating external dependencies, being able to change where the storage plugin points easily (client, cookie, etc) and the ability to mock the session scope access in a unit test.  MailService by default will load the MailService.cfc file in our /models directory.  


<fuseaction name="setupXfa">
	<set name="xfa.conform" value="mail.connectform" />
	<set name="xfa.msglist" value="mail.list" />
	<set name="xfa.msgdetail" value="mail.showmessage" />


	<!-- This could be a <do /> or an include, but the verbs keep it all right here, easy to see. -->
	<if condition="myFusebox.thisFuseaction IS 'connectform'">
		<true />
			<if condition="structKeyExists(session,'connectionInfo') AND structCount(session.connectionInfo) GT 0">
					<relocate xfa="conform" />


// Runs before every action
function preHandler( event, action, eventArguments ) {
	var prc = event.getCollection( private=true );
	// Exit event handlers
	prc.xeh = {}; 
	prc.xeh.conform = 'mail.connectform';
	prc.xeh.conformSave = 'mail.connectformSave';
	prc.xeh.msglist = 'mail.list';
	prc.xeh.msgdetail = 'mail.showmessage';
	// If they're on any action OTHER than the connection form and there isn't cached connection info...
	if(  arguments.action != 'connectform' && arguments.action != 'connectformSave' 
		&& !sessionStorage.exists( 'connectionInfo' ) ) {
		// Send them back to the connection form
		setnextEvent( prc.xeh.conform );

Here we're combining both setupXfa fuseaction in the m circuit as well as the <prefusionaction> tag in the mail circuit into the preHandler method of our mail handler.  preHandler is a special method name and will be run by convention before any other action in that handler.  Xfa stands for "exit fuseaction" and is basically a list of outgoing paths that the user can navigate away with.  Typically, I see this as needless bit of misdirection, but I copied it for old time's sake in a struct called xeh or "exit event handler".  The condition statement in the XML file is a clumsy mix of CFML and XML that we replaced in our handler as a concise bit of pure code.  Basically, if you're hitting any page other than the connection form and you don't have connection details in your session, redirect back to the session form.


<fuseaction name="home">
	<do action="list" />


// Default event, just redirects to list.
function home( event, rc, prc ){
	setNextEvent( prc.xeh.msglist );

Here's the home fuseaction and action.  All it does is redirect to the list action.  Generally this things falls in my "needless misdirection" category as we might as well have just set the default event to mail.list and been done with it.  Nevertheless, I included the equivalent in the ColdBox code.


<fuseaction name="connectform">
	<do action="v.connectform" />


<cfparam name="form.serverName" default="" />
<cfparam name="form.serverPort" default="110" />
<cfparam name="form.userName" default="" />
<cfparam name="form.password" default="" />
<cfparam name="form.msgsPerPage" default="30" />
<cfif structKeyExists(session,'connectionInfo') AND structCount(session.connectionInfo) GT 0>
	<cfset form.serverName = session.connectionInfo.serverName>
	<cfset form.serverPort = session.connectionInfo.serverPort>
	<cfset form.userName = session.connectionInfo.userName>
	<cfset form.password = session.connectionInfo.password>
	<cfset form.msgsPerPage = session.connectionInfo.msgsPerPage>


function connectform( event, rc, prc ){
	// default values
	rc.serverName = '';
	rc.serverPort = '110';
	rc.userName = '';
	rc.password = '';
	rc.msgsPerPage = '30';

	// Overwrite with stored values if they exist
	if( sessionStorage.exists( 'connectionInfo' ) ) {
		structAppend( rc, sessionStorage.getVar( 'connectionInfo' ) );

I didn't agree with the defaulting of variables in the view, so I moved them into the handler since that's where it feels like they belong.  The reason why I don't need to set the view in my action is because I have placed by view file in the appropriate place with the correct name to be automatically run by convention.  The FuseBox app ran the code to save the form on every request but I chose to create an additional connectFormSave action to do that.  


<fuseaction name="list">
	<set name="attributes.start" value="1" overwrite="false" />
	<set name="attributes.listVarName" value="qMailList" />
	<do action="m.getListOfEmails" />
	<do action="v.listmail" />


function list( event, rc, prc ){
	// Param start to 1
	event.paramValue( 'start', 1 );
	// The view needs this for previous/next links
	prc.msgsPerPage = sessionStorage.getVar( 'connectionInfo' ).msgsPerPage;
	// Get E-mails
	prc.emails = mailService.getAllMessages( rc.start );			

And here's our list action.  You can see the set tag for attributes.start is replaced with event.paramValue().  We don't need to be as explicit about the name of the variable we're passing to the view.  We just place the results of our service call into the prc scope (private request collection) and it will automatically be available in the view.  Again, our view will be called by convention.  

I won't show the remainder of the handler since it's pretty well covered already.  You can check out the code in the repo to read the entire file yourself.

But wait, there's more!

We've split this sample app conversion into two halves so you have time to soak each part in.  Here's the other half where we cover views, models, and error handling.  And of course, you can see all the completed code here on GitHub: https://github.com/bdw429s/FuseBox-5.1-Sample-App-Conversion  

Please comment below if you have any questions or suggestions, and as usual, here's our list of handy resources:




Recent Entries

Entry Archives


Training Events

ColdBox CFML Jobs

ColdBox Book