Adobe ColdFusion 8

Passing data to custom tags

To make your custom tags flexible, you often pass data to them for processing. To do this, you write custom tags that take tag attributes and other data as input from a calling page.

Passing values to and from custom tags

Because custom tags are individual ColdFusion pages, variables and other data are not automatically shared between a custom tag and the calling page. To pass data from the calling page to the custom tag, you can specify attribute name-value pairs in the custom tag, just as you do for normal HTML and CFML tags.

For example, to pass the value of the NameYouEntered variable to the cf_getmd tag, you can call the custom tag as follows:

<cf_getmd Name=#NameYouEntered#>

To pass multiple attributes to a custom tag, separate them with a space in the tag as follows:

<cf_mytag Firstname="Thadeus" Lastname="Jones">

In the custom tag, you use the Attributes scope to access attributes passed to the tag. Therefore, in the getmd.cfm page, you refer to the passed attribute as Attributes.Name. The mytag.cfm custom tag page refers to the passed attributes as Attributes.Firstname and Attributes.Lastname.

The custom tag page can also access variables set in the calling page by prefixing the calling page's local variable with Caller. However, this is not the best way to pass information to a custom tag, because each calling page would be required to create variables with the names required by the custom tag. You can create more flexible custom tags by passing parameters using attributes.

Variables created within a custom tag are deleted when the processing of the tag terminates. Therefore, if you want to pass information back to the calling page, you must write that information back to the Caller scope of the calling page. You cannot access the custom tag's variables outside the custom tag itself.

For example, use the following code in the getmd.cfm page to set the variable Doctor on the calling page:

<cfset Caller.Doctor="Doctor " & Attributes.Name>

If the variable Doctor does not exist in the calling page, this statement creates it. If the variable exists, the custom tag overwrites it.

The following image shows the relationship between the variables on the calling page and the custom tag:

A. calling page B. getmd.cfm

One common technique used by custom tags is for the custom tag to take as input an attribute that contains the name of the variable to use to pass back results. For example, the calling page passes returnHere as the name of the variable to use to pass back results:

<cf_mytag resultName="returnHere">

In mytag.cfm, the custom tag passes back its results using the following code:

<cfset "Caller.#Attributes.resultName#" = result> 

Be careful not to overwrite variables in the calling page from the custom tag. You should adopt a naming convention to minimize the chance of overwriting variables. For example, prefix the returned variable with customtagname_, where customtagname is the name of the custom tag.

Note: Data that pertains to the HTTP request or to the current application is visible in the custom tag page. This includes the variables in the Form, Url, Cgi, Request, Cookies, Server, Application, Session, and Client scopes.