Thoroughly Document Your Use Of ColdFusion's CFHTMLHead Tag

Posted September 29, 2009 at 10:12 AM

Tags: ColdFusion

The other day on Twitter, I saw someone tweet about how they just discovered ColdFusion's CFHTMLHead tag and was planning to use it in a project. This gave me flash backs to a project I took over in which the CFHTMLHead tag was being used all over the place. Having not known about this tag at the time, I thought I was going crazy!! Stuff was showing up in the HEAD of the HTML document that wasn't there in the corresponding ColdFusion template and I couldn't for the life of me figure out where the heck it was coming from.

For anyone who has never seen the CFHTMLHead tag - please stop reading this post immediately - it takes text content and injects it into the end of the HTML HEAD element, assuming it has not yet been flushed to the client. For ease of use and demonstration, I am going to wrap the CFHTMLHead tag into a custom tag so that I can use the custom tag's generated content to set the CFHTMLHead text attribute:

htmlhead.cfm

 Launch code in new window » Download code as text file »

As you can see, the CFHTMLHead tag has one attribute, Text, which is the text output that will be injected into the HTML.

Now, let's take a look at how this works:

 Launch code in new window » Download code as text file »

As you can see here, after the HTML we add a Javascript tag using the CFHTMLHead custom tag wrapper. When we run the above page, here is the page source that results:

 Launch code in new window » Download code as text file »

As you can see, the Javascript defined at the end of the page winds up in the HEAD tag of the rendered content. While this might have some ooh-ahh factor at first, realized that this was a very simple example; imagine yourself in the middle of a massive application with hundreds of templates! Suddenly, having things pop up in the HEAD tag out of nowhere will not only be confusing, but very hard to debug.

This is one of the few ColdFusion tags that I actually recommend people don't use. It just seems very hacky to me - like using it is a symptom of some flaw in your page architecture. However, if you are going to use it, I beg of you this one thing: document your use of it! Either put some sort of ColdFusion comment in your HEAD tag about where content might come from; or, even put a comment in your CFHTMLHead content:

 Launch code in new window » Download code as text file »

Regardless of how you go about it, make sure that someone can look at either the ColdFusion page template or your rendered page source and gain some insight as to where this content is coming from. Otherwise, you'll be kicking yourself down the line (or get kicked by the developer that took over your project).

Download Code Snippet ZIP File

Post Comment  |  Ask Ben  |  Permalink  |  Print Page

• Add To Del.icio.us
• Add To Digg
• Add to Spurl.net
• Add to Wists
• Add to Simpy
• Add to Newsvine
• Add to BlinkList
• Add to Furl
• Add to reddit
• Add to FARK
• Add to BlogMarks
• Add to Yahoo! My Web
• Add to smarking
• Add to Ma.gnolia
• Add to Segnalo

Reader Comments

I love cfhtmlhead. I use it religiously in my Model-Glue apps. To me it makes more sense to keep my JavaScript logic in my view instead of mucking about trying to fit it all in my massive dspTemplate.cfm file and playing the viewstate.setValue('needSomeScript', true) game.

Different strokes for different folks I guess ;)

@Todd,

As long as you document, it's totally fine. However, I wouldn't refer to setting things into the ViewState a "game" :) after all, it's there to carry data throughout the page request.

It might also be a good idea to warn people that CfHtmlHead is immune to good old >cfcontent reset=true<. I had issues with some old code where I wanted to clear the output buffer and kept finding out it wasn't empty. I then finally hunted down the culprit CfHtmlHead.

@David,

Very interesting. So, no matter what you do, the CFHTMLHead data gets injected.

Also, in the "Web 2.0" world, I think it's worth noting perhaps that it is recommended that a lot of linked content (ie. Javascript) be placed at the bottom of the page such that the UI can load faster.

I've not tested it, but seems like this tag might break when the head tag has profile="" attribute. http://stackoverflow.com/questions/1477266/how-to-prevent-coldfusion-from-injecting-cfform-js-into-the-head-section

I use CFHTMLHead to add stylesheets when a page is being built by our CMS pulling the content out of our database, we have one global one that is always used and then depending on what kind of content a user has added it will insert the correct stylesheets at the top of the datatypes cfm template.
since it doesn't really make sense to use it before closing your head tags maybe even just putting a HTML comment just before the </head> would make it easier to see what is from where

I agree with Ben that use of cfhtmlhead should be avoided. I ended up writing up my own custom tag that copies text passed to it as a key in request scope. Since I use a central layout (MG & Fusebox), the layout file extract that key and spits it out before </head>

That's not all.
Using <cfhtmlhead> can also bite you in the a$% if at some point you have to use <cfflush> to partially serve large files and one of the "head" calls happens after the "flush".

I've found what looks like the best way to reset/clear anything the CfHtmlHead tag has set. Model-Glue has the best version I've seen of this approach, it works around a bug in other versions and has Railo/BlueDragon support too.

It's called "resetCfHtmlHead" and can be easily dropped into any existing code by just copying out the function itself.
http://svn.model-glue.com/tag/MG_3.0_Final%20_8_10_2009/ModelGlue/gesture/remoting/AbstractRemotingService.cfc

@David,

Cool stuff. Definitely a good understanding of the internal workings of the page request / response mechanisms.

Hi,
This is very helpful and informative article.You have given some nice code and suggestion for the CFHTML use.

I've managed to piece together the following code from various sources on the internet, allowing you to reset/clear or get the contents of the cfhtmlhead buffer. It works in ColdFusion only (no railo/bluedragon) and comes in quite handy if dealing with code using CFHtmlHead.

http://pastebin.com/f2560e44d

@David: What version of ColdFusion did you test that with? I am on 8.0.1 and the getCFHtmlHead function errors on the line with local.out.getClass().getDeclaredField("headerBuffer"). It appears that my version of ColdFusion doesn't have a headerBuffer field in the NeoBodyContext class, but insead an appendHeaderBuffer and prependHeaderBuffer field. Interestingly enough, the contents of cfhtmlhead goes into appendHeaderBuffer and the JavaScript produced by cfajaxproxy shows up in prependHeaderBuffer. I guess this is the problem when dealing with uncoumented features of your app server. :)

@Brad,

Well spotted! I've been doing this in 7 but when I tested it on 8 I forgot to remove a try/catch I had added.

I'll have a look at that and see if I can sort it out. ;)

Post Comment  |  Ask Ben

Post A Comment

Please review the following issues:

Author Name:
Author Email:
Author Website:
Comment:	Formatting: <strong>bold</strong> <em>italic<em>
	Remember my information
	Subscribe to entry *
	Send me a copy of this comment (as part of the comment thread)

 

* If you subscribe, any new posts to this thread will be sent to your email address.