<cfinclude> is the simplest way to reuse CFML: it drops another file's content directly into the current page, as if that code had been typed right there. It's a genuinely server-side thing, worth being precise about — <cfinclude> processes and injects a file's contents into the page before anything reaches the browser, which is completely different from an HTML <link> or <a> tag, which just tells the browser to separately fetch or navigate to something on its own.
Learning Objectives
After completing this lesson, you'll be able to:
- Use <cfinclude> to share a header, footer, or any repeated block across pages.
- Explain how an included file's variable scope relates to the page that includes it.
- Know cfinclude's real limitations, and when to reach for something else instead.
A Simple Example: Shared Header
<cfoutput>
<header>
<h1>#application.siteName#</h1>
</header>
</cfoutput><cfscript> include "header.cfm"; </cfscript> <p>Page content goes here.</p>
<cfinclude template="header.cfm"> <p>Page content goes here.</p>
include "header.cfm" is the CFScript equivalent of <cfinclude template="header.cfm">, added in ColdFusion 9.
Path Resolution
| Path style | Resolved from |
|---|---|
| Relative ("header.cfm") | The calling page's own directory |
| Leading slash ("/layout/header.cfm") | A mapping configured in the ColdFusion Administrator |
It Shares the Calling Page's Scope
This is the single most important thing to understand about <cfinclude>: the included file runs inside the calling page's own Variables scope. It can read every variable the calling page has already set, and anything it sets itself becomes visible to the calling page too, exactly like it was written inline.
<cfscript> message = "Hello from the included file!"; </cfscript>
This is exactly why an included header shouldn't reuse a generic variable name like data or result — it can silently overwrite something the calling page already set, since there's no isolation between them.
The runonce Attribute (ColdFusion 10+)
<cfinclude template="expensive-setup.cfm" runonce="true">
If the same template gets included more than once during a single request (directly or indirectly through other includes), runonce="true" skips processing it again after the first time.
Real Limitations
- Can't pass parameters — an included file only ever sees whatever's already in the calling page's scope, there's no argument-passing mechanism like a function or custom tag has.
- Can't cross code block boundaries — you can't open a <cfoutput> block in one file and close it in the included file.
- Can't include itself — directly or through a chain of other includes, since that creates infinite recursion.
Common Beginner Mistakes
Expecting to pass data into an included file like a function argument
cfinclude has no parameter mechanism at all — set whatever the included file needs as a regular variable beforehand, in the same scope, before the include runs.
Using a generic variable name inside a frequently-included file
Since the include shares scope with every page that uses it, a generic name like data or result risks silently colliding with something the calling page already has. Prefix included files' variables distinctly.
Trying to open a CFML block in the calling page and close it in the include
Code block structures (like <cfoutput>...</cfoutput>) can't span across an include boundary — each file's blocks have to be self-contained.
Best Practices
- Reach for cfinclude for static or mostly-static shared content — headers, footers, config setup — not for anything that needs its own isolated variables or parameters.
- Use runonce="true" for setup code that might get included multiple times in one request through different code paths.
- When a reusable block genuinely needs its own isolated scope or parameters, use a custom tag or CFC instead — covered in the next lessons.
Interview Questions
What scope does an included file run in?
The same Variables scope as the calling page — it isn't isolated, and can both read the calling page's variables and set new ones the calling page can then see.
Can cfinclude pass parameters to the file it includes?
No — cfinclude has no argument-passing mechanism. Anything the included file needs has to already be set as a variable in the shared scope beforehand.
What does runonce="true" do?
Skips re-processing the same template if it gets included more than once during a single request, added in ColdFusion 10.
Is the template attribute required on <cfinclude>?
Yes — template is cfinclude's only real attribute (besides runonce), and it's required. Without it, there's nothing to tell ColdFusion which file to include.
What's the actual difference between <cfinclude> and an HTML <link> tag?
cfinclude is a server-side operation — it processes and injects the included file's content into the page before anything is ever sent to the browser. An HTML <link> (or <a>) tag does nothing server-side at all; it's an instruction the browser itself acts on, separately fetching a resource or navigating to a new page after the original page has already been delivered.
If cfinclude and cfmodule can both reuse code, what actually decides which one to use?
Whether the reused block needs isolation and parameters. cfinclude is simpler but shares the calling page's scope completely with no parameter mechanism — fine for static shared content like a header. cfmodule (or a plain custom tag) runs in its own scope and accepts real attributes, which is what you want the moment the reused block needs its own inputs or shouldn't be able to touch the calling page's variables.
Summary
In this lesson, you used <cfinclude> to share code across pages, covered how it shares the calling page's scope rather than running in isolation, and its real limitations — no parameters, no crossing code blocks, no self-inclusion.
What's Next?
The next lesson covers Custom Tags — reusable code that runs in its own isolated scope, with real parameter passing in and out.