Are you using CFCOMPONENT NAME? I'll argue that you should not be. Here's why
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">
</CFFUNCTION>
</CFCOMPONENT>
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:
<cfdump var="#getmetadata(hello)#">
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:
| version | value |
|---|---|
| CFMX 6.1 | hello |
| CFMX 7.02 | demo.hello |
| 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.
The patch is just for the CFC *Wizard* -- people will still be able to manually add the Name attribute if they so choose, but it won't be automatically added any longer. The patch also adds the Output attribute, so in effect, it's replacing the uncommon and undocumented [and now controversial!?] Name attribute with the commonly-used and well-documented Output attribute.
And of course, the CFE gang can also choose not to apply the patch -- public discussion about this is my goal, and I don't mind sticking my neck out in the process.
Thanks again!
But I still would vote caution in proceeding. I mean, seriously, I've made this post to get the discussion started and to represent the research I've done, but I don't know for sure that there's something that we're missing. :-)
As for adding the Output attribute, phew, this isn't the place to start too big an off-topic discussion, but I hope you're clear on the impact of adding it. Many don't realize that Output=true or Output=false mean one thing, but no Output attribute at all means yet another. Any wizard adding that in needs to be careful to know what the user really expects (and sadly, many users aren't aware of the distinction to decide correctly when starting out).
It's certainly debatable whether CFC's Ouput should default to False (my preference) or to "not present" (the current CFE/HomeSite/hand-coding default) -- but is excluding Output from the CFC wizard just as debatable? You've suggested caution, so let's look at some reasons why adding it might be worth doing:
The trinary behavior (of CFC's Output attribute) you mention is one of the main reasons I'm pushing this change (though I'm not sure it's good practice for "not present" to behave differently from any of the acceptable values -- I'd rather see "true", "false", and "sort of"! :*) As you note, it's a frequently used and often misunderstood attribute, which I believe makes it a strong candidate for inclusion in the wizard.
Another argument in favor is that the wizard should be internally consistant. The CFC wizard's CFFunction section has a *checkbox* for Output, even though that attribute in CFFunction has the same trinary behavior as it does within CFComponent (tag content of both is treated as ordinary CFML if Output is not present; as if within CFOutput tags when Output="true"; as if within CFSilent tags when Output="false"). That suggests that the CFFunction Output field should be changed to a true/false/empty[not present] select box -- and that the CFC's Output field should echo that behavior, rather than duplicating the existing CFFunction section's strictly boolean behavior. In either case, Output is part of the wizard for CFFunction, so makes sense that be there for CFComponent as well.
Another place to look for answers is in the behavior of existing tools. HomeSite/CFStudio don't come with CFC builders, so I decided to find out what Dreamweaver does, and came across a page (http://www.adobe.com...) -- on which it appears that DW's CFC builder does include the Output field, and does so as a select box. It *seems* to be defaulting to not present ("standard output" in the wizard is shown in the code below as not having an Output attribute), while its CFFunction section, like CFE, has a checkbox (so the wizard cannot represent a cffunction that has no output attribute).
Without starting yet another discussion, it's [probably!] safe to say that most CFE users are at least as comfortable with advanced features as most DW users, and thus it seems reasonable for CFE to at least duplicate the exact same behavior as DW.
As noted earlier, of course the CFE team gets the final vote on this, whatever I may think -- thanks for a challenging discussion, whatever their decision may be!