Using ColdFusion in a Fusebox Application

For someone learning Fusebox from scratch it takes some time before knowing how it works, although it is quite simple to use. At least I have been in this situation recently.

Fusebox is a web application management framework using xml files to setup rules for loading the application. it allows you to control the loading of different pages or modules in a transparent way for the user of the web application.

Naming conventions : to keep order and control in the application it is recommendable to prefix files used in the application in order to separate display, query and action functionality. So you can use "qry_"("qry_getAllUsers.cfm") for all queries to database, all data display files prefixed with "dsp_"("dsp_loginFrame.cfm"), all action files with "act_"("act_validateUser.cfm"), etc. The Fusebox core files will all preserve their prefix "fbx_"("fbx_switch.cfm").

For a Fusebox application to function, the mandatory core files need to be placed in the root folder of the web application. These are :

1. fbx_circuit.cfm file, where all the circuits of the application are defined, meaning they are mapped to the existing directories.

   i.e. <cfset fusebox.circuits.home="Homepage">

   <cfset fusebox.circuits.Import=fusebox.circuits.home & "/Import"> , where the import application is placed in the Import directory.

2. fbx_settings.cfm: here default settings are placed, using cfset,cfinclude template defaults, that load each time a page is loaded through the central “fusebox” – “index.cfm“, set herein :

   <cfset request.app=structNew()>

   <cfset request.app.mainDSN="database_name">

   <cfset request.app.self="index.cfm">

   the database is then referred by the variable set here "request.app.mainDSN" and the default page loaded every time is index.cfm, the “fusebox” from which all the “fuses”(actions) are loaded. This fusebox is further referred as "request.app.self". If you want to load a certain action to be executed each time this index.cfm is loaded you can place a

   <cfinclude template="Import\act_checkSession.cfm"> in this file of general settings. General variable declarations are also placed here, like session variables : <cfparam name="session.user_id" default="">

3. fbx_switch.cfm: this file contains the actual switch with all the actions defined for the circuit, it uses a <cfswitch expression= "#fusebox.fuseaction#"> tag with a series of <cfcase value="action_name"> tags where actions or queries are executed in the order placed there :

   <cfcase value="showLogin">
<cfset readonly = false>
<cfset XFA.submit = "login.searchUser">
<cfinclude template="dsp_loginForm.cfm">
</cfcase>

Steps for creating a fusebox application

Because all application actions and files are loaded through the central “fusebox” called for instance index.cfm (this is placed in the fbx_settings.cfm file in the root: <cfset request.app.self="index.cfm">, the fbx_circuit.cfm and the fbx_settings.cfm files need to be adapted to point to the desired files when the page is loaded.

1. define all circuits where actions are to be executed in the root fbx_circuit.cfm file,
2. the next file to edit is fbx_settings.cfm where kind of global variables and templates are set. Here you can set session variables using cfset, include templates to be loaded each time a page is requested through the index.cfm and all sort of validations that are needed when files are loaded through the central index.cfm.
3. for each of the circuits defined in the fbx_circuits.cfm root file there is a need of a fbx_switch.cfm file where all actions for that circuit are defined. There is a <cfswitch> tag with all possible <cfcase> branches that can be accessed in the respective circuit. For each value of cfcase , i.e. <cfcase value="showLogin"> variables can be set, files included, data tested in that particular order in which they are presented.

   i.e.

   <cfset XFA.submit = "login.nextStep">
<cfinclude template="dsp_loginStep4.cfm">

   means :

   “assign the exit variable XFA.submit the value of <cfcase value="nextStep"> in the fbx_switch.cfm file of the circuit ‘login’, then display the file ‘dsp_loginStep4.cfm‘, that includes a form, with an action “#XFA.submit#” , where this variable is replaced at runtime with the value set herein, that is, going to the next step in login or doing whatever is declared in the login circuit fbx_switch.cfm file for the <cfcase value= "nextStep"></cfcase>“.

Every action is controlled by the fbx_switch.cfm file in each circuit directory.

Tips :

1. Reusing Code : In order to reuse code, use the exit fuseactions variables, XFA, is a way to re-use code for different actions. Instead of hard-coding the action of a submit form to loading another file, you can set a variable XFA with the action “submit” in the respective cfcase of the circuit’s fbx_switch.cfm file. The value of this “XFA.submit” can then be changed in other actions, in the respective forms remaining only the reference to it.
2. Validating Forms with JavaScript and Using a Different Submit Action for a Form: When submitting a form validation may be required for the fields in the forms and at the same time the submit action must be set at runtime with the appropriate XFA variable . This can be solved including the JavaScript for validation in the onClick event of the submit button/image and keeping the form action=” #XFA.submit#”. The JavaScript should return true if validation is ok and false if this is not the case.

More tips coming soon.