View comments | RSS feed
Contents > CFML Reference > ColdFusion Tags > cfmodule PreviousNext

cfmodule

Invokes a custom tag for use in ColdFusion application pages. This tag processes custom tag name conflicts.

For more information, see Creating and Using Custom CFML Tags in Developing ColdFusion MX Applications.

Application framework tags

<cfmodule 
   template = "path"
   name = "tag_name"
   attributeCollection = "collection_structure"
   attribute_name1 = "valuea"
   attribute_name2 = "valueb"
   ...>

cfapplication, cfassociate, cflock, Creating and Using Custom CFML Tags in Developing ColdFusion MX Applications

ColdFusion MX: Changed behavior when using this tag within a custom tag: if the attribute_name parameter is the same as a key element within the attributeCollection parameter, ColdFusion now uses the name value that is within the attributeCollection parameter. (Earlier releases did not process this consistently.)

Attribute

Req/Opt

Default

Description

template

Required unless name attribute is used

 

Mutually exclusive with the name attribute. A path to the page that implements the tag.

  • Relative path: expanded from the current page
  • Absolute path: expanded using ColdFusion mapping

A physical path is not valid.

name

Required unless template attribute is used

 

Mutually exclusive with the template attribute. A custom tag name, in the form "Name.Name.Name..." Identifies subdirectory, under the ColdFusion tag root directory, that contains custom tag page. For example (Windows format): 

<cfmodule name = "macromedia.Forums40.
GetUserOptions">

This identifies the page GetUserOptions.cfm in the directory CustomTags\macromedia\Forums40 under the ColdFusion root directory.

attributeCollection

Optional

 

Structure. A collection of key-value pairs that represent attribute names and values. You can specify multiple key-value pairs. You can specify this attribute only once.

attribute_name

Optional

 

Attribute for a custom tag. You can include multiple instances of this attribute to specify the parameters of a custom tag.

To name a ColdFusion page that contains the custom tag definition, including its path, use the template attribute. To refer to the custom tag in the ColdFusion installation directory, using dot notation to indicate its location, use the name attribute.

On UNIX systems, ColdFusion searches first for a file with a name that matches the name attribute, but is all lower case. If it does not find the file, it looks for a file name that matches the attribute with identical character casing.

You can use attributeCollection and attribute_name in the same call.

Within the custom tag code, the attributes passed with attributeCollection are saved as independent attribute values, with no indication that they are grouped into a structure by the custom tag's caller.

Similarly, if the custom tag uses a cfassociate tag to save its attributes, the attributes passed with attributeCollection are saved as independent attribute values, with no indication that they are grouped into a structure by the custom tag's caller.

<h3>cfmodule Example</h3>
<p>This view-only example shows use of cfmodule to call a custom tag inline.</p>
<p>This example uses a sample custom tag that is saved in myTag.cfm in 
the snippets directory. You can also save ColdFusion custom tags in the Cfusion\CustomTags directory.
<cfset attrCollection1 = StructNew()>
<cfparam name="attrCollection1.value1" default="22">
<cfparam name="attrCollection1.value2" default="45">
<cfparam name="attrcollection1.value3" default="88">
<!--- Call the tag with CFMODULE with Name--->
<cfmodule
   Template="myTag.cfm"
   X="3"
   attributeCollection=#attrCollection1#
   Y="4">
<!--- show the code --->
<HR size="2" color="#0000A0">
<P>Here is one way in which to invoke the custom tag,
using the TEMPLATE attribute.</P>
<cfoutput>#HTMLCodeFormat(" <CFMODULE
   Template=""myTag.cfm""
   X=3
   attributeCollection=##attrCollection1##
   Y=4>")#
</cfoutput>
<P>The result: <cfoutput>#result#</cfoutput>
<!--- Call the tag with CFMODULE with Name--->
<!---
   <CFMODULE
      Name="myTag"
      X="3"
      attributeCollection=#attrCollection1#
      Y="4">
--->
<!--- show the code --->
<HR size="2" color="#0000A0">
<P>Here is another way to invoke the custom tag,
using the NAME attribute.</P>
<cfoutput>#HTMLCodeFormat(" <CFMODULE
      NAME='myTag'
      X=3
      attributeCollection=##attrCollection1##
      Y=4>")#
</cfoutput>
<P>The result: <cfoutput>#result#</cfoutput>
<!--- Call the tag using the short cut notation --->
<!---
<CF_myTag
   X="3"
   attributeCollection=#attrCollection1#
   Y="4">
--->


<!--- show the code --->   
<p>Here is the short cut to invoking the same tag.</p>
<cfoutput>#HTMLCodeFormat(   "<cf_mytag 
   x = 3 
   attributeCollection = ##attrcollection1## 
   y = 4>")#
</cfoutput>   
<p>The result: <cfoutput>#result#</cfoutput></p>
Contents > CFML Reference > ColdFusion Tags > cfmodule PreviousNext

ColdFusion 9 | ColdFusion 8 | ColdFusion MX 7 | ColdFusion MX 6.1 | ColdFusion MX | Forums | Developer Center | Bug Reporting

Version 6.1

Comments are no longer accepted for ColdFusion MX 6.1. ColdFusion 8 is the current version.

Comments


anclarke said on Mar 4, 2005 at 3:53 PM :
If you put a trailing slash at the end of your cfmodule call, a la <cfmodule template="zyz.cfm" />, the template will be run twice. If you take away the / at the end, it will only be run once. This is with MX 6.1 on Windows.
Candice0105 said on Aug 14, 2005 at 1:10 PM :
what anclarke said is true for any custom tag.
stopforgetting said on Sep 6, 2005 at 5:23 PM :
Actually, it doesn't QUITE run twice: It runs once when ThisTag.ExecutionMode is "start" and once when ThisTag.ExecutionMode is "end".

This is handy if you want to nest tags and have something happen when the opening tag is hit, and something helse happen when the closing tag is hit.

If you want to suppress the double-run, wrap your code in something like <CFIF thistag.executionmode="start"> .. your code .. </cfif>
and then it will only run once.
hope.martin said on Mar 9, 2006 at 11:36 AM :
Don't forget that the conditional "ThisTag.ExecutionMode" goes around the code in your custom tag. Not on the page you're using cfmodule! Maybe I'm the only one who made that mistake? ;)

 

RSS feed | Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/coldfusion/6.1/htmldocs/tags-pb4.htm