Definition

The ColdFusion PDF generation feature is a set of built‑in tags, functions, and services in Adobe ColdFusion that let you create and manipulate PDF documents on the server. Using CFML (ColdFusion Markup Language), developers can convert HTML to PDF, render dynamic data into printable documents, add headers and footers, apply passwords and permissions, merge or split PDFs, and add watermarks—all programmatically and at scale. It’s commonly used for automated reports, invoices, statements, and downloadable content.

---

How It Works

Core tags and components

• cfdocument: Generates a PDF (or other formats) directly from HTML and CFML output. Supports headers/footers, page size, orientation, and basic CSS.
• cfhtmltopdf: Generates PDFs from HTML with improved CSS/JS support (more faithful rendering for Modern web pages).
• cfpdf: Manipulates existing PDFs (merge, split, protect, add/remove pages, watermark, extract text, set metadata).
• cfpdfform: Works with PDF forms (read/populate fields), if you’re dealing with AcroForm-like PDFs.
• cfcontent: Streams a binary variable or a file to the browser as application/pdf.
• CFDocumentItem/CFHTMLToPDFItem: Used to define repeatable headers and footers.

These are complemented by ColdFusion’s server-side processing: you fetch data (e.g., from a database), combine it with templates, and emit a finished PDF.

Rendering pipeline (high level)

1. Template resolution: ColdFusion executes CFML and composes HTML output.
2. HTML/CSS to PDF conversion:
   • cfdocument uses its internal engine (historically based on iText and an HTML renderer) to transform markup to PDF.
   • cfhtmltopdf uses a modern HTML renderer to better support advanced CSS and JavaScript.
3. Post-processing (optional): Use cfpdf to merge, protect, watermark, change metadata, or extract text.
4. Delivery: Save the file to disk or stream it to the browser or an API client.

Output options

• Directly stream to the client by omitting a destination/filename.
• Save to a file with destination or filename attributes.
• Store the binary PDF in a variable (name attribute) for further processing (e.g., attach to email, upload to S3, or pass to another service).

---

Syntax and Examples

Generate a simple PDF with cfdocument

• Use cases: basic invoices, compact reports, receipts, internal documents.
• Strengths: simple, tightly integrated with CFML data output, easy headers/footers.

Example:
<cfset order = { id=1042, customer=”Acme Corp”, items=[ {name=”Widget A”, qty=3, price=19.95}, {name=”Widget B”, qty=2, price=29.50} ] } >

<h1 style="font-family:Arial;">Invoice</h1>
<p><strong>Customer:</strong> <cfoutput>#order.customer#</cfoutput></p>

<table border="1" cellpadding="6" cellspacing="0" width="100%">
    <tr>
        <th align="left">Item</th><th>Qty</th><th align="right">Price</th><th align="right">Total</th>
    </tr>
    <cfset grandTotal = 0>
    <cfloop array="#order.items#" index="it">
        <cfset lineTotal = it.qty * it.price>
        <cfset grandTotal += lineTotal>
        <tr>
            <td><cfoutput>#it.name#</cfoutput></td>
            <td align="center"><cfoutput>#it.qty#</cfoutput></td>
            <td align="right"><cfoutput>#NumberFormat(it.price, '9,999.99')#</cfoutput></td>
            <td align="right"><cfoutput>#NumberFormat(lineTotal, '9,999.99')#</cfoutput></td>
        </tr>
    </cfloop>
    <tr>
        <td colspan="3" align="right"><strong>Grand Total</strong></td>
        <td align="right"><cfoutput>#NumberFormat(grandTotal, '9,999.99')#</cfoutput></td>
    </tr>
</table>

<cfdocumentitem type="footer">
    <div style="font-family:Arial; font-size:9pt; border-top:1px solid #ccc; padding:6px 0;">
        Page <cfoutput>#cfdocument.currentpagenumber#</cfoutput> of <cfoutput>#cfdocument.totalpagecount#</cfoutput>
    </div>
</cfdocumentitem>

Generate a PDF with cfhtmltopdf (better CSS/JS support)

• Use cases: complex layouts, brand-heavy documents, charts rendered in HTML/JS.
• Strengths: improved fidelity for HTML/CSS; supports modern styles.

