Application.cfc Mappings Gotcha

If you use Application.cfc mappings on Adobe CF, watch out.  If your mapping names contain only alphanumerics, the leading slash is optional.  However, if the name contains other characters (like an underscore), then you HAVE to use the leading slash or it won't resolve.  Ran into this on an app where my "coldspring" mapping worked flawlessly, but my "schema_tool" mapping refused to resolve.  Unfortunately for me, I wasn't aware that "coldspring" worked until about half an hour in to troubleshooting, because the "schema_tool" mapping gets used first.

The livedocs' example does not show leading slashes, which misled me for quite a while after I resorted to looking there when it didn't work.  It's been a long time since I went to livedocs, and I remember why.  ;)  If you scroll down, however, there is a comment about the leading slashes.  It's only five months old, so hopefully it'll get incorporated into the actual document at some point.

In the mean time, make sure you get those leading slashes in there!  I haven't tested this issue on any other CFML engines, but as long as you don't forget the slashes, it shouldn't matter.

6 responses to “Application.cfc Mappings Gotcha”

  1. ike

    One of the new config directories in version 3.2 of the onTap framework (aside from IoC configs) is for mappings, which is neat. It will actually allow plugins to create their own application-specific mappings when you install them. I don't expect most plugins to need it, but it's handy to have. The configs use a method call to set the mapping, so in addition to ensuring that they have that leading slash, it also allows the mappings to be relative from the application's root directory. :)

  2. ike

    Umm… well you don't have to be a jerk about it, but no, the point of Application.cfc mappings is to have application-specific mappings, which is entirely different than application relative mappings. Without going at all out of my way to try and find them I've seen a dozen or so different blog entries or mailing list threads where someone was royally confused by the fact that they needed to add a forward-slash in front of the name of the mapping (and in my experience that's been true whether there was an underscore in it or not). So I don't think it's unfair to say that it's nice to be able to simply declare a mapping as addMapping("coldspring","../coldspring") to avoid all that confusion and to avoid having to manually perform the extra getDirectoryFromPath(getCurrentTemplatePath()). I suppose similar comments from the Grails guys would be acceptable to you tho.

  3. Julian Halliwell

    Barney, my experience is the same as Ike's, that the forward slash is required for all mappings, alphanumeric or otherwise.

    It was me who originally reported the mistake in the Livedocs soon after the CF8 release and they did correct their examples fairly promptly. But for some reason the correction got "reverted" some months later, which I again reported. Adobe replied saying they would try and found out what happened and just post my comment in the meantime. But they don't seem to have done anything to "re-correct" the docs, which means it continues to cause confusion/frustration unless you read the comments.


  4. Julian Halliwell

    Submitted another reminder to Adobe, and they've responded with: "We will be correcting this soon enough." Sheesh, I wonder what kind of version control/workflow system they have that makes it too complex to just add a couple of slashes. Whatever it is, sticking to it is obviously more important to them than avoiding wasting their customers' time.

  5. Julian Halliwell

    Hurray, the docs have been corrected.