Keeping It Together; The Directory Structure of the ColdFusion MX/HTML Pet Market
Hopefully by now many of you have had an opportunity to download and try out the ColdFusion MX/HTML version of the Pet Market Blueprint Application (if not, you can find it here). In my recent article, I discussed why we created the application and how you could use it to see design patterns that we implemented, illustrations of some best practices, object-inspired CFML coding, and much more. In this article and several other upcoming articles, we'll dig a bit deeper into the Pet Market Blueprint Application to explore exactly how it works and help you see how ColdFusion MX can work for your own HTML-based projects.
Using ColdFusion components (CFCs) allows developers to separate their application logic from their presentation tier. As you know, you write CFCs in separate physical files (with the .cfc extension) and call them from traditional ColdFusion templates (with the .cfm extension). This has led many developers to ask a lot of questions about directory structure, such as:
- Where should I put the files for my application?
- Should I have a separate folder for CFCs?
- How can I best make my application portable?
The HTML version of Pet Market built in ColdFusion MX offers an interesting approach to organizing the application directory that will help answer many of these questions. Notice, though, that I say this article "offers one approach." ColdFusion application development is extremely flexible (certainly compared to some other technologies that strictly dictate file locations). If you're building a new application, feel free to try out this approach and see if it works well for you. You're always free to try out other techniques.
The Pet Market application installation puts two files and three folders into the root petmarket folder (see Figure 1).
Figure 1. The root Pet Market directory structure.
A significant benefit of this approach is having the entire application stored under a single folder, in this case c:\petMarket. By using a custom tag path and web server virtual directory, you can store this single source of application materials anywhere on your file system. You make tasks, such as automated backups, application portability, and simpler navigation much more manageable.
The "database" folder needs little explanation. It contains a file-based database (Microsoft Access, in this case), but you may also store SQL scripts or other database-related files within it.
The "extensions" folder contains a "components" subfolder and a "customtags" subfolder. Map your ColdFusion custom tag path to this directory. With this technique, you organize all of the application's custom tags and components beneath a single directory and make them accessible to the ColdFusion application, yet they are outside of the webroot. This secures your extensions; this benefits you by preventing any web browsers from accessing the majority of your application logic.
Finally, the "wwwroot" folder is the folder you map as the web server's virtual directory and contains the images, CFML, and HTML pages for the application. The technique you use for setting up the virtual directory depends on which web server you are using. If you are using the ColdFusion MX built-in web server, refer to "Adding a Virtual Web Mapping" for instructions on creating a virtual directory.
That leaves two files, Application.cfm and onrequestend.cfm, in the root c:\petMarket folder. Why are these two files here, particularly when I just told you that the application's CFML pages all belong in the "wwwroot" folder? Remember that with ColdFusion MX, you can use your application logic for more than just HTML applications; SOAP Web Services and Flash Remoting, for example. By placing the Application.cfm one folder above the webroot, remote CFC calls will incorporate its code too. This allows important application-wide settings, such as the application's data source or authentication logic to be available to remotely called components (perhaps by a Flash MX application) and CFML pages alike. In the Pet Market application, the onrequestend.cfm file doesn't execute any code. It contains user session data, but comments it out. You can remove the comment tags for debugging purposes. Since onrequestend.cfm must be in the same directory as the Application.cfm page, it also resides in c"\petMarket".
We've found this general approach to organizing the files for the ColdFusion application simple and flexible. It keeps your components and custom tags outside of the webroot, allows you to move or back up your entire application easily, allows remote component calls to share application settings with the web-based application, and more.
Other Approaches
Another method for organizing components is based on a Java naming convention where you create a directory structure in reverse order of the domain name, application name, and so on. For example;
{customTagRoot}/com/petmarket/user.cfc
The fully qualified name for the component clearly reflects its relationship to a given application. In this example, the user component of the petmarket.com application is:
com.petmarket.user
This technique may be particularly helpful where multiple applications share the same server. Since it would not be unexpected to have a "user" component in more than one application, this helps to clarify that you are calling the "user" component in the petmarket application as opposed to another application's "user" component.
Some development methodologies, such as the Model View Controller (MVC) architecture may have other specific recommendations for component and application file locations. Whether you decide to try out the structure that was use in the ColdFusion MX HTML Pet Market Blueprint Application or another, all ColdFusion applications will benefit from incorporating ColdFusion components.
A Web Services Warning
You can see that there are many ways to organize elements of a ColdFusion MX application. While ColdFusion is fairly flexible in this regard, other technologies may not be so forgiving. Macromedia Chief Architect Sean Corfield brings up an excellent caveat in his blog regarding name restrictions for CFCs that other apps may consume as web services. He writes;
Let's consider what happens when ColdFusion MX compiles your code (to Java) to use with Axis (as a web service): if you have component.cfc in {CFMX}/wwwroot/path/name/ then it will be compiled to a Java class called 'component' which lives in a Java package called 'path.name'. That means that both your component name and your directory structure should be valid names in Java. In particular, that means that you cannot create a .cfc that is named after any Java keyword (e.g., default, package) and you cannot put components in directories who names begin digits or contain non-alphanumeric characters.
Consider items such as this when planning your applications. Be sure to read the documentation "Developing ColdFusion MX Applications with CFML," specifically chapter 11, "Building and Using ColdFusion Components." It describes how to use component packages and outlines the locations where you can save component files and the available accessibility options from each location.
In the next Pet Market article, I'll describe how we used CFCs as objects in the application to represent and perform all the logical tasks associated with customers, items, and shopping cart. Until then, I hope you continue to find the ColdFusion MX/HTML Pet Market Blueprint Application a helpful guide to the powers of application development with ColdFusion MX.
