Frappe Printing & Templates

Create print formats, email templates, and document templates using Jinja in Frappe.

When to use

Creating custom print formats for documents
Building email templates with dynamic content
Generating PDFs from documents
Using Jinja templating in web pages
Configuring letter heads for branding
Using the Print Format Builder

Inputs required

Target DocType for the print format
Layout requirements (fields, tables, headers)
Whether format is standard (version controlled) or custom (DB-stored)
Letter Head / branding requirements
PDF generation needs

Procedure

0) Choose format type

Type	How to Create	Version Controlled	Customizable by User
Standard	Developer Mode, saved as JSON	Yes	No
Print Format Builder	Drag-and-drop UI	No (DB)	Yes
Custom HTML (Jinja)	Type "new print format" in awesomebar	Optional	Depends

1) Create a Jinja print format

Create via awesomebar → "New Print Format":

Set a unique name
Link to the target DocType
Set "Standard" = "No" (or "Yes" for dev mode export)
Check "Custom Format"
Set Print Format Type = "Jinja"
Write your Jinja HTML

<div class="print-format">
    <h1>{{ doc.name }}</h1>
    <p><strong>{{ _("Customer") }}:</strong> {{ doc.customer }}</p>
    <p><strong>{{ _("Date") }}:</strong> {{ frappe.format_date(doc.transaction_date) }}</p>

    <table class="table table-bordered">
        <thead>
            <tr>
                <th>{{ _("Item") }}</th>
                <th>{{ _("Qty") }}</th>
                <th class="text-right">{{ _("Rate") }}</th>
                <th class="text-right">{{ _("Amount") }}</th>
            </tr>
        </thead>
        <tbody>
            {% for item in doc.items %}
            <tr>
                <td>{{ item.item_name }}</td>
                <td>{{ item.qty }}</td>
                <td class="text-right">{{ frappe.format(item.rate, {'fieldtype': 'Currency'}) }}</td>
                <td class="text-right">{{ frappe.format(item.amount, {'fieldtype': 'Currency'}) }}</td>
            </tr>
            {% endfor %}
        </tbody>
        <tfoot>
            <tr>
                <td colspan="3" class="text-right"><strong>{{ _("Total") }}</strong></td>
                <td class="text-right"><strong>{{ frappe.format(doc.grand_total, {'fieldtype': 'Currency'}) }}</strong></td>
            </tr>
        </tfoot>
    </table>

    {% if doc.terms %}
    <div class="terms">
        <h4>{{ _("Terms & Conditions") }}</h4>
        <p>{{ doc.terms }}</p>
    </div>
    {% endif %}
</div>

<style>
    .print-format { font-family: Arial, sans-serif; }
    .print-format h1 { color: #333; }
    .print-format table { width: 100%; margin-top: 20px; }
</style>

2) Use Frappe Jinja API

Data fetching in templates:

{# Fetch a document #}
{% set customer = frappe.get_doc('Customer', doc.customer) %}
{{ customer.customer_name }}

{# List query (ignores permissions) #}
{% set open_orders = frappe.get_all('Sales Order',
    filters={'customer': doc.customer, 'status': 'To Deliver and Bill'},
    fields=['name', 'grand_total'],
    order_by='creation desc',
    page_length=5) %}

{# Permission-aware list query #}
{% set my_tasks = frappe.get_list('Task',
    filters={'owner': frappe.session.user}) %}

{# Single value lookup #}
{% set company_abbr = frappe.db.get_value('Company', doc.company, 'abbr') %}

{# Settings value #}
{% set timezone = frappe.db.get_single_value('System Settings', 'time_zone') %}

Formatting:

{{ frappe.format(50000, {'fieldtype': 'Currency'}) }}
{{ frappe.format_date('2025-01-15') }}
{{ frappe.format_date(doc.posting_date) }}

Session and context:

{{ frappe.session.user }}
{{ frappe.get_fullname() }}
{{ frappe.lang }}
{{ _("Translatable string") }}

URLs:

<a href="{{ frappe.get_url() }}/app/sales-order/{{ doc.name }}">View Order</a>

3) Build email templates

Dear {{ doc.customer_name }},

Your order {{ doc.name }} has been confirmed.

Items:
{% for item in doc.items %}
- {{ item.item_name }} x {{ item.qty }}
{% endfor %}

Total: {{ frappe.format(doc.grand_total, {'fieldtype': 'Currency'}) }}

Thank you,
{{ frappe.get_fullname() }}

4) Generate PDFs programmatically

import frappe

# Generate PDF
pdf_content = frappe.get_print(
    doctype="Sales Invoice",
    name="SINV-001",
    print_format="Custom Invoice",
    as_pdf=True
)

# Attach PDF to document
frappe.attach_print(
    doctype="Sales Invoice",
    name="SINV-001",
    print_format="Custom Invoice",
    file_name="invoice.pdf"
)

# Send with email
frappe.sendmail(
    recipients=["customer@example.com"],
    subject="Your Invoice",
    message="Please find attached your invoice.",
    attachments=[{
        "fname": "invoice.pdf",
        "fcontent": pdf_content
    }]
)

5) Configure Letter Head

Navigate to Letter Head list → New
Upload company logo and header image
Set as default for the company
Letter Head appears automatically on print formats

6) Use Jinja filters

{{ doc.customer_name|upper }}        {# UPPERCASE #}
{{ doc.notes|truncate(100) }}        {# Truncate text #}
{{ doc.description|striptags }}      {# Remove HTML #}
{{ doc.html_content|safe }}          {# Render raw HTML (trusted only!) #}
{{ items|length }}                   {# Count items #}
{{ items|first }}                    {# First item #}
{{ names|join(', ') }}               {# Join list #}
{{ amount|round(2) }}               {# Round number #}
{{ value|default('N/A') }}          {# Default if undefined #}
{{ data|tojson }}                    {# Convert to JSON #}

7) Template inheritance and macros

{# macros/fields.html #}
{% macro field_row(label, value) %}
<tr>
    <td class="label"><strong>{{ _(label) }}</strong></td>
    <td>{{ value }}</td>
</tr>
{% endmacro %}

{# In print format #}
{% from "macros/fields.html" import field_row %}
<table>
    {{ field_row("Customer", doc.customer_name) }}
    {{ field_row("Date", frappe.format_date(doc.posting_date)) }}
    {{ field_row("Total", frappe.format(doc.grand_total, {'fieldtype': 'Currency'})) }}
</table>

Verification

Print format renders correctly in Print View
All fields display with proper formatting
PDF generation works without errors
Email templates render with correct data
Letter Head appears on printed documents
Translations work in templates (_())
No XSS risks from unescaped content

Failure modes / debugging

Template syntax error: Check Jinja delimiters ({{ }}, {% %}); look for unclosed blocks
Field not rendering: Verify field name matches DocType schema; check child table access pattern
PDF generation fails: Check wkhtmltopdf installation; verify print format Jinja is valid
Styling issues in PDF: Use inline styles; avoid complex CSS; test with Print View first
Permission error in template: Use frappe.get_all (no permission check) vs frappe.get_list

Escalation

For app-level hooks and structure → frappe-app-development
For DocType schema questions → frappe-doctype-development

References

references/jinja.md — Jinja templating and Frappe Jinja API
references/printing.md — Print formats and PDF generation

Guardrails

Test with actual data: Always preview with real documents; edge cases break templates
Handle missing fields gracefully: Use {{ doc.field or '' }} or {% if doc.field %}
Use get_url() for images: Never hardcode URLs; use {{ frappe.utils.get_url() }}/files/...
Escape user content: Use {{ value | e }} for user-generated content to prevent XSS
Keep styling inline: PDF generators don't support external CSS; use inline style attributes

Common Mistakes

Mistake	Why It Fails	Fix
Wrong Jinja syntax	Template error, blank output	Use `{{ }}` for output, `{% %}` for logic; check closing tags
Missing filters	Raw data displayed	Use `frappe.format()` or `frappe.format_date()` for formatting
Hardcoded URLs	Images/links break across sites	Use `{{ frappe.utils.get_url() }}` for absolute URLs
Accessing child table wrong	Empty or error	Use `{% for item in doc.items %}` not `doc.child_table_name`
Complex CSS in print format	Styling lost in PDF	Use inline styles, simple layouts, `<table>` for structure
Not handling None values	`'None'` string in output	Use `{{ value or '' }}` or `{% if value %}`

frappe-printing-templates