<style>
    @page { size: A4; }
    h1 { font-family: 'Segoe UI', Arial, sans-serif; color: #333; }
    .kpi { display: inline-block; width: 30%; margin-right: 3%; padding: 12px; border: 1px solid #eee; }
    .page-break { page-break-after: always; }
</style>

<h1>Executive Summary</h1>
<div class="kpi"><strong>Revenue:</strong> $1.2M</div>
<div class="kpi"><strong>Growth:</strong> 14%</div>
<div class="kpi"><strong>NPS:</strong> 62</div>

<div class="page-break"></div>
<h2>Details</h2>
<p>Charts and tables go here.</p>

<cfhtmltopdfitem type="footer">
    <div style="font-family:Arial; font-size:9pt;">Confidential • Page {page} of {total}</div>
</cfhtmltopdfitem>

Tip: Use CSS like page-break-before/after and @page to control pagination and margins.

Merge and watermark PDFs with cfpdf

• Use cases: bundling statements, assembling booklets, stamping “Confidential” on documents.

<cfpdf action=”addWatermark” source=”C:\webroot\pdf\bundle.pdf” destination=”C:\webroot\pdf\bundle-watermarked.pdf” overwrite=”true”
text=”CONFIDENTIAL” rotation=”45″ opacity=”0.1″ fontSize=”48″ foreground=”true”>

<cfpdf action=”protect” source=”C:\webroot\pdf\bundle-watermarked.pdf” destination=”C:\webroot\pdf\bundle-secure.pdf” overwrite=”true”
newUserPassword=”viewOnly123″ permissions=”noPrint”>

Stream a PDF to the browser

• Option A: Omit a filename/destination and ColdFusion streams inline.
• Option B: Use a variable and cfcontent for more control.

Hello PDF

---

Use Cases

• Automated invoices and receipts for E-commerce.
• Monthly account statements and bank-style reports.
• Certificates, tickets, boarding passes, and badges.
• Regulatory/HR documents pulled from templates and data.
• Analytics dashboards exported as printable PDFs.
• Batch merging of multiple PDFs into a single pack.

Real-world example: E-commerce invoice workflow

1. Customer completes checkout; order data is stored.
2. A scheduled task or synchronous request calls a CFML template.
3. The template uses cfdocument or cfhtmltopdf to render a branded invoice from HTML and database values (taxes, discounts, totals).
4. The file is saved to storage and also emailed as an attachment.
5. A cfpdf protect step adds a user password and restricts editing/printing.
6. The invoice is available for Download in the user’s account page, streamed via cfcontent.

This pattern scales to thousands of orders per day because it is purely server-side and easily automated.

---

Best practices

Content and layout

• Prefer cfhtmltopdf for complex, brand-heavy layouts and modern CSS; use cfdocument for straightforward templated reports.
• Use print-friendly CSS:
  • page-break-before/after, @page margins, and page size.
  • Avoid overly nested tables; use simple structures.
• Embed or reference web-safe fonts; for custom/Unicode fonts, ensure they’re embedded and licensed.
• Optimize images (compression, appropriate dimensions) to reduce PDF size.

Performance and Scalability

• Cache static sections (logos, headers) or use image sprites to reduce processing overhead.
• Pre-generate recurring documents (e.g., monthly statements) via Scheduled tasks and store them.
• Tune ColdFusion request timeouts and heap memory for large PDFs.
• Consider asynchronous generation for long-running document batches.

Security and Compliance

• Sanitize HTML sources if content includes user input; avoid executing untrusted scripts.
• Use cfpdf action=”protect” to apply passwords and permissions.
• Remove metadata you don’t need with cfpdf action=”setInfo” to minimize sensitive disclosures.
• Store generated PDFs in restricted folders; never expose raw paths.

Operational tips

• Log and monitor failures; capture stack traces for PDF generation exceptions.
• Standardize templates and create a design system for consistent headers/footers.
• Keep dependencies and ColdFusion updated for Security and rendering improvements.
• Validate encoding; for multilingual output (e.g., CJK), ensure font coverage and correct collation.

---

Choosing the Right Tag (Quick Comparison)

Feature	cfdocument	cfhtmltopdf	cfpdf
Primary purpose	Generate PDF from CFML/HTML	HTML-to-PDF with improved CSS/JS support	Manipulate existing PDFs
Best for	Data-driven reports, invoices	Complex layouts, brand fidelity, charts	Merge, split, watermark, protect
Headers/Footers	cfdocumentitem	cfhtmltopdfitem	N/A (manipulation only)
CSS/JS fidelity	Basic to moderate	High	N/A
Output	Stream, file, variable	Stream, file, variable	File in/out operations

Tip: Many teams combine them: generate with cfhtmltopdf for fidelity, then use cfpdf to secure or merge.

---

Key Points

• ColdFusion offers end-to-end, server-side PDF generation and manipulation using familiar CFML.
• Use cfdocument for simple templated documents; use cfhtmltopdf for modern HTML/CSS fidelity.
• Use cfpdf to merge, split, watermark, set metadata, and protect PDFs.
• Stream PDFs directly, save to file, or keep them in memory for further processing.
• Follow security and Performance Best practices, especially when generating large batches.

---

Troubleshooting and Performance Tips

• Rendering issues: If CSS isn’t applied as expected in cfdocument, try cfhtmltopdf or simplify the CSS. Check absolute vs relative asset paths.
• Missing fonts or garbled characters: Ensure the font is installed on the server and embedded; specify font-family explicitly.
• Large file sizes: Compress images and avoid massive inline SVGs. Consider lowering image DPI where practical.
• Timeouts: Increase request timeout for heavy reports; pre-render in background and notify users when ready.
• Memory errors: Use pagination, split documents, or generate in batches. Review JVM heap settings for ColdFusion.

---

Frequently Asked Questions

What’s the difference between cfdocument and cfhtmltopdf?

cfdocument is great for traditional CFML-to-PDF workflows with simple CSS and built-in header/footer support. cfhtmltopdf uses a more modern HTML renderer, providing better support for advanced CSS and client-like rendering. For complex layouts or chart-heavy pages, cfhtmltopdf usually produces more faithful results.

Can I password-protect or restrict actions on a PDF?

Yes. Use cfpdf action=”protect” to set a user/owner password and control permissions such as printing, copying, and editing. Example: permissions=”noPrint,noCopy”.

How do I add headers and footers?

Use cfdocumentitem with cfdocument and cfhtmltopdfitem with cfhtmltopdf. These items are repeated on every page and can include dynamic values like page numbers.

Do I need Adobe ColdFusion Enterprise for PDF generation?

Core tags (cfdocument, cfhtmltopdf, cfpdf) are part of ColdFusion’s PDF Feature set. Some advanced or distributed PDF services may be Enterprise-only. Always check your specific ColdFusion version’s documentation for Licensing and feature availability.

Can I merge multiple PDFs and add a watermark?

Yes. Use cfpdf action=”merge” to combine files and cfpdf action=”addWatermark” to place text or image watermarks with rotation and opacity settings.