Description

Embeds references to ColdFusion pages in CFML. You can embed cfinclude tags recursively. For another way to encapsulate CFML, see cfmessagebox. (A ColdFusion page was formerly sometimes called a ColdFusion template or a template.)

Category

Syntax

<cfinclude 
template = "template name" 
runOnce = "true|false">

Note:

You can specify this tag's attributes in an attributeCollection attribute whose value is a structure. Specify the structure name in the attributeCollection attribute and use the tag's attribute names as structure keys.

See also

History

ColdFusion 11: The compileextforinclude attribute of the <cfapplication> tag affects the behavior of the <cfinclude> tag.

  • By default only files with the cfm and cfml extensions get compiled when included using the <cfinclude> tag. All other files when included using the cfinclude tag will not get compiled but their content will be statically included. No error will be thrown.
  • A server-level setting and an application-level setting has been added to specify a list of file extensions that can contain the CFM code. While processing the <cfinclude> tag, ColdFusion checks for this Application-level/server-level setting to decide whether to compile the content or to statically include it. The setting value is comma separated list of file extensions. If file extensions are specified at application-level, the server-level file extension list will be ignored and the application-level file extension list will be used.
  • Specifying a special value wildcard (*) in the file extension list makes the cfinclude tag to compile any file.
  • The server-level setting can be modified using the ColdFusion Administrator. The setting can be found at Server Settings > Settings page. A new key/tag attribute compileextforinclude added to the application cfc/cfm to specify this file extension list.

ColdFusion 10: Added the attribute {{runOnce}}

ColdFusion MX: Changed error behavior: if you use this tag to include a CFML page whose length is zero bytes, you do not get an error.

Attributes

Attribute

Req/Opt

Default

Description

template

Required

 

A logical path to a ColdFusion page.

runOnce

Optional

false

If set to true, the given template (if already processed) is not processed again for a given request.

Usage

ColdFusion searches for included files in the following locations:

  1. In the directory of the current page or a directory relative to the current page
  2. In directories mapped in the ColdFusion Administrator
    You cannot specify an absolute URL or file system path for the file to include. You can only use paths relative to the directory of the including page or a directory that is registered in the ColdFusion Administrator Mappings. The following cfinclude statements work, assuming that the myinclude.cfmfile exists in the specified directory:

<cfinclude template="myinclude.cfm"> 
<cfinclude template="../myinclude.cfm"> 
<cfinclude template="/CFIDE/debug/myinclude.cfm">

But the following do not work:

<cfinclude template="C:\ColdFusion\wwwroot\doccomments\myinclude.cfm">
<cfinclude template="http://localhost:8500/doccomments/myinclude.cfm">

The included file must be a syntactically correct and complete CFML page. For example, to output data from within the included page, you must have a cfoutput tag, including the end tag, on the included page, not the referring page. Similarly, you cannot span a cfif tag across the referring page and the included page; it must be complete within the included page.
You can specify a variable for the templateattribute, as the following example shows:

<cfset templatetouse="../header/header.cfm"> 
<cfinclude template="#templatetouse#">

Example

<!--- This example shows the use of cfinclude to paste CFML or HTML code into another page 
dynamically. ---> 

<h4>This example includes the dochome.htm page from the CFDOCS directory. The images do not 
display, because they are located in a separate directory. However, the page appears 
fully rendered within the contents of this page.</h4> 
<cfinclude template = "../cfdocs/dochome.htm">

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy