Ben Nadel
On User Experience (UX) Design, JavaScript, ColdFusion, Node.js, Life, and Love.
Ben Nadel at CFinNC 2009 (Raleigh, North Carolina) with: Matthew Senn and Michael Senn and Phillip Senn
Ben Nadel at CFinNC 2009 (Raleigh, North Carolina) with: Matthew Senn , Michael Senn , and Phillip Senn@PhillipSenn )

ColdFusion Application-Specific Mappings Work With CFInclude

By Ben Nadel on
Tags: ColdFusion

Ok, so I know this post is like 3 years too late; but, the other day, I got to thinking about the application-specific mappings introduced in ColdFusion 8 and I wondered if I had ever used them for CFInclude. I know that I use them for createObject() all the time; but, I don't think I had ever actually used (or even tested) application-specific mappings in the context of a CFInclude tag. As such, I figured I would throw a small demo together to ease my mind.

To test the application-specific mappings, I set up three directories in my application:


Each of these directories simply includes an index.cfm file that outputs the phrase, "I am in the XYZ folder," in which XYZ is replaced with the actual folder name. Then, I set up an Application.cfc file that defined mappings for each of these directories.


  • <cfcomponent
  • output="false"
  • hint="I define the application settings and event handlers.">
  • <!--- Define the application settings. --->
  • <cfset = hash( getCurrentTemplatePath() ) />
  • <cfset this.applicationTimeout = createTimeSpan( 0, 0, 5, 0 ) />
  • <!---
  • Get the root of the application so that we can start
  • creating mappings that are relative to the current directory.
  • --->
  • <cfset this.rootDir = getDirectoryFromPath(
  • getCurrentTemplatePath()
  • ) />
  • <!---
  • Now that we have the root directory, let's set up mappings
  • for our various MVC code containers.
  • /view == templates
  • /controller == content
  • /model == com
  • --->
  • <cfset this.mappings[ "/view" ] = "#this.rootDir#templates/" />
  • <cfset this.mappings[ "/controller" ] = "#this.rootDir#content/" />
  • <cfset this.mappings[ "/model" ] = "#this.rootDir#com/" />
  • <!--- ------------------------------------------------- --->
  • <!--- ------------------------------------------------- --->
  • <cffunction
  • name="onRequest"
  • access="public"
  • returntype="void"
  • output="true"
  • hint="I execute the incoming request.">
  • <!---
  • Include the index file of each of our three code
  • containers; however, use the per-application mappings
  • rather than the actual folder names.
  • --->
  • <cfinclude template="/view/index.cfm" />
  • <cfinclude template="/controller/index.cfm" />
  • <cfinclude template="/model/index.cfm" />
  • <!--- Return out. --->
  • <cfreturn />
  • </cffunction>
  • </cfcomponent>

As you can see, based on the this.mappings collection defined in the ColdFusion application framework pseudo constructor, "model" maps to "com," "controller" maps to "content," and "view" maps to "templates." The onRequestStart() event handler then overrides the incoming request, including the index.cfm file from each of my mapped directories.

When we run the above code, we get the following output:

I am in the Templates folder.
I am in the Content folder.
I am in the Com folder.

Ok cool, mind at ease - ColdFusion 8's application-specific mappings work with CFInclude. That doesn't mean that I have a particularly great use-case for it (in the context of CFInclude); but, I'm happy to know for sure that it works.

Reader Comments

Have you tried to change a mapping while a site was live and running to see if it creates and issue or works? I was not aware you could use dynamic variables like this and it is a good concept. Thanks for sharing.


I have seen some issues with the use of "this.customTagPaths" and sites under load; but, I have never seen issues with "this.mappings". This is typically how I set my mappings these days and it seems to be fine.

Like I said, though, customTagPaths does seem to get a bit iffy - occasionally throwing a "Template not found" error.

I've had just had a use case for it recently. I've written an os application framework which uses FW/1, WireBox and hyrule so i had to ensure there is a dynamic mapping for the used libraries neverthless where the framework folder is stored (webroot or applicationroot).

I think I've had some trouble with cf "finding" components every once in a while using mappings. I told my users to press refresh and it worked. So I finally just hard coded the folder names and the problem went away. That's not scientific though.

I tried this but at first it didn't work - it just showed links to Application.cfc and the directory structure. I added an index.cfm to the home directory and then it works but doesn't show any text from the index.cfm in the home directory.

From this I assume an index.cfm is required in the home directory as well to ensure that the Application.cfc is run but that it is then ignored.

Is this how it is supposed to work?


Note: It appears that you can not use the mappings in the pseudo-constructor (e.g. you can not have a cfinclude in the pseudo-constructor that uses the mapping.) You must wait until after it (the pseudo-constructor) has completed execution.

Ben! You said "I have seen some issues with the use of "this.customTagPaths" and sites under load".

Thats exactlt what I am seeing with my site right now just finished being load tested. A bunch of random missing template errors when including files via paths set in this.mappings.

Its totally intermittent and random. This is crazy that it doesn't perform under load?!

I guess I need to hard code all of these paths in the CFAMIN (ugh -ugly).

Anybody been able to get this working nicely?

Hi Ben have you ever tried using this technique between sub domain names?


I'm building a project where I own a domain name and I create a subdomain for each of my clients to have a landing page with links that would seem that they are loading from this sub domain. I want this templated obviously so I don't have to copy a bunch of files into each subdomain.

I want to use the methods above and include in each subdomain, the minimal amount of files (ie application.cfc only if possible.)

I've got above working so that index.cfm from my mapped view loads. But when i click from the mapped index.cfm; for example [a href="link.cfm"]link[/a]>, where link.cfm exists in same dir as mapping, I get file not found in the subdomain.

So, how can i create links in my view where the subdomain is completely mapped to the view folder?

Perhaps my rendition of MVC is incorrect, where it should be assumed index.cfm from the mapped view is the only thing that should load.

Ive tried several tricks to get to work but so far unsuccessful.

All help is appreciated! Thank you