erpnext-syntax-jinja（erpnext 语法神器）

ERPNext Jinja Templates Syntax Skill

Correct Jinja syntax for Print Formats, Email Templates, and Portal Pages in ERPNext/Frappe v14/v15/v16.

When to Use This Skill

USE this skill when:

• Creating or modifying Print Formats
• Developing Email Templates
• Building Portal Pages (www/*.html)
• Adding custom Jinja filters/methods via hooks

DO NOT USE for:

• Report Print Formats (they use JavaScript templating, not Jinja)
• Client Scripts (use erpnext-syntax-clientscripts)
• Server Scripts (use erpnext-syntax-serverscripts)

Context Objects per Template Type

Print Formats

Email Templates

Portal Pages

See: references/context-objects.md for complete details.

Essential Methods

Formatting (ALWAYS use)

{# RECOMMENDED for fields in print formats #}
{{ doc.get_formatted("posting_date") }}
{{ doc.get_formatted("grand_total") }}

{# For child table rows - pass parent doc #}
{% for row in doc.items %}
    {{ row.get_formatted("rate", doc) }}
    {{ row.get_formatted("amount", doc) }}
{% endfor %}

{# General formatting #}
{{ frappe.format(value, {'fieldtype': 'Currency'}) }}
{{ frappe.format_date(doc.posting_date) }}

Document Retrieval

{# Full document #}
{% set customer = frappe.get_doc("Customer", doc.customer) %}

{# Specific field value (more efficient) #}
{% set abbr = frappe.db.get_value("Company", doc.company, "abbr") %}

{# List of records #}
{% set tasks = frappe.get_all('Task',
    filters={'status': 'Open'},
    fields=['title', 'due_date']) %}

Translation (REQUIRED for user-facing strings)

<h1>{{ _("Invoice") }}</h1>
<p>{{ _("Total: {0}").format(doc.grand_total) }}</p>

See: references/methods-reference.md for all methods.

Control Structures

Conditionals

{% if doc.status == "Paid" %}
    <span class="label-success">{{ _("Paid") }}</span>
{% elif doc.status == "Overdue" %}
    <span class="label-danger">{{ _("Overdue") }}</span>
{% else %}
    <span>{{ doc.status }}</span>
{% endif %}

Loops

{% for item in doc.items %}
    <tr>
        <td>{{ loop.index }}</td>
        <td>{{ item.item_name }}</td>
        <td>{{ item.get_formatted("amount", doc) }}</td>
    </tr>
{% else %}
    <tr><td colspan="3">{{ _("No items") }}</td></tr>
{% endfor %}

Loop Variables

Variables

{% set total = 0 %}
{% set customer_name = doc.customer_name | default('Unknown') %}

Filters

Commonly Used

See: references/filters-reference.md for all filters.

Print Format Template

<style>
    .header { background: #f5f5f5; padding: 15px; }
    .table { width: 100%; border-collapse: collapse; }
    .table th, .table td { border: 1px solid #ddd; padding: 8px; }
    .text-right { text-align: right; }
</style>

<div class="header">
    <h1>{{ doc.select_print_heading or _("Invoice") }}</h1>
    <p>{{ doc.name }}</p>
    <p>{{ _("Date") }}: {{ doc.get_formatted("posting_date") }}</p>
</div>

<table class="table">
    <thead>
        <tr>
            <th>{{ _("Item") }}</th>
            <th class="text-right">{{ _("Qty") }}</th>
            <th class="text-right">{{ _("Amount") }}</th>
        </tr>
    </thead>
    <tbody>
        {% for row in doc.items %}
        <tr>
            <td>{{ row.item_name }}</td>
            <td class="text-right">{{ row.qty }}</td>
            <td class="text-right">{{ row.get_formatted("amount", doc) }}</td>
        </tr>
        {% endfor %}
    </tbody>
</table>

<p><strong>{{ _("Grand Total") }}:</strong> {{ doc.get_formatted("grand_total") }}</p>

Email Template

<p>{{ _("Dear") }} {{ doc.customer_name }},</p>

<p>{{ _("Invoice") }} <strong>{{ doc.name }}</strong> {{ _("for") }}
{{ doc.get_formatted("grand_total") }} {{ _("is due.") }}</p>

<p>{{ _("Due Date") }}: {{ frappe.format_date(doc.due_date) }}</p>

{% if doc.items %}
<ul>
{% for item in doc.items %}
    <li>{{ item.item_name }} - {{ item.qty }} x {{ item.get_formatted("rate", doc) }}</li>
{% endfor %}
</ul>
{% endif %}

<p>{{ _("Best regards") }},<br>
{{ frappe.db.get_value("Company", doc.company, "company_name") }}</p>

Portal Page with Controller

www/projects/index.html

{% extends "templates/web.html" %}

{% block title %}{{ _("Projects") }}{% endblock %}

{% block page_content %}
<h1>{{ _("Projects") }}</h1>

{% if frappe.session.user != 'Guest' %}
    <p>{{ _("Welcome") }}, {{ frappe.get_fullname() }}</p>
{% endif %}

{% for project in projects %}
    <div class="project">
        <h3>{{ project.title }}</h3>
        <p>{{ project.description | truncate(150) }}</p>
    </div>
{% else %}
    <p>{{ _("No projects found.") }}</p>
{% endfor %}
{% endblock %}

www/projects/index.py

import frappe

def get_context(context):
    context.title = "Projects"
    context.projects = frappe.get_all(
        "Project",
        filters={"is_public": 1},
        fields=["name", "title", "description"],
        order_by="creation desc"
    )
    return context

Custom Filters/Methods via jenv Hook

hooks.py

jenv = {
    "methods": ["myapp.jinja.methods"],
    "filters": ["myapp.jinja.filters"]
}

myapp/jinja/methods.py

import frappe

def get_company_logo(company):
    """Get company logo URL"""
    return frappe.db.get_value("Company", company, "company_logo") or ""

Usage

<img src="{{ get_company_logo(doc.company) }}">

Critical Rules

✅ ALWAYS

1. Use _() for all user-facing strings
2. Use get_formatted() for currency/date fields
3. Use default values: {{value | default('')}}
4. Child table rows: row.get_formatted("field", doc)

❌ NEVER

1. Execute queries in loops (N+1 problem)
2. Use | safe for user input (XSS risk)
3. Heavy calculations in templates (do in Python)
4. Jinja syntax in Report Print Formats (they use JS)

Report Print Formats (NOT Jinja!)

WARNING: Report Print Formats for Query/Script Reports use JavaScript templating.

<!-- JS Template for Reports -->
{% for(var i=0; i<data.length; i++) { %}
<tr><td>{%= data[i].name %}</td></tr>
{% } %}

Version Compatibility

V16: Chrome PDF Rendering

Version 16 introduced Chrome-based PDF rendering replacing wkhtmltopdf.

Key Differences

CSS Updates for V16

/* v14/v15 */
.page-break { page-break-before: always; }

/* v16 - both work, but break-* is preferred */
.page-break { break-before: page; }

Configuration (V16)

# In site_config.json
{
    "pdf_engine": "chrome",  # or "wkhtmltopdf" for legacy
    "chrome_path": "/usr/bin/chromium"
}

Print Format Compatibility

Most print formats work unchanged. Update if using:

• Complex CSS layouts (flexbox/grid now fully supported)
• Custom fonts (web fonts now work)
• Advanced page break control

Reference Files

See Also

• erpnext-syntax-hooks - For jenv configuration in hooks.py
• erpnext-impl-jinja - For implementation patterns
• erpnext-errors-serverscripts - For server-side error handling