The CFMODULtaEg is based on a different concept from that of CFINCLUDEC FINCLUDE . makes it easy to reuse the same code in multiple teInflates. CFMODULE,.othne other hand, provides an easy way to develop custom tags.
Building custom tags can be a complicated proce/s and is dealt with in depth in Chapter 31, “Building Custom Tags.” However, CFMODULE makes it possible to quickly build custom tags. In this chapter, you will look at a simple example of a custom tag.
You should refer to Chapter 31 for a.detailed look at the concepts and techniques for building effective custom tags. The idea behind a custom tag is that it provides a self-contained, reusable piece of code that implements a particular function or set of functions. Like all ColdFusion tags, you can use these tags in your templates and provide data to them through tag attributes. The custom tags process any information provided to them in attributes and then can return results which get included in the template where the tag was used.
There is a subtle, but significant, difference between this model and that of CFINCLUDE: With CFINCLUDE, you are simply adding the code contained in the included file to your template and this is processed as part of the including template. The code in the included file can refer to variables in the template that use the CFINCLUDEtag to include it. The file does not need to contain a complete, fully-functional template: the code only needs to make sense at the point at which it is being included in a template.
When you use the CFMODULtaEg, you are asking ColdFusion to execute the code in the custom tag and only include the results in the template using the CFMODULtaEg. The custom tag is unaware of the environment of the calling template and only uses data provided to it through attributes.
This may seem unimportant but this encapsulation provides one key benefit: truly reusable code. A custom tag is written in such a way that it is in no way dependent on the environment in the template that invokes it with CFMODULTEh.is means that you can create custom tags that serve general purpose functions and you can use them in any number of applications and templates. As long as the calling template follows the correct procedures for passing data to the tag through attributes, the tag will work as expected.
Understanding CFMODULE Syntax
Before looking at an example you need to consider briefly the syntax of the CFMODULE tag. The tag takes at least one of the following two attributes: TEMPLAToEr NAME In. addition any number of custom attributes can be specified which are then accessible by the template being called.
The TEMPLATE Attribute
As with CFINCLUDEth e TEMPLAT attribute enables you to specify the path of the template file being called using relative paths.
The NAME Attribute
The NAME attribute provides an alternate way to specify the template file for your custom tag. ColdFusion provides a special CustomTags directory under the default Cold Fusion directory (which is usually
This directory is used to store custom tags. Tags contained in this sub directory can be specified by name using the NAMEattribute and dotted notation. Consider the examples in Table 8.1.
The use of the Custom Tags directory is discussed in more detail in Chapter 31.
Custom attributes are used to pass information to the tag for processing. Consider a sample tag for adding two numbers (yes ColdFusion can do this for you, but rt makes for an easy example of using custom attributes).
Without writing the code for the custom tag, you can ‘specify that the tag requires two numbers in the form of two custom attributes: A and B. In addition, you can also decide’ that the result of the addition will be returned to the calling template in a variable called’ RESULT
With this in mind, the callir g template can use CFMODULtoE add the two numbers:
<CFMODULE NAME-‘add’ A-‘l’ 8-‘2’)
This code segment calls your addition custom tag that is stored in the Custom Tags directory and then displays the results using CFOUTPUT.
Creating a Sample Custom Tag with CFMODULE
As an example of creating a sample custom tag,let’s take the simple headline and menu example used earlier when discussing CFINCLUDEI.nstead of using CFINCLUDE you will create two custom tags for generating the header and menu. The first will create the menu and output the results. The second will create the header and menu and return the results to the calling template in a variable
For both approaches you need to learn a little bit about how information is passed between the calling template and the custom tag.
In the code of the custom tag, the attributes being provided are accessed by using the at tr-i butes variable scope. For instance, in the preceding addition example the A attribute is accessed in the custom tag as at tributes.A and the B attribute as attributes. B
Similarly results can be returned to variables in the calling template by using the ca 11er variable scope. For instance, to return the output of the addition to RESU’_Tin the calling template, the value is assigned to ca 11e r. RESULTin the custom tag. With this knowledge in hand, let’s consider both approaches to your header and menu custom tag
Returning Output from a Custom Tag
The first approach is for the custom tag to create output, which is then included by the calling !o:” rl1ate as part of the final HTML document sent to the browser. This is similar in concept to the way in which many built-in ColdFusion tags result in specialized output in the HTML file (prime examples are the custom form control tags that you will learn about in Chapter 15, “Forms.”)
First you need to build a custom tag. The code for this tag looks like Listing 8.4
<CFSET Chosen – attributes.Section,
<CFIF Chosen is 1>
<A ·HREF-·syntax.cfm’>The Syntax</A>
<CFIF Chosen is 2>
<CFIF Chosen is 3>
Fundamentally this looks the same as the template that you used with CFINCLUDE. But there is one key difference: The first line of the template refers to at tr-i butes. Section. This means that the custom tag expects the required data to be passed in the attribute Section from the calling template. This value is assigned to the variable Chosen in the tag for easy access (Chosen requires less typing and code than attributes Section)
The calling template for the home page would then look something like this (assuming the template for the custom tag is saved as menu. cfm in the CustomTags directory):
<CFMODUlE NAME-‘menu’ Sectionm’O’>
CFMODUlE tag provides an alternative way of including outside code in the current template ..
The result is that where CFMODULaEppears, the output of the CFMODULtaEg will appear producing an end result like the following:
<A HREF-‘syntax.cfm’>The Syntax</A>
<A HREF-‘ alternatives. cfm’>Al ternat ivesc/A>
CFMODUlE tag provides an alternative way of including outside code in the current template
Functionally this might seem to be basically the same as when you used the CFINCLUDE tag but two different things are happening here
• You don’t have to assign a value to a variable before accessing the custom tag. This process is encapsulated into the tag itself.
• The results that are included in the calling template are not treated as Cold Fusion code but rather as the result of processing ColdFusion code. This means that you can’t return ColdFusion code from a custom tag and expect it to be processed as Cold Fusion code within the calling template. Instead it will be treated as plain text and sent as such to the browser and displayed without processing .
Returning a Result from a Custom Tag
In this scenario you will do things a little differently returning a result through a variable in the calling template. Although this approach means an extra line of code is required to output the results in the calling template it highlights the flexibility of a custom tag Multiple values can be passed to it in a standardized way and multiple values can be returned by it in a standardized way.
Our example requires only one piece of information to be passed to the tag and only one piece of data to be returned. Listing 8.5 shows the code.
<CFSET Chosen – attributes.Section>
<CFSET Result – ‘<Hl>Using CFINCLUDE</Hl>’>
<CFIF Chosen is 1>
<CFSET Result- Result & ‘<STRONG>The Syntax</STRONG>’>
<CFSET Result-Result & ‘<A HREF-“syntax.cfm”>The Syntax</A>’>
<CFSET Result – Result & ‘ I ‘>
<CFIF Chosen is 2>
<CFSET Result= Result & ‘<STRONG>Examples</STRONG>’>
<CFSET Result=Result & “<A HKE.I”~ examples.cfm”)c.xamplcs</A>’>
<CFSET Resu’lt = Result & ‘ I ‘>
<CFIF Chosen is 3>
<CFSET Result~ Result & ‘<STRONG>Alternatives</STRONG>’>
<CFSET Result-Result & ‘<A HREF=”alternatives.cfm”>Alternatives</A>’>
<CFSET Result = Result & ‘<HR>”>
<CFSET caller.HEADLINE = Result>
The calling template needs to be revised to look like this:
<CFMODULE NAMEs’menu’ Section-‘Q’>
Notice that the resulting HTML code for the header is assigned to the variable Result in the custom tag and at the end this value is assigned to the variable HEADLINE in the calling template which can then use CFOUTPUT to display the results