Overview

This guide presents a ready-to-use downloadable package of ColdFusion PDF generation examples built around the CFML tag. The resource is designed to help developers quickly produce high-quality PDFs (invoices, reports, certificates, statements) from HTML and CSS, while learning Best practices for headers/footers, page numbers, page breaks, bookmarks, encryption, fonts, streaming to the browser, and more.

The examples are written for Adobe ColdFusion and compatible with Lucee CFML (with the PDF extension). Whether you’re setting up HTML-to-PDF for the first time or optimizing an existing implementation, these samples will save time, reduce trial-and-error, and improve reliability.

---

What You’ll Get

The downloadable ZIP (cfdocument-examples.zip) contains a complete, runnable set of CFML examples:

• Index launcher to run each demo one by one
• Standalone examples that demonstrate a single concept at a time
• HTML/CSS templates for invoices, reports, and statements
• CFML utility functions for streaming PDFs (cfheader/cfcontent)
• Font examples (embedding, custom fonts)
• Watermark and merge examples using cfpdf
• Documentation notes and Troubleshooting tips

File structure:

• /cfdocument-examples/
  • index.cfm
  • /examples/
    • basic.cfm
    • header-footer.cfm
    • pagebreaks-sections.cfm
    • toc-bookmarks.cfm
    • stream-browser.cfm
    • Security-encryption.cfm
    • fonts-and-css.cfm
    • watermark-cfpdf.cfm
    • Performance-notes.cfm
  • /assets/
    • /css/
      • base.css
      • invoice.css
    • /images/
      • logo.png
      • watermark.png
    • /fonts/
      • SourceSansPro-Regular.ttf
      • SourceSansPro-Bold.ttf
  • /output/ (generated PDFs)
  • README.md

---

Supported Environments

A quick overview of supported platforms and dependencies:

• Adobe ColdFusion: 2018, 2021, 2023
• Lucee CFML: 5.3+ with PDF Extension and/or wkhtmltopdf extension
• Operating Systems: Windows, Linux, macOS
• Java: Use the JDK/JRE bundled with your engine unless your admin recommends otherwise
• Permissions: Filesystem write access to the /output directory; ability to load local images and fonts (localurl=”yes”)

Tip: For Lucee CFML, install the “PDF” extension via the Lucee Admin, or use the wkhtmltopdf extension for advanced CSS/HTML support.

---

Benefits

• Faster adoption: Jump straight into working examples instead of starting from scratch.
• Consistent output: Demonstrates headers/footers, page numbers, and page sizing that print cleanly.
• Production patterns: Covers streaming PDFs, bookmarks/TOC, encryption/permissions, and font embedding.
• Performance tips: Learn how to reduce memory usage, control image quality, and speed up rendering.
• Cross-engine notes: Side-by-side pointers for Adobe ColdFusion and Lucee CFML.

---

How to Install and Run

Follow these steps to get started:

1. Unzip the package

• Extract cfdocument-examples.zip into your CFML webroot or any folder mapped in your server.

2. Configure a mapping (if needed)

• If not placing under the webroot, create a mapping in your CF Administrator/Lucee Admin pointing to /cfdocument-examples.

3. Verify write permissions

• Ensure the server user can write to cfdocument-examples/output/.

4. Confirm PDF capabilities

• Adobe ColdFusion: works out-of-the-box.
• Lucee: Install the “PDF” extension (Server Admin > Extensions) or wkhtmltopdf. Restart if prompted.

5. Open the index

• Navigate to http(s)://your-host/cfdocument-examples/index.cfm
• Click any example link to render the PDF and view source code.

---

How to Use the Examples

