Skip to content

Lesson 24 ยท 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