Macromedia Coldfusion MX 7 Web Application Construction Kit

So far in this chapter, you have learned how to make custom tags that are mainly for internal use within your application or company. The <cf_ShowMovieCallout> custom tag might be enormously useful in building projects for Orange Whip Studios, but probably not all that helpful to the average ColdFusion programmer.

In contrast, you will sometimes find yourself writing a custom tag you know will be helpful not only to yourself but to other developers as well. If so, you can package it and make it available to others via the Developer Exchange on the Macromedia Web site, either free or for a fee.

Perhaps you need to convert sentences to title case, meaning that the first letter of each word should be capitalized. You could write a custom tag, perhaps called <cf_TextToTitleCase>, to get the job done. After the tag is complete, you could share it with other developers you know or even post it for free download by the entire ColdFusion developer community.

Listing 23.14 shows code that creates the <CF_TextToTitleCase> custom tag. The tag has two required attributesinput and output. The tag looks at the text passed to it via the input attribute, capitalizes the first letter of each word, and returns the capitalized version of the string back to the calling template by storing it in the variable specified by the output attribute.

A third, optional attribute, dontCapitalizeList, can be supplied with a comma-separated list of words that should not be capitalized. If this attribute isn't provided, it uses a default list of words: a, an, the, to, for, and of. If a word from the input is in this list, it is appended to the output string verbatim, its case preserved.

NOTE

The output attribute here works just like the ReturnVariable attribute in some of this chapter's other examples. Depending on the situation, simplified attribute names, such as input and output, can be easier for other developers to use. In other cases, more verbose attribute names, such as textToConvert and returnVariable, might make more sense. Geeky as it might sound, coming up with the names is part of the fun.

Listing 23.14. TextToTitleCase.cfmSource Code for <cf_TextToTitleCase>

<!--- Filename: TextToTitleCase.cfm Author: Nate Weiss (NMW) Purpose: Creates the <cf_TextToTitleCase> custom tag ---> <!--- Tag Parameters ---> <cfparam name="ATTRIBUTES.input" type="string"> <cfparam name="ATTRIBUTES.output" type="variableName"> <cfparam name="ATTRIBUTES.dontCapitalizeList" type="string" default="a,an,the,to,for,of"> <!--- Local Variables ---> <cfset result = ""> <!--- For each word in the input ---> <cfloop list="#ATTRIBUTES.input#" index="thisWord" delimiters=" "> <!--- Assuming this is a word that should be capitalized ---> <cfif listFindNoCase(ATTRIBUTES.dontCapitalizeList, thisWord) eq 0> <!--- Grab the first letter, and convert it to uppercase ---> <cfset firstLetter = uCase( mid(thisWord, 1, 1) )> <!--- Grab remaining letters, convert them to lowercase ---> <cfset restOfWord = lCase( mid(thisWord, 2, len(thisWord)-1) )> <!--- Append the completed, capitalized word to result ---> <cfset result = listAppend(result, firstLetter & restOfWord, " ")> <!--- If this is a word that should *not* be capitalized ---> <cfelse> <cfset result = listAppend(result, thisWord, " ")> </cfif> </cfloop> <!--- Return result to calling template ---> <cfset "CALLER.#ATTRIBUTES.output#" = result>

Listing 23.14 relies on the idea that you can think of a set of words (similar to a sentence) as a list, just like an ordinary, comma-separated list of values. The only difference is that the list is delimited by spaces instead of commas. Therefore, by supplying a space as the delimiter to ColdFusion's list functions, such as listAppend(), you can treat each word individually or loop through the list of words in a sentence.

NOTE

For more information about lists, see the various list functions (such as listFind(), listGetAt(), and listDeleteAt()) in Appendix C, "ColdFusion Function Reference." See also the discussion of CFML data types in Chapter 8, "Using ColdFusion."

