Print Format Developer Guide

FrapPDFy renders your Jinja2 HTML template against a Frappe document, then generates a PDF using one of two engines: WeasyPrint (CSS paged media) or CDP (Chrome headless via raw DevTools Protocol). Your template is stored in the Print Format Template doctype as a single HTML string, automatically split into three regions:

A complete template skeleton showing all three regions:

Copy<!-- HEADER — repeats on every page -->
<div class="pdf-header">
  <img src="{{ frappe.utils.get_url(doc.company_logo) }}" height="40">
  <h2>{{ doc.company }}</h2>
</div>

<!-- MAIN CONTENT -->
<div class="pdf-content">
  <h1>{{ doc.name }}</h1>
  <p>Date: {{ doc.posting_date }}</p>

  <table>
    <thead><tr>
      <th>Item</th><th>Qty</th><th>Rate</th><th>Amount</th>
    </tr></thead>
    <tbody>
      {% for row in doc.items %}
      <tr>
        <td>{{ row.item_name }}</td>
        <td>{{ row.qty }}</td>
        <td>{{ row.rate }}</td>
        <td>{{ row.amount }}</td>
      </tr>
      {% endfor %}
    </tbody>
  </table>
</div>

<!-- FOOTER — repeats on every page -->
<div class="pdf-footer">
  <span>{{ doc.company }} | {{ doc.company_address }}</span>
  <span>Page <span class="page-number"></span> of <span class="total-pages"></span></span>
</div>

Headers and footers repeat on every page. Heights are measured automatically so content is never clipped.

How each engine handles header/footer

Page numbering works in both engines using the same HTML structure. Add these spans in your header or footer:

Copy<!-- HTML — works in both engines -->
<span>Page <span class="page-number"></span> of <span class="total-pages"></span></span>

Copy/* Custom CSS — required for WeasyPrint engine */
.page-number::before {
    content: counter(page);
}
.total-pages::before {
    content: counter(pages);
}

These utility classes are pre-defined by both engines — do not redefine them in Custom CSS.

Copy<!-- Force a page break AFTER this element -->
<div class="page-break"></div>

<!-- Prevent this block from splitting across pages -->
<div class="no-break">
  ... keep this section together on one page ...
</div>

FrapPDFy automatically embeds images as base64 data URIs before rendering. This means both public and private files work in PDFs — no authentication issues.

Copy<!-- From an Attach field on the document -->
<img src="{{ frappe.utils.get_url(doc.company_logo) }}" height="50">

<!-- From a hardcoded file path -->
<img src="{{ frappe.utils.get_url('/files/letterhead.png') }}" height="80">

<!-- Private files also work -->
<img src="{{ frappe.utils.get_url('/private/files/stamp.png') }}" height="60">

Use the web_block helper to render an e-Invoice QR code from a registered Web Template.

Copy<!-- Render the QR code block -->
{{ web_block('e-Invoice QR', values={'e_invoice_qr_text': e_invoice_log.signed_qr_code}) }}

Copy/* Size the QR image via Custom CSS */
.qrcode {
    width: 90px;
    height: 90px;
}

Frappe stores rich text (Long Text with editor) as HTML with Quill editor classes. Override default Quill padding to avoid unwanted spacing in your PDF.

Copy/* Add to Custom CSS */
.ql-editor {
    padding: 0;
    margin: 0;
}

Copy<!-- Render a rich text field — it's already HTML -->
<div class="ql-editor">{{ doc.terms_and_conditions }}</div>

All custom CSS goes in the Custom CSS field of the Print Format Template. Page size and orientation are set via the doctype fields — not CSS.

Copy/* Recommended base CSS for every template */
* {
    margin: 0;
    padding: 0;
    box-sizing: border-box;
}

table {
    table-layout: fixed;
    width: 100%;
    border-collapse: collapse;
}

tr {
    break-inside: avoid;
    page-break-inside: avoid;
}

.ql-editor {
    padding: 0;
    margin: 0;
}

/* Page number counters (WeasyPrint) */
.page-number::before { content: counter(page); }
.total-pages::before { content: counter(pages); }

/* QR code size */
.qrcode { width: 90px; height: 90px; }

Page Size & Orientation Fields

Print multiple copies (e.g. Original, Duplicate, Triplicate) in one PDF, each with different labels. Page numbers reset per copy.

Step 1 — Set fields in Print Format Template

Step 2 — Copy Values JSON

Copy[
  { ".copy-label": "Original" },
  { ".copy-label": "Duplicate" },
  { ".copy-label": "Triplicate" }
]

Step 3 — Template placeholder

Copy<div class="pdf-header">
  <span class="copy-label"></span>   <!-- filled per copy -->
  <h2>Tax Invoice</h2>
</div>

Selector Syntax

Choose the right engine for your template's requirements. Set the engine per template in the pdf_engine field.

Offload PDF generation to a separate Frappe site — useful when your production server can't run Chrome or has memory constraints.

How it works

CopyProduction Site                    PDF Service Site
(frappdfy installed)               (frappdfy installed)
        │                                  │
        │  Renders template, extracts      │
        │  header/footer/content           │
        │                                  │
        │── POST (HTML + settings) ───────▶│
        │                                  │  Generates PDF
        │◀── { pdf_base64: "..." } ────────│
        │                                  │
        │  Decodes + streams to browser    │

Setup

FrapPDFy Settings

A cheat-sheet for everyday use: