Fusebox

Fusebox Organization

Writing applications within a multi person team can be difficult. Sharing applications between two teams can become even more difficult. Effectively sharing applications with 30,000 other developers such as with the ColdFusion® community is almost impossible... unless everyone adheres to standards for writing these shared applications. The Fusebox Organization has been assembled to create these standards.

This paper will give specification recommendations to the FuseBox organization for determining how FuseBox applications and databases should be designed. The paper is split up into three recommendations:

• File structures
• Code design
• Database design.

Example Web Application
Before looking at what the recommendations are, it is important to examine how a web application works. Let's look at a quick case of a User named: 'Steve Nelson' logging into an application called: 'Intraville'. This will help us analyze, in a very basic way, the grand scheme of what is happening behind the scenes of an application. Intraville is an Internal Intranet application for Monticello Systems, Inc.

"Steve walks up to his computer, turns it on and opens up Netscape. (This is beginning of cycle 1) Because he has a default URL set in his Netscape Navigator when Netscape loads up, it obtains 'http://www.intraville.com'. Intraville is a secured application, since Steve has yet to enter his name and address, the CF server kicks him to a login screen. (End of cycle 1, beginning cycle 2) Steve then enters his username and password, clicks the OK button and the security module allows him to move into the application (end of cycle 2); these cycles continue throughout Intraville."

After analyzing a CF web application, one will notice that it consists of a series of cycles. These cycles have a distinct similarity. Let's look at these cycles:

To the common user:

1) Send a URL with or without variables attached to the server
2) Black box (something happens at the server)
3) Display the output to the user

To the FuseBox programmer:

1) Send a request (URL with or without variables attached) to the server
2) From the variables, determine what should be done
3) Black Box part 1: If some variable is incorrect, display an error message, and make the user enter the correct information
4) Black Box part 2: Add/Modify/Delete data. This data can be from a database or any other datasource such as the file system. It does not matter.
5) Black Box part 3: Determine what should be displayed. Sometimes queries need to be run to obtain the most recent data changes, such as a select query from a database or a directory query from the Server file system, etc.
6) Display the output

Now that we have a basic understanding of how just about any web application works, let's take a look at how we use this knowledge to build an application. These next sections are current recommendations for Fusebox standards.

Fusebox Application Files
Since the purpose of writing FuseBox applications is to share applications among the possible 30,000+ ColdFusion developers, it's important to realize that not all applications look and feel the same. Two applications that may do the exact same thing look completely different to the user. Because of this, FuseBox applications must not force the user to accept the look and feel the original developer gave the application. It will be important that future developers be able to modify FuseBox applications to fit in with the look and feel with existing applications they are plugging into. Therefore, the Display sections of FuseBox applications must be open code. The display sections should not affect how the application works; they should simply affect what the user will see after the application has made any changes to the data.

The layout of FuseBox applications is as follows:

1)A FuseBox Application will consist of seven types of files:

1. Application.cfm - This file contains global variables.
2. Index.cfm - This file handles the inclusion of what action to take: example tags: cfinclude, cfmodule, CFML no HTML
3. dsp_[filename].cfm - These files handle the display of information: example tags: cfoutput, forms, CFML and HTML
4. act_[filename].cfm - These files handle actions. Generally changing data example tags: cfquery-inserts, cfquery-updates, cfquery-deletes, cffile, cfmail, cfhttp etc. CFML no HTML
5. err_[filename].cfm - These files handle errors. These error modules will generally happen before an action so that server side data verification can be done. CFML and HTML
6. App_[filename].cfm - These are the files that are application-specific. Sometimes queries need to be done that connect other databases. CFML no HTML
7. Default.cfm - This is an required file. If a Fusebox application can be a standalone application then this file will be the first file the user will see if they come to the index.cfm file without any outside variables. Otherwise, this is the default page when an error occurs such as when a user has entered an invalid attribute for the FROMTEMPLATE and FUSEACTION attributes. This file cannot contain references to form, URL, cookie, session, application or client variables. CFML and HTML

