Skip to main content
Ben Nadel at cf.Objective() 2013 (Bloomington, MN) with: Will Belden
Ben Nadel at cf.Objective() 2013 (Bloomington, MN) with: Will Belden

Function Scope Binding Depends On Invoking Custom Tag, Not Defining Custom Tag

By
Published in Comments (8)

As I am learning more about ColdFusion custom tags, I wanted to play around with defining user defined functions within a ColdFusion custom tag. To test this out, I set up a parent tag that has a function called AddName(). This function is invoked by each child tag (where by the child tag stores one of its attributes into the parent tag's data scopes).

Here is the main page (index.cfm) that defines the custom tags:

<!--- Impor the tag libraries. --->
<cfimport taglib="./" prefix="tag" />

<tag:parent>

	<tag:child name="Libby" />
	<tag:child name="Andrea" />
	<tag:child name="Kate" />
	<tag:child name="Sam" />
	<tag:child name="Sarah" />

</tag:parent>

As you can see, each child tag has a single attribute, Name. This is the attribute value that we will store into the parent. Here is the parent tag (parent.cfm):

<!---
	Check to see which execution mode the tag is running in.
	We won't have access to the child tag data until we are
	in the End tag mode.
--->
<cfswitch expression="#THISTAG.ExecutionMode#">

	<cfcase value="Start">

		<!--- Define the tag-based functions. --->

		<cffunction
			name="AddName"
			access="public"
			returntype="void"
			output="false"
			hint="Adds a name to this tag's names array.">

			<!--- Define arguments. --->
			<cfargument
				name="Name"
				type="string"
				required="true"
				hint="A nested tag name attribute to add."
				/>

			<!---
				Add this name to our internal names array
				that we defined below.
			--->
			<cfset ArrayAppend(
				THISTAG.Names,
				ARGUMENTS.Name
				) />

			<!--- Return out. --->
			<cfreturn />
		</cffunction>


		<!---
			Define the array or names that will house the Name
			attribute values our child (nested) tags.
		--->
		<cfset THISTAG.Names = ArrayNew( 1 ) />

	</cfcase>


	<cfcase value="End">

		<!---
			Output the names that we have collected from the
			child tags.
		--->
		<p>
			Names:
		</p>

		<!--- Loop over our names array. --->
		<cfloop
			index="intName"
			from="1"
			to="#ArrayLen( THISTAG.Names )#"
			step="1">

			<p>
				#intName#) #THISTAG.Names[ intName ]#
			</p>

		</cfloop>

	</cfcase>

</cfswitch>

As you can see, in the Start mode of the parent tag, I am defining a user defined function named AddName() and an array named "Names". The AddNames() UDF takes a name argument and appends it to the Name array that we defined within the THISTAG scope. Then, in the End mode of the tag, we are simply looping over the names.

Here is the child tag (child.cfm) that invokes the parent's method:

<!---
	Check to see which execution mode the tag is running in.
	We won't have access to the child tag data until we are
	in the End tag mode.
--->
<cfswitch expression="#THISTAG.ExecutionMode#">

	<cfcase value="Start">

		<!--- Get the base tag. --->
		<cfset THISTAG.Parent = GetBaseTagData( "cf_parent" ) />

		<!---
			Define the tag attributes. Our only attribute is
			the Name attribute. Since we are not defining a
			default value, this is a REQUIRED attribute.
		--->
		<cfparam
			name="ATTRIBUTES.Name"
			type="string"
			/>


		<!---
			Now that we have the parent tag (base tag) pointer,
			let's add this tag's Name attribute value to the
			parent's name array.
		--->
		<cfset THISTAG.Parent.AddName( ATTRIBUTES.Name ) />

	</cfcase>

</cfswitch>

As you can see, the child tag gets a pointer to the parent tag using the GetBaseTagData() method. It then defines the required Name attribute and invokes the parent tag's AddName() method using the Parent tag pointer.

This should work fine, but when I run the index page above, I get this ColdFusion error:

Element NAMES is undefined in THISTAG.

What is going on? Well, we know that this error is definitely happening inside of the UDF AddName() as this is the only place that reference this NAMES element. But how could this be? We are explicitly defining the Names array within the THISTAG scope - why wouldn't it exist?

To investigate what was going on, I added these lines of code to the AddName() UDF right before the line that was causing the error:

<!---
	Dump out the THISTAG scope so that we can get
	a better of sense of where we are.
--->
<cfdump
	var="#THISTAG#"
	label="THISTAG From Within AddName() UDF."
	top="2"
	/>

<!---
	Abort page processing so the previous error
	event doesn't fire.
--->
<cfabort />

After adding that code and then rerunning the index page again, we get the following CFDump output:

Parent ColdFusion Custom Tag Method Invocation

As you can see, this CFDump contains a structure called "Parent". Well, who has this structure? Not the Parent tag. The only ColdFusion custom tag that has this Parent structure defined is the Child tag.

So what does this mean about the UDF AddName()? It means that when it was invoked, the VARIABLES scope of the UDF binded to the VARIABLES scope of the invoking custom tag at run time, not at compile time. This means that while the UDF was defined within in the context of the Parent tag, since it was invoked by the Child tag, the UDF acted as if it were part of the Child tag and not the Parent tag.

This is a little strange, but when I think about ColdFusion components, it kind of makes sense and kind of doesn't make sense. If you have two ColdFusion components and one has a pointer to a method of the other one and then invokes that method, the method acts as if it were defined within the invoking component, not within the defining component. In that case, the VARIABLES and THIS scopes of the ColdFusion component bind dynamically at invocation time, not at compile time.

For this custom tag example, it is not quite like that. In this case, the invoking tag is not treating the UDF as if it were its own; in fact, it is passing the Name attribute value to the method with an explicit scoping to the Parent object. But, even though it is not quite a parallel situation, perhaps there is something like that going on at the ColdFusion custom tag level as well.

Want to use code from this post? Check out the license.

Reader Comments

122 Comments

Whilst this might initially make you go "huh?" it ought to be expected behavior - functions are evaluated in the calling context in all cases and variable name binding occurs in that context.

Consider this code (I don't know how it'll look in comments):

parent.cfm:

<cfset foo = "parent">
<cffunction name="getFoo">
<cfreturn foo>
</cffunction>
<cf_child fn="#getFoo#">
<cfdump label="variables" var="#variables#" />

child.cfm:

<cfset foo = "child">
<cfset caller.result = attributes.fn()>

What will result be in the dump? Since foo inside getFoo is not bound by the definition - it is bound by the calling context - getFoo must return the foo in the child context.

15,822 Comments

@Sean,

The difference in our two examples is that your example passes the Function object to the child then invokes, while mine invokes the method as an attribute of the parent tag.

The funny thing is that BOTH of our examples lead to the same outcome. However, if you look at ColdFusion components, A and B.... A.Foo() called from within the context of B will bind to A (think getters and setters) but Foo passed from A to B and then invoked in B will bind to B.

Obviously ColdFusion components and ColdFusion custom tags are two different beasts, but both have their own memory scopes and their own rules of visibility... but until it was explored, I think it would not be obvious which scope binds when/where.

122 Comments

Like I say, it still seems obvious to me. A component method invocation binds in the dynamic context of the component because, well, that's how objects work. Custom tags are just regular pages so they're not going to work that way.

That's why you can copy function references in and out of components and have them bind <tt>variables</tt> scope to that calling context regardless. Components are objects, everything else is a page.

Now, of course, technically components are pages too and functions all compile out to separate objects but the object-style binding only occurs for components...

My Closures library would allow you to "fix" the custom tag behavior. You could create a closure in your parent tag and bind <tt>variables</tt> scope into it (under an alias) and then invoke the closure from the child tag and have it "correctly" reference the parent's <tt>variables</tt> scope (via the bound alias).

15,822 Comments

@Sean,

I see what you are saying, and I agree. I guess since ColdFusion custom tags behave slightly differently than a standard page template, I just thought maybe the properties of it might be different. But you are quite right - it is just page like anything else.

15,822 Comments

Oh yeah, I have also been lazy about what the comments on my blog recognize. I will update one of these days.

Also, this is all just for experimentation's sake. What was not obvious to me before will now be obvious to me in the future :)

... wearing dark glasses, getting good grades, the future's so bright, I gotta wear shades :)

I believe in love. I believe in compassion. I believe in human rights. I believe that we can afford to give more of these gifts to the world around us because it costs us nothing to be decent and kind and understanding. And, I want you to know that when you land on this site, you are accepted for who you are, no matter how you identify, what truths you live, or whatever kind of goofy shit makes you feel alive! Rock on with your bad self!
Ben Nadel