Odoo Qweb Templates

Odoo QWeb Templates

Selective Reading Rule

Start with:

• references/senior-master-standard.md
• references/usage-routing.md
• references/quality-checklist.md

Then load only the inherited docs, scripts, assets, or examples that match the user's actual task.

Overview

QWeb is Odoo's primary templating engine, used for PDF reports, website pages, and email templates. This skill generates correct, well-structured QWeb XML with proper directives, translation support, and report action bindings.

When to Use This Skill

• Creating a custom PDF report (invoice, delivery slip, certificate).
• Building a QWeb email template triggered by workflow actions.
• Designing Odoo website pages with dynamic content.
• Debugging QWeb rendering errors (t-if, t-foreach issues).

How It Works

1. Activate: Mention @odoo-qweb-templates and describe the report or template needed.
2. Generate: Receive a complete ir.actions.report record and QWeb template.
3. Debug: Paste a broken template to identify and fix rendering issues.

Examples

Example 1: Custom PDF Report

<!-- Report Action -->
<record id="action_report_patient_card" model="ir.actions.report">
    <field name="name">Patient Card</field>
    <field name="model">hospital.patient</field>
    <field name="report_type">qweb-pdf</field>
    <field name="report_name">hospital_management.report_patient_card</field>
    <field name="binding_model_id" ref="model_hospital_patient"/>
</record>

<!-- QWeb Template -->
<template id="report_patient_card">
    <t t-call="web.html_container">
        <t t-foreach="docs" t-as="doc">
            <t t-call="web.external_layout">
                <div class="page">
                    <h2>Patient Card</h2>
                    <table class="table table-bordered">
                        <tr>
                            <td><strong>Name:</strong></td>
                            <td><t t-field="doc.name"/></td>
                        </tr>
                        <tr>
                            <td><strong>Doctor:</strong></td>
                            <td><t t-field="doc.doctor_id.name"/></td>
                        </tr>
                        <tr>
                            <td><strong>Status:</strong></td>
                            <td><t t-field="doc.state"/></td>
                        </tr>
                    </table>
                </div>
            </t>
        </t>
    </t>
</template>

Example 2: Conditional Rendering

<!-- Show a warning block only if the patient is not confirmed -->
<t t-if="doc.state == 'draft'">
    <div class="alert alert-warning">
        <strong>Warning:</strong> This patient has not been confirmed yet.
    </div>
</t>

Best Practices

• ✅ Do: Use t-field for model fields — Odoo auto-formats dates, monetary values, and booleans correctly.
• ✅ Do: Use t-out (Odoo 15+) for safe HTML output of non-field strings. Use t-esc only on Odoo 14 and below (it HTML-escapes output).
• ✅ Do: Call web.external_layout for PDF reports to automatically include the company header, footer, and logo.
• ✅ Do: Use _lt() (lazy translation) for translatable string literals inside Python report helpers, not inline t-esc.
• ❌ Don't: Use raw Python expressions inside QWeb — compute values in the model or a report _get_report_values() helper.
• ❌ Don't: Forget t-as when using t-foreach; without it, you can't access the current record in the loop body.
• ❌ Don't: Use t-esc where you intend to render HTML content — it will escape the tags and print them as raw text.

Limitations

• Does not cover website controller routing for dynamic QWeb pages — that requires Python http.route knowledge.
• Email template QWeb has different variable scope than report QWeb (object vs docs) — this skill primarily focuses on PDF reports.
• QWeb JavaScript (used in Kanban/Form widgets) is a different engine; this skill covers server-side QWeb only.
• Does not cover wkhtmltopdf configuration for PDF rendering issues (page size, margins, header/footer overlap).