cfmodule

Description

Invokes a custom tag for use in ColdFusion application pages. The cfmodule tag can help deal with custom tag name conflicts.

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

Syntax

<cfmodule template = "template"
  name = "tag_name"
  attributeCollection = "collection_structure"
  attribute_name1 = "value"
  attribute_name2 = "value"
  ...>

Attributes

Attribute

Description

template
Used in place of name, defines a path to the application page (.cfm file) that implements the tag. Relative paths are expanded from the current page. Physical paths are not allowed. Absolute paths are expanded using the ColdFusion mappings.

name
Used in place of template, defines the name of the custom tag, in the form "Name.Name.Name..." Identifies a subdirectory that contains the custom tag page under the root directory for ColdFusion custom tags. For example:
<cfmodule name = "macromedia.Forums40.GetUserOptions">
Identifies the page GetUserOptions.cfm in the directory CustomTags\macromedia\Forums40 under the root directory of the ColdFusion installation.

attributeCollection
Optional. A structure that contains a collection of key-value pairs that represent attribute names and their values. You can specify as many key-value pairs as needed. You can specify the attributeCollection attribute only once. See Usage for more information.

attribute_name
Optional. Attributes for a custom tag to use. You can use as many attributes as needed to specify the parameters of a custom tag.

Attribute	Description
template	Used in place of `name`, defines a path to the application page (.cfm file) that implements the tag. Relative paths are expanded from the current page. Physical paths are not allowed. Absolute paths are expanded using the ColdFusion mappings.
name	Used in place of `template`, defines the name of the custom tag, in the form "`Name.Name.Name...`" Identifies a subdirectory that contains the custom tag page under the root directory for ColdFusion custom tags. For example: <cfmodule name = "macromedia.Forums40.GetUserOptions"> Identifies the page `GetUserOptions.cfm` in the directory `CustomTags\macromedia\Forums40` under the root directory of the ColdFusion installation.
attributeCollection	Optional. A structure that contains a collection of key-value pairs that represent attribute names and their values. You can specify as many key-value pairs as needed. You can specify the `attributeCollection` attribute only once. See Usage for more information.
attribute_name	Optional. Attributes for a custom tag to use. You can use as many attributes as needed to specify the parameters of a custom tag.

Usage

You can use attributeCollection and attribute in the same call.

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

Likewise, 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 the attributes are grouped into a structure by the custom tag's caller.

Example

<!--- This example shows the use of cfmodule --->
<html>
<head>
<title>cfmodule Example</title>
</head>

<body>
<h3>cfmodule Example</h3>

<p>
This example shows the use of cfmodule to call a sample custom 
tag inline.
</p>
<p>
This example makes use of a sample custom tag that has been saved
in the file myTag.cfm in the snippets directory. You can also
save ColdFusion custom tags in the Cfusion\CustomTags
directory. For more information about using Custom Tags, please
refer to <i>Developing Web Applications</i>.
</p>
<!--- show the code in the custom tag--->  
<p>Here is the code in the custom tag.</p>
<cfoutput>#HTMLCodeFormat("<cfset x = attributes.x>
<cfset y = attributes.y>
<cfset a = attributes.value1>
<cfset b = attributes.value2>
<cfset c = attributes.value3>
<cfset caller.result = x + y + a + b + c>")#
</cfoutput>
<!--- end sample tag --->

<cfset attrcollection1 = structnew()>
<cfset attrcollection1.value1 = 22>
<cfset attrcollection1.value2 = 45>
<cfset attrcollection1.value3 = 88>

<!--- Call the tag with cfmodule with Name--->
<cfmodule 
  template = "..\snippets\myTag.cfm"
  x = "3"
  attributeCollection = #attrcollection1# 
  y = "4">

<!--- show the code --->
<p>Here is one way in which to invoke the custom tag, 
using the template attribute.</p>
<cfoutput>#HTMLCodeFormat(  "<cfmodule
  template = ""..\snippets\mytag.cfm""
  x = 3
  attributeCollection = ##attrcollection1##
  y = 4>")#
</cfoutput>  
<p>The result: <cfoutput>#result#</cfoutput> </p>  

<!--- Call the tag with cfmodule with Name--->
<cfmodule 
  name = "myTag"
  x = "3"
  attributeCollection = #attrcollection1# 
  y = "4">

<!--- show the code --->
<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>  

</body>
</html>