• View a sample: Click an example name; a PDF will be saved into /output and optionally streamed to the browser.
• Inspect the code: Open the corresponding /examples/*.cfm file and copy relevant snippets into your application.
• Customize: Replace the logo, fonts, and CSS to match your brand. Adjust attributes for page size, margins, orientation, and Security.

---

Core Examples and Code Highlights

Basic HTML-to-PDF (with headers and footers)

• Demonstrates basic usage, margins, embedded CSS, server-side headers, and page numbering.

Code:
<cfdocument format=”PDF”
filename=”#expandPath(‘../output/basic.pdf’)#”
overwrite=”true”
pagetype=”A4″
orientation=”portrait”
margintop=”0.75″
marginbottom=”0.75″
marginleft=”0.6″
marginright=”0.6″
fontembed=”yes”
localurl=”yes”
bookmarks=”no”>

<cfdocumentitem type="header">
    <cfoutput>
        <div style="font-family: Source Sans Pro, sans-serif; font-size: 11px; color: #666;">
            Example Co. • Quarterly Report
        </div>
    </cfoutput>
</cfdocumentitem>

<cfdocumentitem type="footer">
    <cfoutput>
        <div style="font-family: Source Sans Pro, sans-serif; font-size: 11px; color: #666; text-align:right;">
            Page #cfdocument.currentpagenumber# of #cfdocument.totalpagecount#
        </div>
    </cfoutput>
</cfdocumentitem>

<style>
  @page { size: A4; margin: 0.75in; }
  h1 { font-size: 20px; margin-bottom: 0.2in; }
  p { line-height: 1.4; }
  img.logo { width: 160px; }
</style>

<h1>Basic PDF Example</h1>
<img class="logo" src="../assets/images/logo.png" alt="Logo">
<p>This PDF is generated by the CFML <cfdocument> tag using embedded styles.</p>

Notes:

• Use localurl=”yes” to load local images and CSS.
• fontembed=”yes” ensures fonts are included so output looks the same on any machine.

---

Page Breaks and Sections

• Shows controlled pagination and mixed orientation via cfdocumentsection and cfdocumentpagebreak.

Code:

Portrait Section

Content in portrait.

<cfdocumentsection orientation="landscape">
    <h2>Landscape Section</h2>
    <p>Wide tables or charts fit better here.</p>
</cfdocumentsection>

---

Bookmarks and Table of Contents

• Automatically creates PDF bookmarks from heading tags (h1–h6) by setting bookmarks=”yes”.

Code:
<cfdocument format=”PDF”
filename=”#expandPath(‘../output/toc-bookmarks.pdf’)#”
overwrite=”true”
pagetype=”A4″
localurl=”yes”
bookmarks=”yes”>

<h1>Executive Summary</h1>
<p>...</p>

<h1>Financials</h1>
<h2>Revenue</h2>
<p>...</p>
<h2>Expenses</h2>
<p>...</p>

Tip: Use semantic headings consistently to build a clean bookmark tree.

---

Streaming a PDF to the Browser

• Generate the PDF into a variable, then stream with cfheader/cfcontent (useful for APIs, dynamic names, or avoiding filesystem writes).

Code:

Streaming Demo

This PDF will be sent directly to the browser.

Note: Use Content-Disposition: attachment to force Download.

---

Securing PDFs (Encryption and Permissions)

• Set user/owner passwords and restrict operations (printing, copying) using cfdocument attributes.

Code:
<cfdocument format=”PDF”
filename=”#expandPath(‘../output/secure.pdf’)#”
overwrite=”true”
encryption=”128-bit”
permissions=”AllowPrinting,AllowCopying”
userpassword=”viewer123″
ownerpassword=”ownerSecret”
pagetype=”A4″>

Protected Document

Only allowed actions are enabled.

---

Adding a Watermark (with cfpdf)

• Combine cfdocument to generate the base PDF, then apply a semi-transparent text or image watermark using cfpdf.

Code:

Watermark Demo

<cfpdf action=”addwatermark”
source=”#expandPath(‘../output/watermark-source.pdf’)#”
destination=”#expandPath(‘../output/watermark-final.pdf’)#”
text=”CONFIDENTIAL”
foreground=”yes”
rotation=”45″
opacity=”0.15″
font=”Helvetica”
fontsize=”60″/>

Result: watermark-final.pdf contains the overlayed watermark.

---

Custom Fonts and CSS

• Demonstrates embedding TTF fonts and referencing external CSS files.

Key points:

• Place TTF files under /assets/fonts
• Reference fonts via @font-face and set font-family
• Keep localurl=”yes”

Code (snippet from fonts-and-css.cfm):

Font Embedding

This text uses an embedded custom font.

---

Best practices

• Keep HTML simple: Prefer Server-side rendering and avoid heavy client-side JavaScript (not executed in cfdocument).
• Use semantic headings: Enable bookmarks=”yes” to auto-build a TOC from h1–h6.
• Control page breaks: Use or CSS page-break-before/after for predictable pagination.
• Separate sections: for orientation changes and different margins.
• Embed fonts: Use fontembed=”yes” and @font-face to match brand typography across machines.
• Optimize images: Resize/compress images before rendering to reduce memory and file size.
• Stream when appropriate: Use the name attribute and cfcontent to avoid intermediate disk writes in high-throughput endpoints.
• Secure sensitive PDFs: Use encryption, set permissions, and owner/user passwords.
• Test across engines: Minor rendering differences can occur between Adobe ColdFusion and Lucee; validate key documents on your target platform.

---

Performance Tips

• Reduce DOM complexity: Flatten deeply nested tables; consider flexbox-style layouts that render predictably.
• External assets: Enable localurl=”yes” and ensure assets reside on fast storage to avoid timeouts.
• Cache templates: Precompile or cache HTML fragments where possible to reduce server work.
• Fonts: Embed only the fonts you need; too many large TTFs increase file size and render time.
• Pagination: Split very large documents into logical sections; if needed, generate in chunks and merge with cfpdf.

---

Troubleshooting

• Images don’t show: Confirm localurl=”yes” and paths are correct and accessible by the CF service user.
• Fonts look wrong: Ensure @font-face URLs are reachable and fontembed=”yes” is set; clear any server-level font caches.
• Cut-off content: Increase page margins, avoid position: fixed elements, and insert where needed.
• Bookmarks missing: Ensure bookmarks=”yes” and that headings (h1–h6) exist in the content.
• Streaming issues: Use cfheader + cfcontent and ensure you didn’t write output before the binary response (check whitespace/BOM).

---

Pros and cons

• Pros:
  • Rapid adoption with copy-pasteable CFML.
  • Covers most real-world use cases (invoices, statements, reports).
  • Includes security and streaming patterns out-of-the-box.
• Cons:
  • HTML/CSS rendering in cfdocument is not a full browser engine; complex layouts may require simplification or wkhtmltopdf.
  • Large documents can be memory-intensive; Optimization is necessary.

---

Common Use Cases

• Invoices and billing statements with branded headers/footers and page totals
• Financial and operational reports with bookmarks and table of contents
• Certificates, tickets, and labels with embedded fonts and watermarks
• Export-to-PDF Features in admin dashboards using streaming endpoints

---

Key Takeaways

• is a powerful CFML tag for **HTML-to-PDF** conversion with headers, footers, pagination, and security.
• The provided examples demonstrate production-grade patterns including streaming, bookmarks, encryption, watermarks, and font embedding.
• Use cfdocumentsection and cfdocumentpagebreak for precise pagination and mixed page orientations.
• For Lucee CFML, install the PDF extension or wkhtmltopdf to ensure robust rendering support.
• Optimize images, simplify HTML, and embed only necessary fonts for performance and file size control.

---

FAQ

How do I force the browser to Download instead of viewing inline?

Set a Content-Disposition header to attachment and stream the PDF variable:

Why are my local images not appearing in the PDF?

Use localurl=”yes” in , ensure the image paths are correct and readable by the ColdFusion/Lucee service account, and prefer absolute or expandPath() locations during troubleshooting.

Can I merge multiple PDFs after generating them?

Yes. Use cfpdf action=”merge” to join multiple source PDFs:

How can I improve rendering fidelity for complex CSS?

Keep the HTML/CSS simpler, avoid heavy JavaScript, and consider the wkhtmltopdf extension (Lucee) if you need more browser-like rendering for advanced CSS Features.

Do I need to embed fonts?

Embed fonts (fontembed=”yes”) when you rely on brand-specific or non-standard fonts. This ensures consistent visual output across different machines and viewers.