Note: This blog post is from 2009. Some content may be outdated--though not necessarily. Same with links and subsequent comments from myself or others. Corrections are welcome, in the comments. And I may revise the content as necessary.

About the hidden gems series

With CF9 out and final, I'm excited to start identifying the interesting little bits and bobs which you may not have heard much about. Some will know I've done this going back to one of my first articles in the CFDJ from Feb 2000, on "Hidden Gems in 4.01".

Over the course of the next few weeks, I'll share various things that you may have missed, whether in the CF Admin, the language, the docs, or otherwise.

Hidden Gem 1: Controlling Application.cfm/cfc Lookup Order in Admin

If you've not noticed it, there is now a setting in the CF9 Admin for controlling how far above the current directory CF will look for Application.cfm/cfc if not found in the current directory. This is a server-wide setting (found on the Settings page).

How application file searching works by default

As you should know, if CF doesn't find an Application.cfm (or Application.cfc, since CF 7) in the current folder where a request starts, CF searches up to the parent, then the grandparent, trying to find one (and since CF 7 if it finds an Application.cfc it chooses that over an Application.cfm).

What many don't know is that by default ColdFusion has always searched all the way to the system root (the drive root). It doesn't stop at the webroot, which could lead to both security and possibly performance issues. This can now be changed using this setting.

To change this, find the Settings page which is the first link in the options on the left (see the arrow pointing to it in the image above). This new setting is about 2/3 the way down this page of settings (which is getting quite long!)

The options available in CF9

As the screenshot above shows, you can now change things to choose either of these alternative search behaviors:

• Default order
• Until webroot
• In webroot

As I said at the outset, things are not quite as obvious as they may seem. OK, the first is: it maintains the default behavior of searching to the system root, such as c:\.

The second does what some have wished: makes CF stop searching when it reaches the webroot. (The third option may make you think that this second option means search until the webroot but do not search in the webroot. That's NOT what it means.)

Before explaining that, let me point out as well that changing this setting is immediate. No restart of CF 9 is required.

The surprising "in webroot" option

So what then is the deal with the third option, "in webroot"? It may surprise you (as it did me, at first). What it does is tell CF to search either in the current directory (as they all do) or if not found, search ONLY in the webroot. It DOES NOT search the directories between the current directory and the webroot. Interesting. (To be clear, it does not mean "don't look in the current directory but only in the webroot". It still takes affect only if there is no Application.cfc/cfm in the current directory where a request starts.)

Why might one use this third option? Well, if they know that their server code directories are setup in such a way that the Application.cfc/cfm file is either in the directory of templates it should apply to, or if not there it's only in the webroot, then this option would suit them.

I can see it potentially causing confusion if folks don't know about the change in behavior and wonder, "why isn't my Application.cfc/cfm file (in an intermediary directory) running?"

Also, the fact that this is a system-wide feature means that all your apps on your entire server must accept the behavior specified here.

No documentation on this feature

Another source of confusion is the fact that there's no documentation explaining this feature. It's mentioned only in passing in the online help of the Administrator, without explanation of the meaning of the options. It's not mentioned at all in the docs, either the "Configuring and Administrating CF" manual or the "Developing Applications" manual. That's a real shame and I hope it will change in the next release.

In the meantime, I hope that this entry will help. Sorry that it was a long one, but again it's just not a trivial feature. It is indeed a hidden gem, and look for more to come from me soon.

(I've provided a zip here that can help you demonstrate things. Unzip it into a web root and run the nested /testdir/testsubdir/test.cfm, and observe that whichever Application.cfm runs reports where it was found. You can rename the various Application.cfm files to xApplication.cfm to observe the impact of CF's search order, and as you change the Admin settings. You'll also want to copy one of the Application.cfm files to a direcory above your webroot to test that, too. The content is identical in all of them.

Of course, beware when unzipping the file that you don't overwrite any Application.cfm that you already have in your webroot. Also, beware that if you have an Application.cfc file in that webroot, it would take precedence over the Application.cfm file.

Finally, to find the zip file, see the link appearing just below this blog entry.)

For more content like this from Charlie Arehart:

• Signup to get his blog posts by email:
• Follow his blog RSS feed
• View the rest of his blog posts
• View his blog posts on the Adobe CF portal

Need more help with problems?

• If you may prefer direct help, rather than digging around here/elsewhere or via comments, he can help via his online consulting services
• See that page for more on how he can help a) over the web, safely and securely, b) usually very quickly, c) teaching you along the way, and d) with satisfaction guaranteed