Each of the dsp_, act_, err_, app_ and default.cfm files must all point back to an Index.cfm, i.e., if this file contained an HTML form, the action of this form would be <form action="index.cfm">, or, if this file contains a link to the application, the link must point to index.cfm, ie <a href="index.cfm">blah blah</a>

Each of the dsp_, act_, err_, app_, default.cfm files which points back to an Index.cfm file must state which file it came from. This is done through a variable called FromTemplate. This variable may be passed through either form or URL variables. I.e., if the XYZ_[filename].cfm file contained an HTML form, the form would contain the hidden form field <input type=hidden name="FromTemplate" value="XYZ_[filename]">; if the XYZ_[filename].cfm file did not contain a form but contained an HREF link or a CFLOCATION link, the link must also follow this <a href="index.cfm?fromtemplate=XYZ_[filename]>My link</a> or <cflocation url="index.cfm?fromtemplate=XYZ_[filename]>.

Because additional direction must sometimes be given to the index.cfm, a second variable should be sent through all URL and Form fields when needed. It is called FuseAction. This variable is passed much like the FromTemplate variable, but doesn't have to reference the template name. Instead, it is a descriptive action your index.cfm file is to take. For example, in one template page you could have three different links. Depending on which link is clicked on, different templates are to be called. By only having the FromTemplate variable, there is no way to specify what action is to be taken. With the FuseAction variable, you can give the index.cfm the direction it needs. Below is an example of three links from the default.cfm page. Each link will need to go to a different template and through different act_ files.

<a href="index.cfm?FromTemplate=default&FuseAction=ADD">
    Add a User</a>
<a href="index.cfm?FromTemplate=default&FuseAction=Modify">
    Modify an Existing User</a>
<a href="index.cfm?FromTemplate=default&FuseAction=Delete">
    Delete a User</a>

Index.cfm files must manage the CF files (the inclusion of templates). Index.cfm will first check to see where the user came from (i.e., FromTemplate variable), and then, depending on where the user came from, determine what action must be performed (i.e., what template to run, <cfmodule template="XYZ_[filename].cfm">). If the application can be a standalone application and, if the "FromTemplate" parameter does not exist, the Index.cfm files must display the "default.cfm" template. This template must not require outside variables.

Ultimately, the index.cfm file relies on CFIF statements for the direction to each of the template pages. There are two specific IF statements that should be utilized within each index.cfm page so that the correct template is always called. The first has already been discussed. It is the first statement used to check for the existence of the FromTemplate variable. If the variable does not exist, the user is sent to the default.cfm display page. There is another instance, however, where a mistake can be made and the page may display nothing as a result. A final CFELSE statement will catch any link to the index.cfm page that sends an invalid FromTemplate value. Essentially, while developing the site or if a user alters the value of the FromTemplate variable, the index.cfm page will continue without including any templates. By using a final CFELSE statement, a default page may be specified for that instance. This can be a special dsp_ page notifying the user of the error, or just a cfinclude to the default.cfm page. Remember to use CFEXIT after the final dsp_ template within each CFIF section. See the example below for an illustration of the index.cfm file as discussed so far.

A simple example of the index.cfm page (without error checking)

<cfif NOT IsDefined("FromTemplate")>
    <!--- check for the FromTemplate var --->
   <cfmodule template="default.cfm"> 
        <!---if fromTempalte doesn't exist, show the default page --->
   <cfexit>
<cfelseif FromTemplate is "default"> 
    <!--- if they just came from the default page --->
   <cfif FuseAction is "ADD"> 
        <!--- if the link they clicked on was to run the Add page --->
     <cfmodule template="err_addtoApp.cfm">
        ;<!--- check for errors --->
     <cfmodule template="dsp_addtoApp.cfm">
        <!--- display the file --->
     <cfexit>
  <cfelseif FuseAction is "modify"> 
        <!--- Check to see if the link was to go to the modify page --->
     <cfmodule template="err_modifyApp.cfm"> 
        <!--- check for errors --->
     <cfmodule template="act_modifyApp.cfm">
        <!--- process any actions to the db/file system/whatever--->
     <cfmodule template="dsp_modifyApp.cfm"> 
        <!--- display the file --->
     <cfexit>
  <cfelseIf FuseAction is "delete>
     <cfmodule template="err_deleteApp.cfm">
        ;<!--- check for errors --->
     < cfmodule template="act_deleteApp.cfm">
        <!--- process any actions to the db/filesystem/whatever --->
     <cfmodule template="dsp_deleteApp.cfm">
        <!--- display the file --->
     <cfexit>  
   <cfelse>
     <cfinclude template="default.cfm"> 
        <!--- If the value of FuseAction is invalid go here ---> 
   </cfif>
<cfelseif FromTemplate is "dsp_addtoApp"> 
    <!--- if they just came from the addToApp display file --->
   <cfif FuseAction is "BackToMain"> 
        <!--- if the link directs them back to home --->
     <cfinclude template="default.cfm">
        <!--- display the default page --->
     <cfexit>
   <cfelseif FuseAction is "GoToNewPage">
        <!--- if the link directs them somewhere else --->
     <cfmodule template="dsp_newpage.cfm">
        <!--- display a new page  --->
     <cfexit> 
   </cfif>
<cfelse>
   <cfinclude template="default.cfm"> 
        <!--- If the value of FromTemplate is invalid go here --->
   <cfexit>
</cfif>

Why is this a good method to use for FuseBox applications?

1. Not all web applications look the same. This method of file management allows original developers and future developers of an application to change the look and feel of an application without changing the way an application works.
2. By forcing all links and actions to go to a single file, redirection errors will not occur. 4.0 browsers 'automagically' remember sites which you have already visited (Steve Nelson hates this magical feature). If the 4.0 browser enters in a file which requires a form variable to complete the process, it will generate an error. By using the index.cfm method if the formtemplate variable does not exist (this means other form variables also do not exist), it will send then user to the default template or generate an error when necessary.
3. Linking FuseBox applications into other Fusebox applications will be greatly simplified. If the developer does not want to change the look and feel of the FuseBox applications, he/she may simply create a link to the index.cfm file.
4. Adding new "modules" to FuseBox applications will be standardized. A new "Fromtemplate" cfif statement will be added to the index.cfm file and the new XYZ_[filename].cfm files will be added to the server. This allows multiple file modules to be added to any application.
5. When a Search Engine spiders a Fusebox site, the spiders will only be able to link to the main 'entrance' file into the application. It is a common problem for a search engine to link to a ColdFusion file that requires a form variable or a session variable that won't exist if your user comes from an outside source such as a Search Engine. By forcing the user to go through a common index.cfm file, that file will be able to verify that the user has all the necessary variables to continue onto the next page.

Fusebox File Contents
Application.cfm - This file contains global variables. When an application is dependant on outside variables, these variables will be checked for in this file.

Index.cfm - This file handles the inclusion of what action to take. If the FROMTEMPLATE variable does not exist, it will send the user to default.cfm using the cfinclude tag, then cfabort, so it does not run any other modules. If the FROMTEMPLATE exists, it will search where the user is coming from by doing a CFIF statement around the FROMTEMPLATE required variable. Once it knows where the user is coming from, it will know what code to use to manage what action should be taken. Although the FuseAction variable is not required, it may be used within the FromTemplate variable to further determine which action is to be taken. Generally, but certainly not always, when a user comes from a dsp_ file, these modules will then be included in this order:

1. Check for errors in the variables the user passed in (err_[filename].cfm)
2. Run any application-specific queries that may need to get outside data (app_[filename].cfm)
3. Modify the data specific to this fusebox application (act_[filename].cfm)
4. Display the results to the user (dsp_[filename].cfm)

err_[filename].cfm - These files handle errors on the server side. Since it is usually important in most applications to make sure the user enters valid information before processing the action, this file is where the application will check for these errors. These files will contain only server-side error checking, since javascript is displayed to the browser; javascript error checking will occur in the dsp_ files. These files will only contain CFML and not HTML. They will return error variables that the dsp_ files will check for and abort if these errors occur.

