Sunday, June 22, 2008

CFCs in Fusebox

Ok, so it’s been a while since the last fusebox tutorial and I figured enough time has passed since you began working with fusebox and you should be feeling fairly confident by now with it. I let some time lapse for several reasons, first and foremost I’ve been busy, second cfc’s in fusebox are rather complex thing to get into. It takes some understanding of how fusebox works before you can dive into cfcs.

Anyway, I’ve gotten a few responses as to what I should do to display the use of cfcs in fusebox, the majority were rather complex and would require a mountain worth of explaining. I decided to go with a simple application just because of the complexity of calling cfcs and for the widest possible understanding from everyone. You can easily build your own complex applications once you have the basics.

Ok so to begin download the sample app I have. I have not added anything to it that is covered here, but it has the basic setup of the fusebox and circuits. Unzip it to a site in your wwwroot folder. Once that is finished we can begin.

Ok, so first off let’s talk a bit about fusebox and how it calls cfcs. Fusebox reads and calls cfcs as a java class. No worries if you have no idea what that are, you don’t really need to understand java classes to work with cfcs.

Ok first off open the fusebox.xml file. Within the first couple of lines you will see an opening and closing tag named “classes”. In-between those two lines add the following code:

<class alias="testClass" type="component" classpath="yoursite.cfc.test" />

Ok I highlighted “yoursite” for a very good reason and here it is. For those of you using a developing server if inside your wwwroot folder you have a folder for a site named something like www.mycoolsite.com you are going to get an error when you create the dot path. I suggest making a completely new site with no dots anywhere in it’s name. For example “testingsite” NOT “testingsie.com”. If you insist on using your dot riddled folder you can declare a class path in your cf admin panel to the cfc folder. I am not going to explain that, you can find information in the tech notes and on macromedia if you decide to go that path. For those of you uploading to your own hosted site. You do not need to name your site. Chances are your host has already added your site to a class path if not you can ask them to. So you would just need a dot path to the cfc from root. IE (cfc.test). Please do not email with questions about this. I do not have access to your server you are using so I wouldn’t be able to tell you anything different than I have here.

Ok that warning out of the way what did we just do. We created a class and named it “testClass” we told it that it is a component. (The other option I believe is webservice, but I have never had a need for this.) And told it where to find our cfc.

Save and open the circuit.xml.cfm file under the folder “main”.

Again copy the code below to the fuseaction called “testcfc” making sure you place it above the included page.

<instantiate object="application.test" class="test" arguments="id" />
<invoke object="application.test" methodcall="testFun(#url.id#)" returnvariable="myResult" />

So what did we do here. First off you can set all the classes in the world in your fusebox.xml file and they would just sit there doing nothing without that first line above. All classes you set will need to be instantiated to be used. The object attribute sets the class in a variable that can be used application wide. Hence the “application” prefix. The class attribute says what class to give this “application” variable to. And here is the tricky part. You must pass any and all arguments that are in your cfc in the arguments attribute. Delimit them with a comma. In our cfc we are about to make we are going to have a cfarguement of “ID” so we declare that here.

The next line is just like a cfinvoke tag. We tell it that we want to invoke the object “application.test” that we just set above it and the method in which to use in our cfc. The method is the same as the cffunction name. In this case we have a cffunction method called “testFun”. We also included the ID argument within the brackets. In this case it is our url variable which we are using as our ID. Then we want to name the variable we would like to use once our cfc has processed. Which we ae just going to use the same variable that is passed back to us from the cfc called “myResult”.

Ok hard part over. Now lets make our cfc.

Here’s the code to do that.

<cfcomponent>
<cffunction name="testFun" access="public" returntype="string">
<cfargument name="ID" type="string" required="yes">
<cfset myResult="Today is: #DateFormat(Now(),"MM/DD/YYYY")#">
<cfreturn myResult>
</cffunction>
</cfcomponent>

Notice that the cfargument is required. It doesn’t have to be, but since we are passing it we will require it. Then we do a little code telling it what to do. And Return the results. I am not going into detail here, because I am assuming that if you are doing this tutorial you have some knowledge of cfcs.

