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.
It's that time again, time for me to start sharing hidden gems in CF9. In this first offering, I'll point out an interesting option now available in the CF Admin that lets you control how far up the drive CF searches for Application.cfm/cfc files. It's not quite as obvious as it seems, nor is it well documented. One of the options may even surprise you. More on the feature in a moment.
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.)