act_[filename].cfm - These files handle actions. Actions may be anything from changing data in a database such as inserting, deleting and updating information in the database, or an action may deal with sending/receiving an email or modifying a file. This file will contain CFML but will not contain any HTML, because this file is for managing actions and not displaying information to the user.

App_[filename].cfm - These are the files that are application-specific. Since Fusebox applications are designed to work with any other Fusebox application, they will need to connect to these other applications. These files will contain the code that is required to do this. Usually, these files will contain queries from databases that are not defined in the Fusebox application. Since all Fusebox database structures will look the same, there will not be a problem connecting to these other databases.

dsp_[filename].cfm - These files handle the display of information to the user. These files do not change any data; they are allowed to select data. These files may contain both CFML and HTML. If the user is requested to do some action such as click on a link or enter information into a form, the link or the action of the form must point to the "index.cfm". It is required that either an URL or a hidden form variable named FROMTEMPLATE be in this file. The reason for this is that it tells the index.cfm file where the user just came from which assists the index.cfm file in determining what to do. These files will be integrated with the err_ files and will check for error variables that the err_ templates may have returned. If the err_ files returned an error variable, the dsp_ files will display the error and abort processing, requesting that the user re-enter their information.

Default.cfm - This is an optional file. Fusebox applications will either be standalone applications or they will require input from some other application. If a Fusebox application can be a standalone application, this file will be the first the user will see if they come to the index.cfm file with any outside variables. This file cannot contain references to form, URL, cookie, session, application or client variables. CFML and HTML

FuseBox Database Design
Databases are a major part of any application. Since the purpose of FuseBox applications is to make applications talk to each other, it is important that not just the code but also the databases talk to each other.

FuseBox applications are meant to be a section of an overall application. The reason we want to create "FuseBox" applications is so when we need to write a very common section of an application, we do not write this code over and over. An application delivered to a different team or developer, therefore, will most likely not cover all the same bases that the developers may need. Because of this FuseBox tables will most likely never have ALL the fields that an application needs. The FuseBox standards need to be built around this. What this means is that, in general, FuseBox tables will create a one-to-one or one-to-many relationship with another table in your application. This is not required but, unless the FuseBox table contains all the fields necessary for your application, another table with the remaining application specific data will be needed.

ColdFusion 3 allows developers to reuse sections of code by creating "custom tags". These tags can be used by multiple applications when placed in the /customtags directory or when called directly. In a similar way, it is important that the FuseBox standards for databases allow multiple applications to use the same database without stepping on the other application's toes.

Creating a standard naming convention for table names is crucial so that they will never conflict with other applications and table names. Each table name should go by the standard of TableName_FuseBoxIDNumber, where the FuseBoxIDNumber is unique and assigned by FuseBox itself.

FuseBox standards have not been created to force developers to choose a specific database (i.e., SQL Server) so we have to build FuseBox databases to the lowest common denominator. Because of this, we need to consider field types; it is important that we do not use field types that exist in one database but do not exist in another database. More importantly, because FuseBox applications will be used by MANY people, they will need to be able to move data from one database to the next smoothly. The initial field type that should be placed on the NOT TO BE USED list is the "Autonumber" field or perhaps better known as "Identity field".

This may sound like it will cause a problem for many developers because using an Identity field is very commonly used for creating the table's Primary Key (PK). The following recommendations will solve that problem.

It is important that tables be able to talk to each other. The way tables talk to each other is through Primary Key-Foreign Key relationships. Because this is the way related tables talk to each other, FuseBox applications need to standardize on a field type for Primary and Foreign Key fields. It is recommended that FuseBox applications standardize on the "integer" field. FuseBox applications will need to deal with the auto-incrementing at the application level as opposed to at the database level (the way an Identity field works). Here is an example:

<!--- This amount of code creates the Identity value 
    on the application side. --->
<cftransaction>
<cfquery name="GetMax" datasource="#DSN#">
	select max(Primarykeyfield) as Max
		from MyTable
</cfquery>
<cfif GetMax.RecordCount is 0>
	<cfset NextID = 1>
<cfelse>
	<cfset NextID = #GetMax.Max# + 1>
</cfif>
<!--- now you can insert that number into the database --->
<cfquery name="InsertNow" datasource="#DSN#">
Insert Into MyTable
(primaryKeyName, Whatever)
Values (#NextID#, '#Whatever#')
</cfquery>
</cftransaction>

The above amount of code is how to recreate the auto-incrementing field at the application level as opposed to on the database side. This allows FuseBox databases to be database-independent by using a number field as our primary keys and allows FuseBox applications to define the datatype of all FuseBox Primary Keys.

Notice the use of the <cftransaction> tag. Because there are two separate queries (one to gather the ID, the other to insert the new record and correct ID), it is possible that more than one person can be given the same GetMax.Max number from the GetMax query. This would then attempt to insert a non-unique number as the primary key. Using <cftransaction></cftransaction> wrapped around the two queries will force CF to lock out the database while both queries are run. This eliminates the potential problem of a non-unique PK.

Now that the datatype has been determined for Primary Keys, let's look at how FuseBox tables will be related. The ways tables are related are through Foreign Keys. We discussed above that the purposes of FuseBox applications are basically to reuse code AND DATABASES. That means that FuseBox tables need to support multiple applications without each application stepping on the other applications' toes. For better reference, here is an example of possible uses for FuseBox applications. The FuseBox standard needs to compensate for the problem in this example.

Application1: Allaire Forums
Application2: Intraville Banners

Both of these applications require the use of files being uploaded from the user's computer to the server. Allaire Forums uses these uploaded files as attachments to messages; Intraville Banners uses these uploaded files as banners.

FuseBox Upload will have a table called "Uploads".

Allaire Forums will connect these uploaded files to a table called "Messages".
Intraville Banners will connect these uploaded files to a table called "Banners".

The Messages table uses an incrementing (at the application level) number field as its primary Key.
The Banners table also uses an incrementing (at the application level) number field as its primary Key.

If this uploads application were only meant to be used by one application, we could use the following structure for the "Uploads" table:

Upload_id (PK) (integer)
-------------------
Fuse_ID (FK) (integer)
Field1
Field2
fieldN

Now, the problem with this structure for multiple applications sharing this table is that, if a record exists in the Allaire Forums table: Messages_FID499 that has a primary key value of, say, 1599 and the Intraville Banners table Banners_FID510 also has a record with a primary key value of 1599, the database will not be able to tell these different applications apart.

What is needed is a way for tables that will be connected to multiple applications have the ability to differentiate between applications. What is recommended is that the FuseBox standard create a foreign key of not one field but two fields. The first field will state what FuseBox application the record deals with and the second field deals with the record in this foreign table. For example:

Upload_id (PK) (integer)
-------------------
FuseBox_ID (FK) (integer)
Fuse_ID (FK) (integer)
Field1
Field2
fieldN

What will the FuseBox_ID be?
The FuseBox_ID will be a foreign key to a lookup table that will store the information about the application it is connecting to. It isn't necessary that this lookup table even exists; it will be more for the developer to reference information about how this FuseBox table is connecting to another table. Here is an example of useful information that the developer may need to know about the connecting table:

FuseBox_ID (PK) (integer)
----------------------
FuseBox_Name
Database
Table
PrimaryKeyField

This table does not need to exist. The reason for having this table at all is to differentiate between different FuseBox applications.

Looking at the example again, you will notice that the problem is now solved. If the Attachments table has a record of 1599, and the Banners table has a record of 1599 these two records in the Uploads table will be differentiated because this additional Foreign Key field in the Uploads table states to which application each of these 1599 records belongs.

Conclusions
If the ColdFusion community set and adhered to standards for integrating multiple applications, ColdFusion would be boosted into the next level as a real programming language. The ideas above are simply recommendations for the Fusebox Organization to discuss and change to create full standards for creating Fusebox applications.

Additional Information
The FuseBox web site can be found at http://www.fusebox.org. Available on the Website are links to the forum, a contact list of interested FuseBox parties, sample FuseBox applications, additional information about the FuseBox organization, logs of all ICQ meetings and the latest version of the FuseBox specifications.