ColdFusion 8 Per App Settings - Mappings

According to the documentation for this feature, Per App mappings allows you to dynamically set "logical aliases for paths to directories on your server." This sounds great but the code example in the documentation is wrong and this leads to a lot of frustration.

The first problem is that the docs show how to set a mapping for an application but not how to use it. We could experiment a bit and eventually find out the exact syntax needed except for the second problem - the example code given to set the mapping is wrong.

The documentation says to use the following to set a mapping of "MyMap" pointing to the location "c:\inetpub\myStuff".

If we place a file called test.cfm into the "c:\inetpub\myStuff" directory we should be able to include it using standard cfinclude syntax. The problem is, no matter how we try, we can not get this to work. Every one of the attempts above results in an error. This leads to a ton of frustration and a search across the net for working examples. The problem with that is that there are no clear cut examples showing how to make this work.

The solution lay partially in a blog post by Sean Corfield (Scazu Powered By ColdFusion 8) where he shows how he created a number of dynamic mappings for his application. In his example code he added a forward slash before the name of the mapping, something not mentioned in the ColdFusion documentation. This is the key. This single character makes the difference between frustrating failure and a successful feature. Adding the slash we get an setting of:

and a usage of Frustration solved.

So to recap, ColdFusion 8 allows an application to have dynamic mappings. These are defined in the application.cfc using a syntax of this.mappings["/MyMap"] where MyMap is the mapping name. Once set, the dynamic mapping is used like any other mapping with a syntax of "/MyMap/...".

One fast note - We can use any name we want for a dynamic mapping even if the name is in use by a mapping set in the administrator. The only restriction is that if we try to set a dynamic mapping with "/", an error will be thrown. We always have to have some text after the forward slash.