Back to Details

erpnext-syntax-jinja

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ERPNext Jinja Templates Syntax Skill

ERPNext Jinja模板语法指南

Correct Jinja syntax for Print Formats, Email Templates, and Portal Pages in ERPNext/Frappe v14/v15/v16.
适用于ERPNext/Frappe v14/v15/v16版本中打印格式、邮件模板和门户页面的标准Jinja语法。

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)
在以下场景使用本指南：
  • 创建或修改打印格式
  • 开发邮件模板
  • 构建门户页面（www/*.html）
  • 通过钩子添加自定义Jinja过滤器/方法
请勿在以下场景使用：
  • 报表打印格式（使用JavaScript模板而非Jinja）
  • 客户端脚本（请使用erpnext-syntax-clientscripts）
  • 服务器脚本（请使用erpnext-syntax-serverscripts）

Context Objects per Template Type

各模板类型对应的上下文对象

Print Formats

打印格式

ObjectDescription
doc
The document being printed
frappe
Frappe module with utility methods
_()
Translation function
对象描述
doc
当前要打印的文档
frappe
包含实用工具方法的Frappe模块
_()
翻译函数

Email Templates

邮件模板

ObjectDescription
doc
The linked document
frappe
Frappe module (limited)
对象描述
doc
关联的文档
frappe
Frappe模块（功能受限）

Portal Pages

门户页面

ObjectDescription
frappe.session.user
Current user
frappe.form_dict
Query parameters
frappe.lang
Current language
Custom contextVia Python controller
See: 
references/context-objects.md
for complete details.
对象描述
frappe.session.user
当前用户
frappe.form_dict
查询参数
frappe.lang
当前语言
Custom context通过Python控制器定义
参考：
references/context-objects.md
查看完整详情。

Essential Methods

核心方法

Formatting (ALWAYS use)

格式化（务必使用）

jinja
{# 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) }}
jinja
{# 打印格式中字段的推荐写法 #}
{{ doc.get_formatted("posting_date") }}
{{ doc.get_formatted("grand_total") }}

{# 子表行 - 传入父文档 #}
{% for row in doc.items %}
    {{ row.get_formatted("rate", doc) }}
    {{ row.get_formatted("amount", doc) }}
{% endfor %}

{# 通用格式化 #}
{{ frappe.format(value, {'fieldtype': 'Currency'}) }}
{{ frappe.format_date(doc.posting_date) }}

Document Retrieval

文档检索

jinja
{# 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']) %}
jinja
{# 完整文档 #}
{% set customer = frappe.get_doc("Customer", doc.customer) %}

{# 指定字段值（更高效） #}
{% set abbr = frappe.db.get_value("Company", doc.company, "abbr") %}

{# 记录列表 #}
{% set tasks = frappe.get_all('Task', 
    filters={'status': 'Open'}, 
    fields=['title', 'due_date']) %}

Translation (REQUIRED for user-facing strings)

翻译（面向用户的字符串必填）

jinja
<h1>{{ _("Invoice") }}</h1>
<p>{{ _("Total: {0}").format(doc.grand_total) }}</p>
See: 
references/methods-reference.md
for all methods.
jinja
<h1>{{ _("Invoice") }}</h1>
<p>{{ _("Total: {0}").format(doc.grand_total) }}</p>
参考：
references/methods-reference.md
查看所有方法。

Control Structures

控制结构

Conditionals

条件判断

jinja
{% 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 %}
jinja
{% 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

循环

jinja
{% 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 %}
jinja
{% 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

循环变量

VariableDescription
loop.index
1-indexed position
loop.first
True on first
loop.last
True on last
loop.length
Total items
变量描述
loop.index
从1开始的索引
loop.first
首次循环时为True
loop.last
最后一次循环时为True
loop.length
总条目数

Variables

变量定义

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

Filters

过滤器

Commonly Used

常用过滤器

FilterExample
default
{{ value | default('N/A') }}
length
{{ items | length }}
join
{{ names | join(', ') }}
truncate
{{ text | truncate(100) }}
safe
{{ html | safe }}
(trusted content only!)
See: 
references/filters-reference.md
for all filters.
过滤器示例
default
{{ value | default('N/A') }}
length
{{ items | length }}
join
{{ names | join(', ') }}
truncate
{{ text | truncate(100) }}
safe
{{ html | safe }}
（仅用于可信内容！）
参考：
references/filters-reference.md
查看所有过滤器。

Print Format Template

打印格式模板

jinja
<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>
jinja
<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

邮件模板

jinja
<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>
jinja
<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

www/projects/index.html

jinja
{% 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 %}
jinja
{% 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

www/projects/index.py

python
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
python
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

通过jenv钩子自定义过滤器/方法

hooks.py

hooks.py

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

myapp/jinja/methods.py

myapp/jinja/methods.py

python
import frappe

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

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

Usage

使用示例

jinja
<img src="{{ get_company_logo(doc.company) }}">
jinja
<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)
  1. 所有面向用户的字符串使用
    _()
    包裹
  2. 货币/日期字段使用
    get_formatted()
    方法
  3. 为变量设置默认值：
    {{ value | default('') }}
  4. 子表行使用：
    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)
  1. 在循环中执行查询（N+1性能问题）
  2. 对用户输入使用
    | safe
    过滤器（存在XSS风险）
  3. 在模板中进行复杂计算（应在Python中实现）
  4. 在报表打印格式中使用Jinja语法（报表使用JS模板）

Report Print Formats (NOT Jinja!)

报表打印格式（非Jinja语法！）

WARNING: Report Print Formats for Query/Script Reports use JavaScript templating.
AspectJinja (Print Formats)JS (Report Print Formats)
Output
{{ }}
{%= %}
Code
{% %}
{% %}
LanguagePythonJavaScript
html
<!-- JS Template for Reports -->
{% for(var i=0; i<data.length; i++) { %}
<tr><td>{%= data[i].name %}</td></tr>
{% } %}
注意：查询/脚本报表的打印格式使用JavaScript模板。
维度Jinja（普通打印格式）JS（报表打印格式）
输出语法
{{ }}
{%= %}
代码块语法
{% %}
{% %}
语言PythonJavaScript
html
<!-- 报表的JS模板示例 -->
{% for(var i=0; i<data.length; i++) { %}
<tr><td>{%= data[i].name %}</td></tr>
{% } %}

Version Compatibility

版本兼容性

Featurev14v15
Basic Jinja API✅✅
get_formatted()✅✅
jenv hook✅✅
Portal pages✅✅
frappe.utils.format_date with format✅✅+
特性v14v15
基础Jinja API✅✅
get_formatted()✅✅
jenv钩子✅✅
门户页面✅✅
带格式的frappe.utils.format_date✅✅+

V16: Chrome PDF Rendering

V16版本：Chrome PDF渲染

Version 16 introduced Chrome-based PDF rendering replacing wkhtmltopdf.
V16版本引入了基于Chrome的PDF渲染，替代了wkhtmltopdf。

Key Differences

主要差异

Aspectv14/v15 (wkhtmltopdf)v16 (Chrome)
CSS SupportLimited CSS3Full modern CSS
Flexbox/GridPartialFull support
Page breaks
page-break-*
break-*
preferred
FontsSystem fontsWeb fonts supported
PerformanceFasterSlightly slower
维度v14/v15（wkhtmltopdf）v16（Chrome）
CSS支持有限的CSS3支持完整的现代CSS支持
Flexbox/Grid部分支持完整支持
分页
page-break-*
推荐使用
break-*
字体仅系统字体支持Web字体
性能更快略慢

CSS Updates for V16

V16版本的CSS更新

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

/* v16 - both work, but break-* is preferred */
.page-break { break-before: page; }
css
/* v14/v15写法 */
.page-break { page-break-before: always; }

/* v16写法 - 两种都兼容，但推荐使用break-* */
.page-break { break-before: page; }

Configuration (V16)

配置（V16版本）

python
undefined
python
undefined

In site_config.json

在site_config.json中

{ "pdf_engine": "chrome", # or "wkhtmltopdf" for legacy "chrome_path": "/usr/bin/chromium" }
undefined
{ "pdf_engine": "chrome", # 如需兼容旧版可设置为"wkhtmltopdf" "chrome_path": "/usr/bin/chromium" }
undefined

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
大多数打印格式无需修改即可使用。若使用以下特性则需更新：
  • 复杂CSS布局（Flexbox/Grid现在完全支持）
  • 自定义字体（Web字体现在可用）
  • 高级分页控制

Reference Files

参考文件

FileContents
references/context-objects.md
Available objects per template type
references/methods-reference.md
All frappe.* methods
references/filters-reference.md
Standard and custom filters
references/examples.md
Complete working examples
references/anti-patterns.md
Mistakes to avoid
文件内容
references/context-objects.md
各模板类型的可用上下文对象
references/methods-reference.md
所有frappe.*方法
references/filters-reference.md
标准及自定义过滤器
references/examples.md
完整可用示例
references/anti-patterns.md
需避免的错误写法

See Also

相关内容

  • erpnext-syntax-hooks
    - For jenv configuration in hooks.py
  • erpnext-impl-jinja
    - For implementation patterns
  • erpnext-errors-jinja
    - For error handling
  • erpnext-syntax-hooks
    - hooks.py中的jenv配置
  • erpnext-impl-jinja
    - 实现模式
  • erpnext-errors-jinja
    - 错误处理