User Guide

256 Chapter 11: Creating and Using Custom CFML Tags
The baseTag attribute specifies the name of the base tag that gets access to this tag’s attributes.
The
dataCollection attribute specifies the name of the structure in which the base tag stores the
sub-tag data. Its default value is AssocAttribs. You only need to specify a
dataCollection
attribute if the base tag can have more than one type of subtag. It is convenient for keeping
separate collections of attributes, one per tag type.
Note: If the custom tag requires an end tag, the code processing the structure referenced by the
dataCollection attribute must be part of end-tag code.
When cfassociate is encountered in a sub tag, the sub tag’s attributes are automatically saved in
the base tag. The attributes are in a structure appended to the end of an array whose name is
thisTag.collectionName.
The
cfassociate tag performs the following operations:
<!--- Get base tag instance data --->
<cfset data = getBaseTagData(baseTag)>
<!--- Create a string with the attribute collection name --->
<cfset collection_Name = "data.#dataCollection#">
<!--- Create the attribute collection, if necessary --->
<cfif not isDefined(collectionName)>
<cfset #collection_Name# = arrayNew(1)>
</cfif>
<!--- Append the current attributes to the array --->
<cfset temp=arrayAppend(evaluate(collectionName), attributes)>
The code accessing sub-tag attributes in the base tag could look like the following:
<!--- Protect against no sub-tags --->
<cfparam Name='thisTag.assocAttribs' default=#arrayNew(1)#>
<!--- Loop over the attribute sets of all sub tags --->
<cfloop index=i from=1 to=#arrayLen(thisTag.assocAttribs)#>
<!--- Get the attributes structure --->
<cfset subAttribs = thisTag.assocAttribs[i]>
<!--- Perform other operations --->
</cfloop>
Ancestor data access
The ancestor’s data is represented by a structure object that contains all the ancestor’s data.
The following functions provide access to ancestral data:
• GetBaseTagList() Returns a comma-delimited list of uppercase ancestor tag names, as a
string. The first list element is the current tag, the next element is the parent tag name if the
current tag is a nested tag. If the function is called for a top-level tag, it returns an empty string.
• GetBaseTagData(TagName, InstanceNumber=1) Returns an object that contains all the
variables (not just the local variables) of the nth ancestor with a given name. By default, the
closest ancestor is returned. If there is no ancestor by the given name, or if the ancestor does
not expose any data (such as
cfif), an exception is thrown.