1
2
3
4
5
6

<cfsavecontent variable="jQueryInit">
     <script type="text/javascript" language="javascript"
         src="/javascript/jquery-1.3.2.min.js"></script>
</cfsavecontent>
 
<cfhtmlhead text="#jQueryInit#" />

This worked perfectly fine for a while, right up until the point where we had two views in the same request that needed jQuery. If you put the above code in each of the view pages, then only some of your jQuery plugins work because the jQuery javascript file was getting loaded and instantiated multiple times–wiping out everything that had been configured previously.

The natural first “fix” for this problem was to only include the above code in the view that would be used first on the page. While that would work in theory, it seriously breaks the notion of encapsulation that we’re trying to achieve by separating all these views into individual files. Essentially, you could only ever use a view reliably on one page because you never knew if jQuery had been loaded or not.

I had started to contemplate building some kind of custom listener object and accompanying view to do be able to manage this problem when I remembered reading about the HTMLHelperProperty CFC included in MachII 1.8. After doing some reading, I realized that the solution to my problem was already built right into MachII.

The HTMLHelperProperty is designed to be a “holding place” of sorts for anything that you need to dynamically add to the section as you progress through the various steps configured by your for the requested event. It allows you to call different functions to add javascript files, css files, and meta properties to the “pile” of things that will be inserted into the section just before the request ends. For example, to include the jQuery library that we need from the above example, all you have to do is add this bit of code:

1

<cfset getProperty("html").addJavascript("jquery-1.3.2.min.js") />

The best part is, you can add that same line to EVERY view that needs jQuery and the HTMLHelperProperty CFC will only add it to the tag once. Yep, you read that right! It intelligently manages duplicate additions so you don’t wind up clobbering your javascript objects with multiple invocations like we talked about above.

Now, the HTMLHelperProperty CFC isn’t confined to doing javascript files. It also can be used to manage CSS files. Say we have a view that needs to use the DataTables and FancyBox plugins. Each of those plugins ships with a CSS file that it needs to make things look right. That’s no problem either, you can pass in a comma-delimited list of javascript and CSS files (or pass in an array of values as well) like this (extra line breaks added for readability–you’ll not want to use them in your code):

1
2
3
4
5
6
7
8
9

<cfset getProperty("html").addJavascript("
     jquery-1.3.2.min.js, 
     jquery.dataTables.min.js, 
     jquery.fancybox-1.2.1.js
     ") />
<cfset getProperty("html").addStylesheet("
     datatables.css, 
     jquery.fancybox.css
     ") />

The other use is to dynamically add tags to your document. These are pretty self-explanatory so I’m not going to go into them here, but refer you to the wiki page instead.

You may have noticed that there I’ve not included any file system paths to the javascript and CSS files in the examples above. When you configure the property in your MachII config file, you can set the default “home” directories for your javascript and CSS files. In the following example, the path to CSS files is set to “/css” and the path to javascript files is set to “/javascript”.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

<!-- HTMLHelper Property -->
<property name="html" type="MachII.properties.HtmlHelperProperty">
    <parameters>
	<parameter name="metaTitleSuffix" value=" | MyCompany, Inc." />
	<parameter name="cacheAssetPaths" value="true" />
 
	<!-- Defaults to ExpandPath(".") -->
	<!-- <parameter name="webrootBasePath" value="/" /> -->
 
	<!-- Defaults to webroot base path + "/js" -->
	<parameter name="jsBasePath" value="/javascript" />
 
	<!-- Defaults to webroot base path + "/css" -->
	<parameter name="cssBasePath" value="/css" />
 
    </parameters>
</property>

Two quick notes on this block of code:

1. You’ll notice that I’ve commented out the parameter named “webrootBasePath”. It defaults to the filesystem path equivalent to where your index.cfm page is running which is what I wanted, so I commented it out so as to use the default.
2. You’ll also notice a parameter named “cacheAssetPaths”. There’s quite a bit behind this one, but the short version of the story is that, used correctly, this can help your visitors not have to download your javascript and css files every time (using them from the browser cache instead), while still forcing the browser to download the file if you have made any changes. Refer to the wiki page listed above for a complete description on this feature of the HTMLHelperProperty CFC.

One thing that the HTMLHelperProperty doesn’t do at the moment is allow you to store “ad-hoc” javascript code for inclusion in the section. This would be especially helpful in dealing with jQuery plugins as many of them need to be initialized in script once the document is loaded. For example, the following script is required to trigger the FancyBox plugin on an image named “preview”:

 $(document).ready(function() {
	$("#preview").fancybox();
});

It would be really nice to be able to do something like the code below to have your own custom scripts included in the header after the other javascript files are loaded:

1
2
3
4
5
6
7

<cfsavecontent variable="fancyBoxInit">
     $(document).ready(function() {
	$("#preview").fancybox();
      });
</cfsavecontent>
 
<cfset getProperty("html").addScript( fancyBoxInit, "javascript") />

The only issue I had with the property is that I got an error under under Railo 3.1.015 if I left the .js extension off of each javascript file I wanted to include. The wiki page examples say that you can just put the name of the javascript and css files (minus the extension) into the function, but I wasn’t able to get it to work unless I included the extensions. I’m still experimenting with this to see if it’s a bug in the property when running under Railo or if it’s something that I did.

All in all I’m very impressed with the feature and REALLY happy that I found it before tearing off and creating my own solution.

UPDATE: After looking through the code, I determined that I was getting an error when leaving off the extension of the files because my files had periods in their names other than between the filename and extension. I filed this bug and submitted a patch. The MachII team reviewed the patch, integrated it into the source and closed the ticket in the space of about 90 minutes. So, this bug has been resolved in the latest BER version in Subversion.

Two of the projects I’m working on at the moment have had complete user interface updates in the last two weeks. One is a MachII project I’m working on with my brother. The other is a ModelGlue project I’m working on with another client. In each instance, the decision was made that the template that we were using just wasn’t flexible enough to allow us to easily do what we wanted to so the decision was made to replace it. I’m not talking about a simple color scheme change–both these were radical template changes that changed overall layout containers and content containers as well as the styles for the content elements themselves.

In a traditional, “spaghetti” ColdFusion site like we all wrote back in the early days (what I like to call the “Bad Ole Days”), this would have been a nightmare to do on a site of any size. Granted, these two applications were both small- to mid-sized at the moment, but the amount of work and testing required would still have been significant.

Here’s the real kicker though. Each of these were done in less than 1 man day’s worth of effort due to the way MachII and ModelGlue separate the different parts of the process of generating the final HTML page! That’s just awesome as far as I’m concerned!

So, for those people that use the argument that MVC frameworks are more work than they’re worth except in large, enterprise-class applications, I submit that the first time you encounter this situation, you just might change your mind.

*Disclaimer: I know that there are other MVC frameworks out there for ColdFusion and they solve a lot of the same problems that MachII and ModelGlue do. I only mention these two here because they’re the ones that I worked with directly.