Go ahead and test our your app by opening your index.cfm file into your browser. Click on the available link and you will see the cfc in action. If you get an error message check the path to your cfc in your fusebox.xml file. Otherwise it should work. Well it is that simple.

The FuseBox Organization believes it has devised new methods of ColdFusion coding that will allow CF to cure acne, heal canker sores, and most importantly prevent hair loss... The FuseBox Organization invites the CF development community to examine and try these standards. Suggestions are always welcome. These papers are specific to Allaire's ColdFusion, although we've found that because of the advent of WDDX it would be possible to very easily integrate a ColdFusion "Fusebox" application with another application written using a different web application server (such as ASP or Perl). Similar standards would need to be created in those languages. If anyone is interested in doing so, please contact me directly, I'm pretty interested in doing this also, but don't have the expertise many other web application languages.

The Fusebox Model
Fusebox applications are modeled around an electrical Fusebox in a House. For example, the electrical circuit for your kitchen is separated from your bathrooms and also separated from your living room. In the end, your house has electricity, to the common family they never notices that the electricity is really separated. When little joey decides it would be funny to put a fork in the electrical socket in the kitchen and he blows out the fuse. So the power goes out in the kitchen but it doesn't go out in the living room. This is similar to a software program, when a user does something that the developer wasn't expecting them to do the program throws an error. With Fusebox we separate each application from the other application's in the home thus allowing circuits to be blown without taking out ALL the power in the home application.
There are two types of applications in a large scale Fusebox application.
Circuit Application - If you've ever written a Fusebox application before you've probably written a Circuit application. This generally consists of a single directory of files (although it doesn't have to be limited to this). A circuit application generally does a few related tasks. An example is the eBags Search engine: http://www.ebags.com/search/ This search engine has multiple Fuseactions but it's main purpose is to help the user find the product they're looking for. Another example is the eBags Testimonials: http://www.ebags.com/info/testimonials/index.cfm This application allows users to view,add,edit,delete testimonials (depending on the user's security level)
Home Application - This is the overall application, it is made up many circuit applications that are tied together with an interface. The common user does not realize they are using a circuit applications they are under the impression that they are using the Home application. An example of a Home application is http://www.ebags.com. The entire site is made up of many many circuit applications that do various specific tasks such as searching, information, product details, purchasing etc. Although to the common user whether they are searching for luggage, or checking they are still in the home. This is similar to a real life home. Whether a person plugs a television into an outlet in the kitchen or in the living room, they still get power, because they are in their home. (assuming they paid the power bill :). It is important to realize that circuit applications may contain bugs in them.... but if they do, it is possible to remove them from the Home application without bringing the rest of the Home application down. It is also possible to go the other direction. When a new Circuit is added to the Home application it can be added without affecting the other circuit applications.
Because web sites are no longer static it is important to be able to add new features or remove old features from the site without affecting the entire site. This method of building your large scale applications will prove to be very helpful when it comes time to upgrade the application.
How to tie Circuit Applications together with the Home Application
The Home application is made up of many Circuit applications so when writing a large scale application it's important to be able to tie everything together. The Home application is nothing more than a concept it is the result of multiple circuit applications. You can think of the Home application as a directory structure on your CF server. By putting all of your circuit applications in the same root directory that entire directory structure could make up the Home application. The root directory of your Home application will contain the app_globals.cfm file. This file will be included in all app_locals.cfm files which are in every circuit application.
The root directory of your Home application may contain a circuit application itself. If you take a look at: http://www.ebags.com you will notice that a few of the links go to: http://www.ebags.com/index.cfm?..... This is a circuit application that is in the root directory. These tasks that may be not fit in any of your other circuit applications.
Once you've set up your directory structure that will be able to handle multiple circuit applications. You will eventually need to link your many circuit applications together. This can be done so by using the different types of links that is described in Technique 7 Use the universal format as much as possible (i.e. point links and forms to: index.cfm). There will be cases that you cannot use the universal format such as when building menus, I recommend using the absolute format (i.e. /directoryname/index.cfm) in your menus. The reason for this is that it will allow you to use the same menu on multiple circuit applications while still having the links in tact.

No comments: