cfdocumentitem is cfdocument's sub-tag for three specific jobs: forcing a page break at a specific point, and defining a running header or footer that repeats on every generated page.
Learning Objectives
After completing this lesson, you'll be able to:
- Force a page break at a specific point with cfdocumentitem.
- Build a running header/footer using the page-number scope variables only available inside it.
- Explain what evalAtPrint actually controls.
How cfdocumentitem Fits Into cfdocument
cfdocument Renders the Content
cfdocumentitem Marks a Header/Footer/Page Break
Applied to Every Generated Page
The type Values
| type | Does |
|---|---|
| pagebreak | Starts a new page at the location of the tag |
| header | Uses the content between the tags as the running header on every page |
| footer | Uses the content between the tags as the running footer on every page |
| bookmark (Lucee) | Adds a PDF bookmark, named via the name attribute; not documented on Adobe's cfdocumentitem |
A Basic Page Break
<cfdocument format="pdf">
<h1>Section One</h1>
<p>Content for the first section.</p>
<cfdocumentitem type="pagebreak">
<h1>Section Two</h1>
<p>Content for the second section.</p>
</cfdocument>cfdocumentitem(type = "pagebreak");
A Real Example: A Footer With Page Numbers
cfdocument.currentpagenumber, cfdocument.totalpagecount, cfdocument.currentsectionpagenumber, and cfdocument.totalsectionpagecount are scope variables that only exist inside a cfdocumentitem tag, they're not accessible anywhere else in the document, and they're read through the cfdocument prefix, not as bare variable names.
<cfdocument format="pdf">
<h1>Annual Report</h1>
<p>Report content goes here.</p>
<cfdocumentitem type="footer">
<cfoutput>Page #cfdocument.currentpagenumber# of #cfdocument.totalpagecount#</cfoutput>
</cfdocumentitem>
</cfdocument>cfdocumentitem(type = "footer") {
writeOutput("Page " & cfdocument.currentpagenumber & " of " & cfdocument.totalpagecount);
}evalAtPrint: Why It Matters for a Header/Footer
On Adobe ColdFusion, evalAtPrint (default false) controls whether expressions inside cfdocumentitem are evaluated at print time (once per page) rather than once, up front, a header or footer showing the page number genuinely needs a fresh value on every page. Lucee's own documentation marks evalAtPrint as unimplemented on its documentitem tag, setting it there has no effect.
Common Beginner Mistakes
Trying to use currentpagenumber or totalpagecount outside of cfdocumentitem
Those scope variables only exist inside a cfdocumentitem tag, they aren't accessible in the rest of the document's content.
Putting substantial content inside a header or footer
It's re-rendered on every single generated page, keep it minimal, page numbers, a short title, a date, not a large block of content.
Expecting one cfdocumentitem type="header" to apply different margins to just part of the document
That's what cfdocumentsection is for, dividing the output into sections with their own margins and headers/footers, not something cfdocumentitem alone handles.
Best Practices
- Keep header/footer content minimal, it's re-rendered on every page of the output.
- Use the page-number scope variables (currentpagenumber, totalpagecount) for pagination text, they're only available here.
- Reach for cfdocumentsection instead of cfdocumentitem when different parts of the document genuinely need different margins or headers.
Interview Questions
What are cfdocumentitem's three type values, and what does each do?
pagebreak starts a new page at that point, header and footer define running content that repeats on every generated page.
Where can currentpagenumber and totalpagecount actually be used?
Only inside a cfdocumentitem tag, they're scope variables specific to that context and aren't available elsewhere in the document.
Why does a page-numbered footer need something like evalAtPrint's behavior to work correctly?
The page number is different on every page, the expression has to be evaluated fresh at print time for each page it appears on, not calculated once up front.
Summary
In this lesson, you forced a page break with cfdocumentitem, built a page-numbered footer using scope variables only available inside it, and covered what evalAtPrint's per-page evaluation actually enables.
What's Next?
The next lesson covers cfpdf: manipulating a PDF that already exists, merging, watermarking, protecting, and extracting content.