Simple Custom Tags
A simple custom tag is one that is used in a page and adds code to that template without using any inputs. To add a custom tag's functionality to your page, you will place the custom tag in the custom tag directory or in the same folder as the page that you call the custom tag in from. For version control (managing updates to the custom tag) it is best to place the custom tag in the custom tags folder which is assigned through the ColdFusion Administration panel. If you are in a shared hosting environment, you may have to place in each folder where the tag is used.
After the tag is located on the server, you can use it by simply adding a single tag to your template. In the case of CF_States , the file name is states.cfm so we add cf_ to the start of the file name and drop the .cfm extension place the result within mark up brackets: <cf_states>. In your sample you should see a drop down select box listing all US states with California selected.
Custom Tags with Attributes
The previous example saves over 70 lines of code but it may not produce a select box to you or your clients taste. Custom tags can have attributes. Attributes are passed to the custom tag and are used within the custom tag to vary the tag's output. In the CF_States example, we can change what state is pre-selected and also abbreviate the state name to two letters. The attributes for CF_States are NONVERBOSE and SELECTED. By including these attributes, you can control the look of the select box. To show only two letters with Virginia selected use:
<cf_states nonverbose="yes" selected="va">
Creating Custom Tags
Creating a simple custom tag requires saving a portion of code as a ColdFusion template. Creating a custom tag that use attributes, only requires that you reference the attributes using the attributes scope. Within CF_States, attributes.nonverbose and attributes.selected are used to reference the nonverbose and selected attributes that are passed into the custom tag.
Sources for Custom Tags
A great way to learn about ColdFusion code and custom tags is to download sample tags and review the way they are coded. Free and inexpensive custom tags and applications can be found at the following sites:
- Macromedia Exchange
- Hotscripts
- CFTagstore
- CFXtras
Various Ways to Include CF Code
There are several ways to include ColdFusion code. Two ways were addressed above, they are summarized below with two other methods.
Ways of Including CF Code | ||
| Type | Syntax | Consideration |
| Custom Tag | <CF_filename> | This is the simplest syntax for calling in a custom tag. The syntax is adding CF_ to the start of the file name and dropping the .cfm. |
| Custom Tag | <CF_filename ATTRIBUTE-name ="attribute value"> | Same as simple custom tags but includes attribute/value pairs. |
| CFINCLUDE | <CFINCLUDE TEMPLATE="templatename" > | CFINCLUDE places the content of one template into another as a simple way to include code. |
| CFMODULE | <CFMODULE NAME="path" TEMPLATE="path" ATTRIBUTE ="attribute value" ATTRIBUTESCOLLECTION="" > | CFMODULE is an alternative way to call a custom tag. It is required when calling a custom tag from within a sub-directory of the custom tag directory. Either Name or Template is used and attributes can be called in indivdually or as a collection from a structure. |
Summary
Custom tags provide a great way to use your code or code from others. Custom tags simplifies coding while improving quality by using tested code. The use of attributes adds flexibility while maintaining reusibility. ColdFusions server's central location for custom tags promotes version control.
discuss this topic to forum
