Adobe ColdFusion 8

Using tag attributes summary

Custom tag attribute values are passed from the calling page to the custom tag page as name-value pairs. CFML custom tags support required and optional attributes. Custom tag attributes conform to the following CFML coding standards:

  • ColdFusion passes any attributes in the Attributes scope.
  • Use the Attributes.attribute_name syntax when referring to passed attributes to distinguish them from custom tag page local variables.
  • Attributes are case-insensitive.
  • Attributes can be listed in any order within a tag.
  • Attribute name-value pairs for a tag must be separated by a space in the tag invocation.
  • Passed values that contain spaces must be enclosed in double-quotation marks.
  • Use the cfparam tag with a default attribute at the top of a custom tag to test for and assign defaults for optional attributes that are passed from a calling page. For example: 
    <!--- The value of the variable Attributes.Name comes from the calling page. If 
    the calling page does not set it, make it "Who". --->
<cfparam name="Attributes.Name" default="Who">

  1. Use the cfparam tag or a cfif tag with an IsDefined function at the top of a custom tag to test for required attributes that must be passed from a calling page; for example, the following code issues an abort if the user does not specify the Name attribute to the custom tag:
    <cfif not IsDefined("Attributes.Name")>
    <cfabort showError="The Name attribute is required.">
</cfif>

Custom tag example with attributes

The following example creates a custom tag that uses an attribute that is passed to it to set the value of a variable called Doctor on the calling page.

  1. Create a ColdFusion page (the calling page) with the following content:
    <html>
<head>
    <title>Enter Name</title>
</head>
<body>
<!--- Enter a name, which could also be done in a form. --->
<!--- This example simply uses a cfset. --->
<cfset NameYouEntered="Smith">

<!--- Display the current name. --->
<cfoutput>
Before you leave this page, you're #Variables.NameYouEntered#.<br>
</cfoutput>

<!--- Go to the custom tag. --->
<cf_getmd Name="#NameYouEntered#">
<!--- Come back from the Custom tag --->

<!--- Display the results of the custom tag. --->
<cfoutput>
You are now #Variables.Doctor#.<br>
</cfoutput>
</body>
</html>

  2. Save the page as callingpage.cfm.
  3. Create another page (the custom tag) with the following content:
    <!--- The value of the variable Attributes.Name comes from the calling page.
    If the calling page does not set it, make it "Who". --->
<cfparam name="Attributes.Name" default="Who">

<!--- Create a variable called Doctor, make its value "Doctor " 
    followed by the value of the variable Attributes.Name.
    Make its scope Caller so it is passed back to the calling page.
--->
<cfset Caller.Doctor="Doctor " & Attributes.Name>

  4. Save the page as getmd.cfm.
  5. Open the file callingpage.cfm in your browser.

The calling page uses the getmd custom tag and displays the results.

Reviewing the code

The following table describes the code and its function:

Code

Description
<cfset NameYouEntered="Smith">

In the calling page, create a variable NameYouEntered and assign it the value Smith.
<cfoutput> Before you leave this page, you're #Variables.NameYouEntered#.<br> </cfoutput>

In the calling page, display the value of the NameYouEntered variable before calling the custom tag.
<cf_getmd Name="#NameYouEntered#">

In the calling page, call the getmd custom tag and pass it the Name attribute whose value is the value of the local variable NameYouEntered.
<cfparam name="Attributes.Name" default="Who">

The custom tag page normally gets the Name variable in the Attributes scope from the calling page. Assign it the value Who if the calling page did not pass an attribute.
<cfset Caller.Doctor="Doctor " & Attributes.Name>

In the custom tag page, create a variable called Doctor in the Caller scope so it exists in the calling page as a local variable.

Set its value to the concatenation of the string "Doctor" and the value of the Attributes.Name variable.
<cfoutput> You are now #Variables.Doctor#.<br> </cfoutput>

In the calling page, display the value of the Doctor variable returned by the custom tag page. (This example uses the Variables scope prefix to emphasize the fact that the variable is returned as a local variable.)