Chapter 12: Creating Printable PDF Reports with Server-Side QWeb

While a regular view can provide valuable information to users, there will be cases where a printed output is needed. Maybe it is a PDF document to be sent to a customer, or a paper document that is needed to support a physical process. To address these cases, Odoo apps support printed business reports. These are generated using QWeb and then exported to PDF documents, which can then be printed, emailed, or simply stored.

Being QWeb-based means that the same skills that can be used for Kanban views and web pages can be reused to design reports. Beyond QWeb, specific mechanisms are used, such as report actions, paper formats, and the variables that are available for QWeb report rendering.

In this chapter, examples will be used to illustrate how to structure and add content to a report. The usual report structure has a header, details, and footer sections. The content that can be added includes field data, including...

Technical requirements

This chapter expands the existing library_app add-on module, based on the code first created in Chapter 3, Your First Odoo Application. This chapter's code can be found in this book's GitHub repository at https://github.com/PacktPublishing/Odoo-15-Development-Essentials in the ch12/ subdirectory.

Installing wkhtmltopdf

Odoo reports are just HTML pages that are then converted into PDF files. For this conversion, the wkhtmltopdf command-line tool is used. Its name stands for Webkit HTML to PDF.

For reports to be generated correctly, the recommended version of the wkhtmltopdf utility needs to be installed. Some versions of the wkhtmltopdf library are known to have issues, such as not printing page headers and footers, so we need to be picky about the version we use.

Since Odoo 10, version 0.12.5 is the officially recommended one. The most up-to-date Odoo information about wkhtmltopdf can be found at https://github.com/odoo/odoo/wiki/Wkhtmltopdf.

The packaged version provided by Debian or Ubuntu may not be appropriate. So, the recommendation is to directly download and install the correct package. The download links can be found at https://github.com/wkhtmltopdf/wkhtmltopdf/releases/tag/0.12.5.

To install the correct version of wkhtmltopdf, follow these steps:

...

Creating business reports

It would be helpful for the Library app to print out a report containing the book catalog. This report should list the book titles, along with details such as publisher, publishing date, and authors.

We will implement this throughout this chapter, and in the process showcase the several techniques involved in implementing Odoo reports. The report will be added to the existing library_app module.

The convention is to have report files in a /reports subdirectory, so a reports/library_book_report.xml data file will be added. As usual, when adding data files, remember to also declare them in the data key of the __manifest__.py file.

To be able to run a report, the first thing we must add is the report action.

Adding the report action

The report action triggers the execution of a report, similarly to how window actions trigger web client view presentations. A report action is a record in the ir.actions.report XML model, and it can be inspected by...

Designing report content

The report content is written in HTML and makes use of Bootstrap 4 to help design the report's layout. Bootstrap is widely used in web development.

Tip

A complete reference can be found at http://getbootstrap.com.

Unlike Kanban views, the report QWeb templates are rendered on the server side and use the Python QWeb implementation. So, there are some differences to be aware of, compared to the JavaScript QWeb implementation. QWeb expressions are evaluated using Python syntax, not JavaScript.

Understanding the report rendering context

The server-side context where expressions are evaluated is also different from the client-side context that's used for Kanban views. On a report template, the following variables are available:

• docs is an iterable collection with the records to render the report for.
• doc_ids is a list of the IDs of the records to render the report for.
• doc_model identifies the model of the records; for example...

Creating custom reports

By default, a report is rendered for the selected records and is available in the rendering context through the docs variable. In some cases, it is useful to prepare arbitrary data structures to be used in the report. This is possible using custom reports.

A custom report can add whatever data that's needed to the report rendering context. This is done using an abstract model with a specific name, following the naming convention of report.<module>.<report-name>.

This model should implement a _get_report_values() method, which returns a dictionary with the variables to add to the rendering context.

As an example, a Books by Publisher custom report will be added to the Library app. It will show the books that have been published by each publisher. The following screenshot shows an example of the report's output:

Figure 12.4 – Example of the Books by Publisher custom report

The report will be available...

Further reading

This additional reference material complements the topics described in this chapter.

Relevant Odoo official documentation:

• QWeb Reports: https://www.odoo.com/documentation/15.0/developer/reference/backend/reports.html
• QWeb Templates: https://www.odoo.com/documentation/15.0/developer/reference/frontend/qweb.html
• Bootstrap 4 official documentation: https://getbootstrap.com/docs/4.1

Other relevant resources:

• The Odoo Community Association hosts a project dedicated to the enhanced report feature at https://github.com/OCA/reporting-engine.
• Bootstrap additional learning resources from Packt Publishing can be found at https://www.packtpub.com/tech/bootstrap.