Note: This blog post is from 2006. 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.Are you using CFCOMPONENT NAME? I'll argue that you should not. Here's why. Someone asked me what I knew about the CFCOMPONENT NAME attribute. They were finding it being used but couldn't find any explanation of its purpose. I'd never really noticed it before, but as I started researching it, I can see some sources of potential confusion. From my testing, I'm going to propose that it's not something you should be using at all. It serves no purpose and can instead lead to confusion. I realize that's going to surprise those who use it, and perhaps it will cause a stir, but let me make the case, and you can decide for yourself.
Supported versus Unsupported Attributes on CFCOMPONENT, and GetMetaData()
First, there's no NAME attribute listed for CFCOMPONENT in the CFMX docs. If one wants to give a friendly name or description to a CFC, that's the purpose of the DisplayName or Hint attributes instead.
More important, whenever you use any attribute on CFCOMPONENT that's not otherwise supported, the only programmatic motivation would seem to be to take advantage of the fact that a GetMetaData() call against that CFC will return that attribute as a key in its result.
But it turns out there is ALREADY a getmetadata key called "name" that's always returned from a getmetadata call against a CFC, and it always returns an internally generated value indicating the name and location of the CFC, and more to the point, this value returned is NEVER affected by your use of a NAME attribute on CFCOMPONENT.
Curiously, I do find that different versions of CF and BD return slightly different values for that (more on that in a moment). And for those who may wonder, neither the use of NAME nor any unsupported attribute affects the output of the CF Component browser.
That's why I'll argue you shouldn't be using NAME at all. It not only does nothing (is not returned by getmetadata), but it may lead someone to be confused that it should. I don't know if I will go so far as to propose that CF (and BD) should raise an error when it's used. Sadly, a google search for "cfcomponent name" shows hundreds of pages using it (and those aren't real code running on people's servers but instead code people are sharing on the web for demonstration purposes), so restricting that could have a lot of impact.
If one wonders how people started using it, I'll note that (sadly) the CF7 docs user guide section on "documenting CFCs" does shows using the NAME attribute. I will leave a comment there pointing to this blog for folk's consideration (and perhaps to get Adobe to remove that, if all this observation holds true).
Further, the person asking me about this did so because they noticed that the CFEclipse CFC wizard also implements the NAME attribute in CFCs it creates. Again, unless comments to this suggest otherwise, it seems that perhaps that should be changed.
I am open to hearing from others. It sure seems that all is as I see it, but if I've missed something, I welcome comments below. If there is any egregious problem or misunderstanding I've created, I will offer a follow-up entry to correct things.
What getmetadata's NAME key returns on different CFML engines
I mentioned above that if you use GetMetaData against a CFC instance, it does return a NAME value. What does that value hold? Well, the docs for CFMX 6.1 simply indicate that it's "the component name", with no further explanation. The CF7 docs reference on GetMetadata does elaborate further, now saying that it's the "Component name, including the period-delimited path from a component search root such as the web root or a directory specified in the administrator Custom Tag Paths page."
I mentioned before that I'd found differences between the two versions of CF as well as between editions of BlueDragon. Here's a demonstration. I setup a simple test hello.cfc file in a /demo directory off my webroot:
<CFFUNCTION NAME="GetHello" ACCESS="REMOTE" RETURNTYPE="string">
<CFRETURN "Hello World">
Note that in the CFC I have set the value of NAME to "hellox". I did also test it using simply "hello" or "hello.cfc", and it made no difference at all in the following results. I then called it with a template that used Getmetadata:
The dump of the getmetadata result always showed a NAME key and it was always the same whether I provided one or not, and regardless of what value I provided. But there was a slight difference among the engines, which showed the following values for the getmetadata name key:
|BDJX 6.2.302 (JX)||demo.hello |
|BDJX 6.2.302 (.NET)||demo.hello|
The big difference is that CFMX 6.1
You'll note I've put an asterisk next to the BDJX test. To do this testing among the 4 engines, I'm running on Windows XP with IIS, so I can't have multiple web sites. (Yes, I know about tools to get around that and that Apache would let me have multiple sites.) Instead, I setup multiple virtual directories, each pointing to the different engines (as I document in a CFDJ article), so that I could call the page invoking the CFC using each of the different versions of CF and BD. On my laptop, I use virtual directories named _cfmx, _cf7, _bdjx, and _bdnet (so calling my demo page above might be http://localhost/_cf7/demo/invoke_hello.cfm.) I was surprised to find that in BDJX (only), the resulting name key returned did also show the name of the virtual directory as a prefix to the value returned, so the getmetadata name value returned by BDJX in my example was _bdjx.demo.hello. Of course, you won't see that difference if you don't use virtual directories.
Those who delight in the discover of the new value returned in the pre-defined getmetadata name key may find the above details useful. The more important point, again, is simply that the use of a NAME attribute on CFCOMPONENT has no programmatic purpose at all. It's not a supported attribute, and unlike any other unsupported attribute, it's not returned by GetMetaData, so it seems it should not be used at all. Let me know if you think otherwise.
For more content like this:
- If you may prefer direct help, rather than digging around here/elsewhere or via comments, I can help via my consulting services
- See that for more on how I can help a) over the web, safely and securely, b) usually very quickly, c) teaching you as we go, and d) with satisfaction guaranteed