Tag Pairs


Let's say you have a Custom Tag called <cf_PrintDate> that contains only the following code:

 <cfoutput> Today's Date: #DateFormat(Now(), "mm/dd/yyyy")# </cfoutput> 

When you run this Custom Tag, you will find that it simply displays a formatted date. Here is a calling code snippet:

 <cf_printdate> </cf_printdate> 

The preceding code actually calls the Custom Tag two timesif you were to execute it you would see the date displayed twice on the screen. This is because regardless of whether the call to the Custom Tag references a start or an end tag, it will always run the Custom Tag.

NOTE

If you use <cfmodule> to call the Custom Tag, you can also use it as an end tag, like this: </cfmodule>.


<cfmodule> was first introduced in Chapter 28, "Custom Tags."


However, it is not useful to run the same code when we call the start and end tags. Typically, when the start tag is run, the Custom Tag's environment is createdmeaning that the necessary default variables and validation are performed here. The actual functionality of the Custom Tag is usually run when the end tag is accessed.

ThisTag Scope

Nested Custom Tags have some degree of intelligence about their own state. You can use the ThisTag scope to access the information, or tag instance data, that the tags know about themselves.

ThisTag is a structure. It can be used to store your own data (so that the data persists for the duration of the tag processing), and it also contains several default members.

Structures were covered in Chapter 15, "Structures."


ThisTag.ExecutionMode

ThisTag.ExecutionMode is a variable that tells us whether we're in the start, inactive, or end mode of a tag pair set. start mode refers to the start tag, end mode refers to the end tag, and inactive mode refers to any code or text that is run between the two tags.

Within our Custom Tag, we can specify what part of the program we would like to run in start or end mode. We simply evaluate which mode ColdFusion is currently processing, and instruct the program to react accordingly. The following code shows how we determine the value of ThisTag.ExecutionMode:

 <cfswitch expression="#ThisTag.ExecutionMode#"> <cfcase value="start">  <!--- in start mode, initialize variables --->  <cfparam name="Attributes.FirstName" value="Emily"> </cfcase> <cfcase value="end">  <!--- in end mode, perform the processing --->  <cfoutput>#ATTRIBUTES.FirstName#</cfoutput> </cfswitch> 

<cfswitch> and <cfcase> were introduced in Chapter 3, "Conditional Processing."


When ColdFusion runs the start tag, ThisTag.ExecutionMode will evaluate to start and only the <CFPARAM> tag will be run. When ColdFusion runs the end tag, ThisTag.ExecutionMode will evaluate to end and the value of ATTRIBUTES.FirstName will be evaluated and printed.

TIP

Generally, start mode is used for initialization, end mode for actual processing.


ThisTag.HasEndTag

ThisTag.HasEndTag is a variable that holds instance data about whether a particular start tag has an associated end tag. This value is used for validation purposes; some Custom Tags should not be processed without an end tag present. Analyze the following code:

 <cfif NOT ThisTag.HasEndTag>  This Custom Tag requires an end tag.   <cfexit> </cfif> 

<cfif> was introduced in Chapter 3, "Conditional Processing." <cfexit> was introduced in Chapter 28, "Custom Tags."


Because ThisTag.HasEndTag has either a yes or no value, it can be directly evaluated to a true or false statement by using the <cfif> tag. In the preceding code, if ThisTag.HasEndTag is not true, an error will be printed and the Custom Tag will be aborted. The usual place for this logic to occur is within the start case of the ThisTag.ExecutionMode evaluation.

ThisTag.GeneratedContent

Any text that ColdFusion types or generates during the inactive mode of ThisTag.ExecutionMode (in other words, between the start and the end Custom Tags) can be accessed by evaluating the variable ThisTag.GeneratedContent.

This is used primarily to access or change information between the start and end tags. For example, consider the following snippet:

 <cf_applyformat format="alert"> #message# </cf_applyformat> 

<cf_applyformat> TReats text based on a specified format. Here the alert format is used, and the text to be formatted for display is a ColdFusion variable named message (it may be a database column too). <cf_applyformat> needs to access whatever data is in message and then update it with the formatted data. It can do this by both reading and writing ThisTag.GeneratedContent.



Macromedia ColdFusion MX 7 Certified Developer Study Guide
Macromedia ColdFusion MX 7 Certified Developer Study Guide
ISBN: 0321330110
EAN: 2147483647
Year: 2004
Pages: 389
Authors: Ben Forta

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net