[Looking for Charlie's main web site?]

Hidden Gem in CF9: controlling Application.cfm/cfc lookup order

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.)

For more content like this from Charlie Arehart: 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
Thanks for explaining.
Isn't CF case sensitive? If yes it's Application.cfm not application.cfm
# Posted By Michael | 10/7/09 4:01 AM

CF is not case sensitive, but the OS you're using might be. On Windows, the case of Application.cfm doesn't matter, however it does matter on Linux. You should always use Application.cfm just to be safe.

While it'll never matter on Windows, if you ever move the application to some *nix flavor, it will matter and thus cause problems with your code.
Yep, what Dan says. I just wasn't being careful about that casing--sign of a typical Windows-based CF developer. :-) Thanks for clarifying for those who might have stumbled. Looking forward to hearing what others think of this new feature.
Thanks so much for taking the time to clarify this Charlie.

This was one of the first bugs I logged in the CF9 Beta:
Glad to help, Steven. Like Jimmy Durante used to say, "I've got a million of 'em". Well, dozens for now, coming soon. :-)
Someone reminded me that where I said there were "no docs" on this feature, I could at least address that a little by adding a comment in the docs themselves, which I have just done at:


Do keep that in mind, if you ever see either something that deserves feedback or, as here, where you might point to an alternative source of information that readers of the docs may want to consider.
Hi Hart i am concerning about SOLR server for searching in brief manner usage of "category" as it gives me NULL results.
The problem is I am having hundreds of files consists of data from 2000 to 2011 for both FALL and Spring semesters.
now dynamically at the runtime i am asking about the category(either SEM or YEAR) if i categorize either by year or by SEM but it doesnt give me any results so can u please give me some push on this.
Advanced thanks
# Posted By lucky | 10/27/11 10:43 AM
@lucky, I'm afraid that question has nothing to do with this blog entry. Also, I do not know the answer to the question that you are asking. I would recommend you ask it instead on the Adobe CF forums.
Copyright ©2024 Charlie Arehart
Carehart Logo
BlogCFC was created by Raymond Camden. This blog is running version 5.005.
(Want to validate the html in this page?)

Managed Hosting Services provided by
Managed Dedicated Hosting