Adobe ColdFusion 8

Including pages with the cfinclude tag

The cfinclude tag adds the contents of a ColdFusion page to another ColdFusion page, as if the code on the included page were part of the page that uses the cfinclude tag. It lets you pursue a "write once use multiple times" strategy for ColdFusion elements that you incorporate in multiple pages. Instead of copying and maintaining the same code on multiple pages, you can store the code in one page and then refer to it in many pages. For example, the cfinclude tag is commonly used to put a header and footer on multiple pages. This way, if you change the header or footer design, you only change the contents of a single file.

The model of an included page is that it is part of your page; it just resides in a separate file. The cfinclude tag cannot pass parameters to the included page, but the included page has access to all the variables on the page that includes it. The following image shows this model:

Using the cfinclude tag

When you use the cfinclude tag to include one ColdFusion page in another ColdFusion page, the page that includes another page is referred to as the calling page. When ColdFusion encounters a cfinclude tag it replaces the tag on the calling page with the output from processing the included page. The included page can also set variables in the calling page.

The following line shows a sample cfinclude tag: 

<cfinclude template = "header.cfm">

Note: You cannot break CFML code blocks across pages. For example, if you open a cfoutput block in a ColdFusion page, you must close the block on the same page; you cannot include the closing portion of the block in an included page.

ColdFusion searches for included files as follows:

  • The template attribute specifies a path relative to the directory of the calling page.
  • If the template value is prefixed with a forward slash (/), ColdFusion searches for the included file in directories that you specify on the Mappings page of the ColdFusion Administrator.

Important: A page must not include itself. Doing so causes an infinite processing loop, and you must stop the ColdFusion server to resolve the problem.

Include code in a calling page

  1. Create a ColdFusion page named header.cfm that displays your company's logo. Your page can consist of just the following lines, or it can include many lines to define an entire header:
    <img src="mylogo.gif">
<br>

    (For this example to work, you must also put your company's logo as a GIF file in the same directory as the header.cfm file.)

  2. Create a ColdFusion page with the following content: 
    <html>
<head>
    <title>Test for Include</title>
</head>
<body>
    <cfinclude template="header.cfm">
</body>
</html>

  3. Save the file as includeheader.cfm and view it in a browser.

The header should appear along with the logo.

Recommended uses

Consider using the cfinclude tag in the following cases:

  • For page headers and footers
  • To divide a large page into multiple logical chunks that are easier to understand and manage
  • For large "snippets" of code that are used in many places but do not require parameters or fit into the model of a function or tag