Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 39 ยท Views and QWeb

QWeb Templates

Learn QWeb, the XML templating language behind Odoo reports, kanban cards and website pages: t-if, t-foreach, t-out, t-att, t-call and t-set, with a runnable mini renderer.

QWeb is Odoo's template language. A template is valid XML (or HTML written as XML) in which special t- attributes say what to repeat, skip or print. QWeb is used in three places: PDF reports and emails, website and portal pages, and the web client's own interface (kanban cards and many widgets, rendered in the browser by an OWL-based variant). The t- directives are the same family everywhere, which is why learning them once pays off.

You cannot run the real engine here, so the Odoo snippets are read-only. A mini QWeb written in Python later in the lesson implements the core directives, which is also a good way to understand what they do.

Directives you will use daily

XML
<t t-name="library.book_card">
  <div class="card" t-att-class="'bg-danger' if book.state == 'lost' else ''">
    <h3 t-out="book.name"/>
    <p t-if="book.author_id">By <span t-out="book.author_id.name"/></p>
    <p t-else="">Author unknown</p>
    <ul>
      <li t-foreach="book.tag_ids" t-as="tag" t-key="tag.id">
        <t t-out="tag.name"/>
      </li>
    </ul>
    <a t-attf-href="/library/book/#{book.id}">Open</a>
  </div>
</t>
Directive Meaning
t-out Print the value, HTML-escaped. Older code uses t-esc for the same thing
t-raw / t-out with markup Unescaped output. t-raw was removed; Markup objects passed to t-out are not escaped
t-if, t-elif, t-else Conditional rendering
t-foreach, t-as Loop; inside you also get tag_index, tag_first, tag_last, tag_size...
t-set, t-value Define a variable
t-att-NAME Set an attribute from an expression
t-attf-NAME Set an attribute from a format string with #{expr}
t-call Render another template, optionally passing variables
t-name Names a template
<t> An invisible wrapper: it holds directives but emits no element

Expressions are Python (server-side templates) or JavaScript (the client-side ones), restricted to a safe subset. In server templates, t-out is evaluated inside a sandbox where attribute access, comparisons and simple calls work.

Escaping: the security detail

t-out escapes <, > and &, so a customer name like <script> cannot inject code into a page or PDF. Never mark user-supplied text as safe. In Python, only text built by Odoo with markupsafe.Markup is trusted. A frequent bug is building HTML in a field with string formatting, then showing it with an HTML widget: use Markup and escape from the start.

Reusing templates with t-call

XML
<template id="library_row">
  <tr><td t-out="b.name"/><td t-out="b.copies"/></tr>
</template>

<template id="library_table">
  <table>
    <t t-foreach="books" t-as="b">
      <t t-call="library.library_row"/>
    </t>
  </table>
</template>

The called template sees the caller's variables, so b is visible in the row. You can pass extras by setting variables inside the t-call element, and a special 0 variable holds the body of the call, which lets a layout template wrap its content. Web pages use t-call="website.layout" and reports use t-call="web.external_layout" this way.

flowchart TD
    A["Report template<br/>t-foreach docs"] --> B["t-call web.external_layout"]
    B --> C["Header with company logo"]
    B --> D["Your body (variable 0)"]
    B --> E["Footer"]

A layout template draws the frame; your template fills in the body.

Template inheritance

QWeb templates are ir.ui.view records of type qweb, so they inherit the same way as other views, with inherit_id and xpath (Customising with View Inheritance). This is how a module adds a field to a standard invoice report without copying it.

A mini QWeb in Python

The stand-in below implements t-if, t-foreach/t-as, t-out (escaped) and t-att-*. It evaluates expressions with Python eval against a restricted scope. It is a teaching model, not Odoo's engine and not safe for untrusted templates.

Python Render a template with a mini QWeb

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice the second book: its angle brackets come out as &lt;script&gt;, which is exactly what t-out guarantees.

Layouts with t-call

This second stand-in models the layout and body pattern: a layout function wraps a body that is rendered with its own variables.

Python A layout that wraps a body

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which directive prints a value with HTML escaping in current QWeb?

    t-out prints and escapes. Older code used t-esc, which behaves the same way.
  2. 2. What does the <t> element do?

    <t> is invisible in the output; it is used to hold t-if, t-foreach and similar directives.
  3. 3. How do you build an attribute from a format string such as /book/#{book.id}?

    t-attf-NAME takes a format string with #{...} parts; t-att-NAME takes a plain expression.
  4. 4. Why does t-out matter for security?

    Escaping stops cross-site scripting through names, notes and other user-entered text.

Summary

  • QWeb templates are XML with t- directives, used for reports, emails, website pages and kanban cards.
  • t-out escapes; t-if, t-foreach, t-set, t-att, t-attf and t-call cover most needs.
  • t-call lets layouts wrap bodies, and templates are inheritable views.
  • Never trust user text; keep escaping on and use Markup only for HTML you built safely.

Next: Users and Groups