As one of the most popular and robust open-source ERP systems, Odoo has continuously evolved to meet the growing demands of businesses worldwide. The recent release of Odoo 18 brings with it several new features and enhancements aimed at improving user experience, efficiency, and flexibility. Among the core components of Odoo's dynamic framework are Qweb templates, which are used for generating reports, emails, and web pages. Qweb (Query Web) is Odoo’s templating engine, designed to facilitate the creation and manipulation of HTML structures in a modular and reusable way.
In this blog, we will explore Qweb templates in Odoo 18, delving into their structure, functionalities, and operations. We’ll also discuss how to extend and customize Qweb templates, as well as key operations you can perform to streamline your reporting and web content management in Odoo. By the end, you will have a solid understanding of how to use and manipulate Qweb templates in Odoo 18 for your own business or development needs.
What are Qweb Templates?
Qweb templates are a fundamental part of Odoo’s templating system. In simple terms, Qweb is a markup language that allows developers to define and structure the content to be displayed in the browser or in reports. The key advantage of Qweb is its flexibility; it can be used to generate various types of documents, including HTML pages, PDF reports, and emails.
Qweb templates rely on XML (Extensible Markup Language) to define the layout and content of a document, and they integrate seamlessly with Odoo’s models and views. The templating engine can pull data from Odoo’s database using Python expressions, making it possible to create highly dynamic and data-driven outputs. This is particularly useful for generating invoices, purchase orders, delivery slips, and other important documents that require real-time data.
In Odoo 18, Qweb templates have been further optimized to improve performance, especially in terms of rendering speed and memory consumption. This allows for a smoother experience when dealing with large datasets or generating complex reports.
Key Features of Qweb in Odoo 18
* Dynamic Content Rendering: Qweb templates can render dynamic content directly from Odoo's models, allowing you to display real-time data in reports and web pages.
* Flexible Layouts: Qweb provides flexibility in defining custom layouts, making it easy to build complex and detailed reports.
* Modular Structure: Templates can be extended or overridden to add new elements or modify existing ones without altering the core template. This is crucial for customizing documents to suit specific business needs.
* Integration with PDF and HTML Reports: Odoo’s reporting system relies heavily on Qweb templates, especially for generating PDFs. These templates are also used for generating HTML content on web pages.
* Reusability: You can define reusable template snippets in Qweb that can be called in multiple documents or views, reducing code duplication.
Structure of a Qweb Template
Qweb templates in Odoo 18 are defined using XML, and they typically consist of tags that define how content is structured and rendered. Below is an example of a simple Qweb template used to generate a report:
<template id="report_invoice">
<t t-call="web.html_container">
<t t-foreach="docs" t-as="o">
<t t-call="account.report_invoice_document">
<t t-set="company" t-value="o.company_id"/>
<t t-set="date" t-value="o.date_invoice"/>
<!-- Add more content here -->
</t>
</t>
</t>
</template>
Key Elements in a Qweb Template:
* <template>: This is the root tag that defines the Qweb template. Each template has a unique id attribute, which is used to reference the template.
* <t>: This is the core tag used in Qweb templates to handle dynamic content. It can be used for calling other templates, iterating over lists, setting variables, and applying conditionals.
* t-call: This attribute is used to call another Qweb template within the current template, enabling modularity and reuse of code.
* t-foreach: This attribute is used to iterate over a collection (e.g., a list of records), rendering the content dynamically for each item in the list.
* t-set: This attribute is used to define and set variables within the template. These variables can then be used to display dynamic content.
Operations in Qweb Templates
Qweb templates offer a wide range of operations that allow developers to manipulate data and structure documents efficiently. Below are some key operations you can perform in Qweb templates:
1. Variable Definition and Usage (t-set and t-value)
You can define variables in a Qweb template using the t-set attribute. These variables can store values that will be used later in the template. The t-value attribute assigns a value to the variable.
Example:
<t t-set="company_name" t-value="o.company_id.name"/>
<p>Company Name: <t t-esc="company_name"/></p>
In this example, the t-set tag defines a variable company_name with the value of o.company_id.name. This value is then displayed inside a paragraph tag.
2. Looping Over Data (t-foreach and t-as)
The t-foreach attribute is used to loop through a list of records and render content for each item in the list. The t-as attribute specifies the name of the variable for each iteration.
Example:
<t t-foreach="o.invoice_line_ids" t-as="line">
<tr>
<td><t t-esc="line.product_id.name"/></td>
<td><t t-esc="line.quantity"/></td>
<td><t t-esc="line.price_unit"/></td>
</tr>
</t>
In this example, the template iterates over each invoice_line_id in the invoice object o, and for each line, it displays the product name, quantity, and unit price.
3. Conditional Statements (t-if , t-elif and t-else)
Qweb templates support conditional logic using t-if, t-elif, and t-else. This allows you to control which content is rendered based on specific conditions.
Example:
<t t-if="o.state == 'draft'">
<p>Invoice is in draft state.</p>
<t t-elif="o.state == 'open'">
<p>Invoice is open.</p>
<t t-else="">
<p>Invoice is in another state.</p>
</t>
4. Including Other Templates (t-call)
You can include or call another Qweb template within the current template using the t-call attribute. This is useful for creating modular templates that can be reused in multiple places.
Example:
<t t-call="account.report_invoice_footer"/>
In this example, the template account.report_invoice_footer is called, and its content is included at the current location.
5. Escaping Content (t-esc t-raw)
In Qweb templates, the t-esc tag is used to escape content, ensuring that any special characters (e.g., <, >, &) are properly rendered as HTML entities. This is essential for preventing security vulnerabilities like cross-site scripting (XSS).
If you want to include raw content (e.g., HTML code), you can use the t-raw tag.
Example:
<p>Escaped Content: <t t-esc="o.name"/></p>
<p>Raw Content: <t t-raw="o.description_html"/></p>
6. Rendering Content Without Escaping (t-out)
The t-out tag outputs content directly without escaping. This is useful when you want to include raw HTML or other unescaped content in the template.
Example:
<t t-out="o.description_html"/>
This will render the description_html field as raw HTML, without escaping any characters.
7. Dynamic Attributes (t-att and t-attf-*)
The t-att tag allows you to dynamically set an attribute for an HTML element based on the value of a field.
Example:
<img t-att-src="'/web/image/product.product/' + str(o.product_id.id) + '/image_1920'"/>
In this example, the src attribute of the img tag is dynamically set based on the product's ID.
t-attf-* is a format string version of t-att, where placeholders are used for formatting.
Example:
<a t-attf-href="/my_url/{{ path }}">Link</a>8. Formatting Dates and Numbers
Qweb templates support various formatting options for dates, numbers, and currencies. You can use Python’s formatLang and formatDate methods within a Qweb template to format these values.
Example:
<p>Invoice Date: <t t-esc="formatDate(o.date_invoice, 'dd MMMM yyyy')"/></p>
<p>Total Amount: <t t-esc="formatLang(o.amount_total, currency_obj=o.currency_id)"/></p>
9. Debugging in Qweb (t-debug)
The t-debug tag allows you to insert debugging information into the template. It outputs the value of a variable or expression for debugging purposes.
Example:
<t t-debug="o.partner_id.name"/>
10. Logging Data for Debugging (t-log)
The t-log tag outputs content to the browser's JavaScript console, helping with debugging Qweb templates.
Example:
<t t-log="o.partner_id.name"/>
11. Multi-language Support (t-translation)
To ensure that your Qweb templates are multi-lingual, Odoo provides the t-translation tag, which helps in translating content based on the user's language preferences.
Example:
<t t-translation="Invoice Details"/>
This ensures that "Invoice Details" is translated according to the user’s selected language.
Extending and Customizing Qweb Templates in Odoo 18
Odoo allows developers to extend or modify existing Qweb templates to suit their needs. This is particularly useful when customizing reports or views for a specific business requirement. You can either extend a template by adding new content or completely override it.
Inheriting and Extending Templates
To extend a template, you need to inherit the existing template and add new elements to it. This is done using the xpath expression, which allows you to specify where to insert new content within the template.
Example:
<template id="report_invoice_inherit" inherit_id="account.report_invoice_document">
<xpath expr="//div[@class='header']" position="after">
<p>This is additional content added to the invoice report.</p>
</xpath>
</template>
In this example, the template report_invoice_inherit inherits the account.report_invoice_document template and adds new content right after the header section.
Overriding Templates
If you need to replace an entire template, you can override it by defining a new template with the same id. This will replace the original template with your customized version.
Example:
<template id="report_invoice">
<!-- Custom content -->
</template>
Qweb templates are a powerful and flexible tool within Odoo 18, allowing developers to create dynamic and customizable reports, emails, and web pages. With its XML-based structure, Qweb facilitates seamless integration of real-time data, making it indispensable for businesses that rely on accurate and visually appealing documentation. By mastering operations like looping, conditional rendering, variable handling, and template inheritance, developers can easily adapt Qweb to meet specific business needs. With the improvements introduced in Odoo 18, Qweb templates have become even more efficient, making them a core asset for managing dynamic content in the Odoo ecosystem.