First, three <cfparam> tags declare the tag's input and output attributes as well as the optional attribute, dontCapitalizeList. A variable called result is set to an empty string. Then, a <cfloop> tag loops over the words supplied by the input attribute. For each word, the first letter is capitalized and stored in the firstLetter variable. The remaining letters, if any, are stored in the restOfWord variable. So, when the firstLetter and restOfWord variables are concatenated using the & operator, they form the capitalized form of the current word. The listAppend() function then appends the word to the list of capitalized words in result, again using the space character as the delimiter. When the <cfloop> is finished, all the words in input have been capitalized and the tag's work is done. It then passes the completed result back to the calling template using the usual quoted <cfset> syntax.

NOTE

Because of the way ColdFusion's list functionality behaves, consecutive space characters from the original string are not preserved in the tag's output. ColdFusion treats multiple delimiters as a single delimiter. So if the Input contained three words with five spaces between each word, the resulting output would still contain three words (in title case), but with only one space between each word. This is the defined, documented behavior and isn't a bug. Depending on the situation, the multiple-delimiter behavior can work for you or against you. Just keep it in mind.

Listing 23.15 shows how you and other developers can use this custom tag in actual code. Figure 23.6 shows what the results look like in a browser.

Listing 23.15. UsingTextToTitleCase.cfmUsing <cf_TextToTitleCase>

<!--- Filename: UsingTextToTitleCase.cfm Author: Nate Weiss (NMW) Purpose: Demonstrates how to use the <cf_TextToTitleCase> custom tag ---> <html> <head><title>Using &lt;cf_TextToTitleCase&gt;</title></head> <body> <h2>Using &lt;cf_TextToTitleCase&gt;</h2> <!--- Text to convert to "Title Case" ---> <cfset originalText = "The rest of the band's around back."> <!--- Convert Text to Title Case, via Custom Tag ---> <cf_textToTitleCase input="#originalText#" output="fixedCase"> <!--- Output the text, now in Title Case ---> <cfoutput> <p><b>Original Text:</b><br> #originalText#<br> <p><b>Processed Text:</b><br> #FixedCase#<br> </cfoutput> </body> </html>

Sharing Your Custom Tags

As explained in the section "Finding Tags on the Developer Exchange," earlier in this chapter, the Developer Exchange on the Macromedia Web site is the first place most ColdFusion developers go when they are looking for custom tags to purchase or download. If you want to share one of your custom tags with others, consider posting it to the Developer Exchange.

Providing Documentation

If you're going to make one of your custom tags available to other developers, you should write some type of short documentation for the tag. No formal guidelines exist for doing this, but it is customary to write the documentation in a simple HTML (.htm) file and include it in a .zip file along with the custom tag template itself. So, for the <cf_TextToTitleCase> custom tag, you might create a documentation file called cf_TextToTitleCase.htm.

At the very least, your documentation should describe what the tag is meant to do and provide a list of its attributes. In general, the more detailed, the better. If your documentation isn't clear, you might start getting questions via email from developers who are using the tagand rest assured, they will find you!

NOTE

You will find that many developers don't know how to install a custom tag and often start fooling around in the ColdFusion Administrator or the Registry instead of just placing your template in the special CustomTags folder. So you should say early in your documentation how to install the tag.

In addition, you should include a sample ColdFusion template (.cfm file) showing how to actually use the custom tag in code. For instance, for the <cf_TextToTitleCase> custom tag, you could simply include the UsingTextToTitleCase.cfm template from Listing 23.15.

Posting to the Developer Exchange

Posting your custom tag to the Developer Exchange on the Macromedia Web site is simple. If you're going to allow people to download your tag for free, all you need to do is create a .zip file that contains your custom tag template, plus any documentation or examples, as discussed above. Then go to the Developers Exchange and follow the submit links to post your tag to the exchange.

Visit the Developers Exchange at http://www.macromedia.com/cfusion/exchange/index.cfm.

Selling Your Custom Tags

As of this writing, the Developer Exchange on Macromedia's Web site doesn't accept payment for commercial tags. If you want to sell your custom tags, you must either set up a secured payment processing and download area of your own (see Chapter 28) or use a specialized third-party site to handle this for you.

NOTE

The CFXtras Web site at http://www.cfextras.com is a good example of such a site. Signing up as a tag author and selling your custom tags is easy. The site retains a portion of each payment made to you as a service fee.