View comments | RSS feed

cfinclude

Description

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

Category

Flow-control tags, Page processing tags

Syntax

<cfinclude 
   template = "template_name">

See also

cfcache, cfflush, cfheader, cfhtmlhead, cfsetting, cfsilent

History

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.

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 MX 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 MX Administrator Mappings. The following cfinclude statements will work, assuming that the myinclude.cfm file exists in the specified directory:

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

But these will not work:

<cfinclude template="C:\CFusionMX7\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 template attribute, 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">

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

Version 7

Comments


Laverda668 said on Sep 26, 2005 at 9:33 PM :
This method of using a variable to set the template path does not seem
work in a page that is being included. i.e. you can't nest includes with
this method.
cf.Objective said on Dec 29, 2006 at 3:28 PM :
The documentation here makes for some confusion.

First of all, there's some debate about what terms mean what kinds of
paths.

Some use the following terminology:
relative path: anything starting with a file or directory name, ./, ../, or /
where the / path is commonly called "webroot relative"

absolute path: on Windows something starting with a drive letter, on
*NIX, something starting with a / character (the root of the UNIX box's
disk systems).

For others, especially those with an Apache background, the following
"lexicon" is preferred (and actualy makes for a much clearer, cleaner
discussion):

relative path: anything starting with a filename, ./ or ../

absolute path: anything starting with a /, working from the webroot down
the directory tree... this is what Apache calls an "absolute path" and most
others call a "webroot relative path"

physical path: anything starting with a drive letter on Windows or a / on
*NIX, meaning the root of the server's disk systems.

That little bit of clarification out of the way, the cfinclude documentation
indicates that what Apache users call an "absolute path" cannot be done
without a mapping. THIS IS NOT THE CASE. Any cfinclude using a path
of "/CFIDE..." is guaranteed to work on any version from 6.1 up, with no
mappings defined whatsoever, including those who have wisely
removed the "/" mapping from the CF Administrator.

So to use webroot relative or absolute paths (in the Apache sense), you
need no mappings UNLESS the file you wish to cfinclude lies outside
the webroot:

This will work, with zero mappings listed in the Administrator
/=c:\inetpub\wwwroot
/modelglue = c:\inetpub\wwwroot\modelglue
<cfinclude template="/modelglue/modelglue.cfm" />

This will NOT work without a mapping of /modelglue pointing at the
correct folder:
/=c:\inetpub\wwwroot
/modelglue = c:\inetpub\external\modelglue
<cfinclude template="/modelglue/modelglue.cfm" />

 

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

Current page: http://livedocs.adobe.com/coldfusion/7/htmldocs/00000277.htm