Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 39 ยท Reports and Integration

QWeb PDF Reports

Build PDF and HTML reports in Odoo: ir.actions.report, the report template, docs and doc_ids, external_layout, paper formats, translations and a runnable report-rendering stand-in.

Invoices, delivery slips, payslips, quotations: business software lives on printable documents. In Odoo a report is a QWeb template (QWeb Templates) plus a small report action record that links the template to a model. When a user clicks Print, Odoo renders the template to HTML on the server, then converts that HTML to PDF with the external program wkhtmltopdf.

The real renderer cannot run here, so Odoo code is read-only, and the stand-ins render a report to text and compute totals the way a template would.

The two records

XML
<odoo>
  <record id="action_report_loan_card" model="ir.actions.report">
    <field name="name">Loan card</field>
    <field name="model">library.loan</field>
    <field name="report_type">qweb-pdf</field>
    <field name="report_name">library.report_loan_card</field>
    <field name="report_file">library.report_loan_card</field>
    <field name="print_report_name">'Loan-%s' % object.name</field>
    <field name="binding_model_id" ref="model_library_loan"/>
    <field name="binding_type">report</field>
  </record>

  <template id="report_loan_card">
    <t t-call="web.html_container">
      <t t-foreach="docs" t-as="doc">
        <t t-call="web.external_layout">
          <div class="page">
            <h2>Loan <span t-field="doc.name"/></h2>
            <p>Member: <span t-field="doc.member_id"/></p>
            <p>Due: <span t-field="doc.date_due"/></p>
            <table class="table table-sm">
              <thead><tr><th>Book</th><th class="text-end">Fee</th></tr></thead>
              <tbody>
                <tr t-foreach="doc.line_ids" t-as="line">
                  <td t-field="line.book_id"/>
                  <td class="text-end" t-field="line.fee"/>
                </tr>
              </tbody>
            </table>
          </div>
        </t>
      </t>
    </t>
  </template>
</odoo>

The report action fields:

  • report_type: qweb-pdf, qweb-html or qweb-text.
  • report_name: the XML ID of the template, written module.template_id.
  • print_report_name: a Python expression for the downloaded file name; object is the record.
  • binding_model_id and binding_type: attach the report to the Print (Action) menu of that model's form and list.
  • paperformat_id: optional link to a paper format (page size, margins).

The template receives these variables: docs (the selected records, with the user's access rights), doc_ids, doc_model, plus user, res_company and helper values.

t-field versus t-out

t-field is the report favourite: it takes a field expression of a record and formats it by type, with currency symbols, dates in the user's language and many2one display names, and it supports t-options (for example {"widget": "monetary"}). t-out simply prints a value. In reports prefer t-field for record fields so formatting and translation are correct.

web.external_layout supplies the company header, footer and page numbers for documents sent to partners, and web.internal_layout is for internal papers. Your template provides only the div class="page". The company's Document Layout wizard (Settings) chooses the colours, font and style; developers rarely touch the layout code. wkhtmltopdf renders the header and footer in separate HTML files; that is why custom CSS sometimes needs special care.

flowchart LR
    A["Print button"] --> B["ir.actions.report"]
    B --> C["QWeb renders HTML<br/>(docs = records)"]
    C --> D["wkhtmltopdf"]
    D --> E["PDF download"]

The server renders HTML first; wkhtmltopdf turns it into a PDF.

Paper format

XML
<record id="paperformat_label" model="report.paperformat">
  <field name="name">Library label</field>
  <field name="format">custom</field>
  <field name="page_height">80</field>
  <field name="page_width">100</field>
  <field name="orientation">Landscape</field>
  <field name="margin_top">5</field>
  <field name="margin_bottom">5</field>
  <field name="dpi">90</field>
</record>

Link it from the report action with <field name="paperformat_id" ref="paperformat_label"/>. Choosing the format for each report is how label printers and A4 sheets coexist.

Custom data: report parsers

Sometimes the template needs more than the record fields, for example computed totals across many records. Define an AbstractModel named report.<module>.<template_id> with a _get_report_values method:

Python
class LoanReport(models.AbstractModel):
    _name = "report.library.report_loan_card"
    _description = "Loan card report"

    @api.model
    def _get_report_values(self, docids, data=None):
        docs = self.env["library.loan"].browse(docids)
        return {
            "doc_ids": docids,
            "doc_model": "library.loan",
            "docs": docs,
            "total_fee": sum(docs.line_ids.mapped("fee")),
        }

The returned dict becomes the variables of the template. Keep calculations in Python and keep the template for layout.

A report renderer stand-in

The first stand-in renders documents with a layout and a body, computing a total before rendering, as _get_report_values does.

Python Render a report with totals

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.

Format helpers

t-field formats values for you. The second stand-in mimics three formatting jobs: money, dates and a missing value, using Python's standard tools.

Python Format fields like t-field

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.

Practical tips

  • Preview a report as HTML first by using the URL /report/html/<report_name>/<ids> while in developer mode; it is much faster to debug than PDFs.
  • Install wkhtmltopdf (version 0.12.6 with patched Qt) on every server that prints; without it Odoo shows a warning and falls back to HTML.
  • Test with a record that has very long names, many lines and special characters, because tables break across pages.
  • Translate the template: static text in templates is picked up as translatable terms, and t-lang can render a document in the partner's language.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which two pieces make up a printable Odoo report?

    The action links the template to a model and adds the Print entry; the template draws the document.
  2. 2. Which variable holds the selected records inside a report template?

    docs is the recordset, usually iterated with t-foreach.
  3. 3. What tool converts the rendered HTML into PDF?

    Odoo uses wkhtmltopdf for qweb-pdf reports; a missing install explains many layout problems.
  4. 4. Where do you compute extra values such as grand totals for a report?

    The parser model returns a dictionary that becomes the template variables.

Summary

  • A report = ir.actions.report record + QWeb template.
  • Templates iterate docs, use t-field for formatted values and web.external_layout for the frame.
  • qweb-html previews are fast; qweb-pdf goes through wkhtmltopdf.
  • Paper formats control size and margins; _get_report_values supplies computed data.

Next: Controllers and Routes