Attributes

Custom Tags should be built with flexibility. Essentially this means that the more attributes the tag takes, the more flexible and reusable it will be.

Earlier in the chapter, we discussed the sample Custom Tag used to query the database and output the data in an HTML table:

 <cf_queryprinttable datasource="dsn"  tablename="Employees"  columnnames="FirstName, LastName, Phone, Email"  columnheaders="First Name, Last Name, Phone Number, Email Address"  caption="All Company Employees"> 

The attributes we list here could be considered the absolute minimum needed to make the Custom Tag run properly. However, we could easily enhance the Custom Tag by adding more attributes for formatting issues:

 <cf_queryprinttable datasource="dsn"  tablename="Employees"  columnnames="FirstName, LastName, Phone, Email"  columnheaders="First Name, Last Name, Phone Number, Email Address"  caption="All Company Employees"  width="80%"  cellpadding="3"  cellspacing="0"  border="0"  headerbgcolor="blue"  databgcolor="yellow"> 

To make the query in the Custom Tag recognize the attributes, use the following:

 <cfquery name="MyQueryName"          datasource="#ATTRIBUTES.datasource#"> SELECT #ATTRIBUTES.ColumnNames# FROM #ATTRIBUTES.Tablename# </cfquery> 

CAUTION

The ATTRIBUTES. prefix is required when referencing values passed into a Custom Tag using attributes.

Notice that the only value that is hard-coded in the preceding query is the query name itself. Because the name of the query is being used only to output the values within the Custom Tag, it is not necessary for us to change it. Similarly, the rest of the code that displays the caption and the HTML table will also reference these attributes.

For this Custom Tag to work at all, we have to make sure that certain attributes are passed. datasource, tablename, columnnames, columnheaders, and caption are all required for the Custom Tag to function even on the most limited basis. You don't want the code to break in the event one of the attributes is not assigned, so you should implement some validation at the beginning of your Custom Tag to display an error message if a required attribute is missing. Such code might look like this:

 <cfif NOT IsDefined("ATTRIBUTES.datasource")>  <cfabort showerror="The datasource attribute is required."> </cfif> 

To perform validation, review Chapter 3, "Conditional Processing," and the discussion about custom validation in Chapter 9, "FORM Variables."

NOTE

The code uses <cfabort>, which will stop ColdFusion dead in its tracks. As soon as ColdFusion encounters this tag, it stops whatever it was doing. There might be instances in which this immediate halt is unnecessary or too abrupt. In these instances, consider using <cfexit> instead. This tag will stop the processing of the Custom Tag but will not hinder ColdFusion from finishing the processing of the calling page. Used outside of a Custom Tag, <cfexit> acts just like <cfabort>.

Now, after we've validated that all of the required tags are passed, we need to address the issue of the optional attributes. cellpadding, cellspacing, border, headerbgcolor, and databgcolor are all optional attributes that affect only the display of the HTML table. If they are used, the table should take on the declared physical characteristics. However, if they are not used, the Custom Tag should revert to default values for those attributes.

To set default values, you use the <cfparam> tag as follows:

 <cfparam name="ATTRIBUTES.border" default="0"> 

<cfparam> was introduced in Chapter 2, "Working with Variables and Expressions."

Notice that the value of the NAME attribute is ATTRIBUTES.borderwith the ATTRIBUTES. scope prefix. This simply states that you are creating a default value specifically for the border attribute.