Adobe ColdFusion 8

Passing custom tag attributes by using CFML structures

You can use the reserved attribute attributeCollection to pass attributes to custom tags using a structure. The attributeCollection attribute must reference a structure containing the attribute names as the keys and the attribute values as the values. You can freely mix attributeCollection with other attributes when you call a custom tag.

The key-value pairs in the structure specified by the attributeCollection attribute get copied into the custom tag page's Attributes scope. This has the same effect as specifying the attributeCollection entries as individual attributes when you call the custom tag. The custom tag page refers to the attributes passed using attributeCollection the same way as it does other attributes; for example, as Attributes.CustomerName or Attributes.Department_number.

Note: You can combine tag attributes and the attributeCollection attribute when you use a custom tag directly or when you use the cfmodule tag to invoke a custom tag. If you pass an attribute with the same name both explicitly and in the attributeCollection structure, ColdFusion passes only the tag attribute to the custom tag and ignores the corresponding attribute from the attribute collection. You cannot combine tag attributes and the attributeCollection attribute when you use standard (built in) ColdFusion tags.

Custom tag processing reserves the attributeCollection attribute to refer to the structure holding a collection of custom tag attributes. If attributeCollection does not refer to such a collection, ColdFusion generates a template exception.

The following example uses an attributeCollection attribute to pass two of four attributes:

<cfset zort=StructNew()>
<cfset zort.x = "-X-">
<cfset zort.y = "-Y-">
<cf_testtwo a="blab" attributeCollection=#zort# foo="16">

If testtwo.cfm contains the following code: 

---custom tag ---<br>
<cfoutput>#attributes.a# #attributes.x# #attributes.y#
    #attributes.foo#</cfoutput><br>
--- end custom tag ---

its output is the following statement:

---custom tag ---
blab -X- -Y- 16
--- end custom tag ---

One use for attributeCollection is to pass the entire Attributes scope of one custom tag to another. This often happens when you have one custom tag that calls a second custom tag and you want to pass all attributes from the first tag to the second.

For example, you call a custom tag with the following code:

<cf_first attr1="foo" attr2="bar">

To pass all the attributes of the first custom tag to the second, you include the following statement in first.cfm:

<cf_second attributeCollection="#attributes#">

Within the body of second.cfm, you reference the parameters passed to it as follows:

<cfoutput>#attributes.attr1#</cfoutput>
<cfoutput>#attributes.attr2#</cfoutput>