Odoo CMS - a big picture

QWEB Email Templates in Odoo 10

Conversion from Mako (Jinja) to QWeb

Hieu Le

From my perspective, it is a need (maybe a must) that most companies have their own email templates to communicate with their clients, or report templates to use internally or externally. Without an ERP system, they can use Office tools like Microsoft Word, OpenOffice, LibreOffice to do that. But with an ERP system, life is much more easier since we can manage those templates in one single place and connect them with the related data.


Currently Odoo (version 7, 8, 9) use Mako to define email templates where we can create dynamic email content. Mako is a template library written in Python. It provides a familiar, non-XML syntax which compiles into Python modules for maximum performance. Mako supports syntaxes that enable us to define:

  • Dynamic values (variables)

this is x: ${x}

  • Control structures (if, else ...)

% if x==5:
    this is some output
% endif

  • The Loop Context (for loop ...)

% for a in ("one", "two", "three"):
    <li>Item ${loop.index}: ${a}</li>
% endfor

  • Even Python blocks

    x = 1
    y = 2
this is x: ${x}
this is y: ${y}

For more details, visit Mako syntaxes guideline.

Let’s have a look at an email template in Odoo at menu Settings > Technical > Email > Templates:

You can see how the template ‘Invoice - Send by Email’ was defined using Mako syntaxes and HTML formats. For instances, ${object.number}, ${object.amount_total}, ${object.currency_id.name} are dynamic values will be replaced by the real data from the Invoice when the email will be rendered and sent. It would be difficult for non-technical background users to do this. Normally, clients send a template with real data, then developers convert it to ‘technical’ one in source code. 

There is a nice blog post about Send Mail in OpenERP with Mail Temples that you can have a look.

Mako is good. But you know, technologies always change. New techniques are invented day by day to improve or to replace the old ones. There are always debates on the Internet about which one is better. For instance, visit this wiki page Comparison of web template engines with dozens of options. In the next chapter, I am going to talk about QWeb.


Qweb was first used in Odoo 8 to replace for the old RML report engine. What is QWeb? A clear answer is already here. QWeb is web framework (mainly an XML templating system) implemented in various languages. The core component of qweb is its cool XML templating engine. It was written by Antony Lesuisse, Odoo's CTO, in 2006 and is available in the following languages: Python, PHP, Ruby, C#, Java and Javascript. Its source code is managed here. Odoo uses both the Python and Javascript versions of QWeb. The Javascript version was ported and enhanced by Fabien Meghazi. You can also find QWeb documentation on Odoo website.

Like Mako, QWeb also supports dynamic values, control structures, loop context, … but with different syntaxes. Developers will feel it more familiar to XML tags, of course, it is a XML templating engine. 

This small comparison table shows the different syntaxes between Make and QWeb.

​Mako Qweb
Dynamic values ​this is x: ${x} ​this is x: <t t-esc="x"/>
Control structures % if x==5:
    this is some output
% endif
​<t t-if="x==5">
    <p> this is some output</p>
​The Loop Context % for i in (1, 2, 3):
    <li>Item ${i}</li>
% endfor
​<t t-foreach="[1, 2, 3]" t-as="i">
    <li>Item <t t-esc="i"/></li>

Let’s have a look at the Invoice report at menu Settings > Technical > Reports > Reports. Clicking on button QWeb views will show you a list of related views created for a report.

Three nice features of QWeb that can beat Mako, I think, are:

  • Layout with HTML and XML syntaxes, plus we can add CSS formats to control the appearance.

  • Call Sub-template (<t t-call="other-template"/>) to reuse designs

  • Template Inheritance (<t t-extend="base.template">) to extend existing templates.

One interesting thing for normal users is that in Odoo, if I change the Report Type to HTML instead of PDF, I can even edit it on the interface in real time before printing. It is like a text editor that everyone without technical background can learn to use it easily.

There are more tutorials on the Internet, here are 2 articles from my old coworker Xuan Binh.

QWeb For Email Template

Maybe because of the advantages of QWeb, they started thinking about how to apply it for Email Templates. On OCA Github (The GitHub repos for all Open Source work around Odoo), two Odoo developers created the module email_template_qweb which is available for Odoo 8 and 9, and may be upgraded to Odoo 10 later on.


After install it, I can choose either QWeb engine or Jinja2 (Mako) engine to design the email body.

Mako template engine for email body


Qweb template engine for email body

And on Odoo Github, one of Odoo developers also implemented that, see [IMP] various: Conversion of mail templates from jinja to qweb. #13220 where they converted all email templates in Odoo to use QWeb. 20 days ago, a merge request to Odoo master branch was waiting for review. So if everything is fine, in Odoo 10, we could completely move to QWeb Email Templates. This is a big source code refactoring, also a revolution for Odoo Email Templates. 


In conclusion, I think it is good to use QWeb for both report templates and email templates because of the advantages from QWeb. Another reason, I think, is that we have the consistency in using one engine for designing templates from website pages, to reports, and now emails. I am not a truly technical consultant, I do not dive into the source code and techniques of QWeb, so my article should end here. The details are waiting for truly developers to discover.

  • Jens Holze on 11/23/2017 11:38:15

    Hieu, it looks that this is not finally done and merged into odoo v1 nor 11. Or i am wrong ?

  • Jens Holze on 11/23/2017 11:30:05

    Hieu, nice article . Had to read it again since i am back on the LR Migration :) - thanks. Good job.

  • Hieu Le on 07/24/2017 14:14:15

    @Daniel: thanks for reading and for your feedback!

  • Daniel Blanco on 07/24/2017 12:39:54

    I have tested, and prefer qweb, because you have an only way to write templates.. but there is a problem with emails: utf-8 chars are not supported, so special chars are misrepresented, and you can't use á - like notation.