Overview

deltatech_document_template provides a generic, reusable engine to define document templates and generate finalized documents from them in Odoo 19. It is business‑agnostic and can target any model via res_model/res_id. The module supports mixed content (manual HTML, embedded QWeb reports, or QWeb views), a simple workflow on generated documents, and a Print menu integration that opens or reuses a unique generated document per template and target record.

Key Concepts

• Document Template (document.template):
  • Defines the target model (res_model).
  • Holds an ordered list of sections (document.template.section).
  • Can register a Print‑menu server action on the target model that opens a generated document (creating one if needed).
• Template Section (document.template.section):
  • Defines one piece of content for a template, ordered by sequence.
  • Content types (content_type):
    • html – manual HTML (body_html) rendered as a QWeb fragment with placeholders (e.g., t-esc="o.display_name").
    • report – an embedded QWeb report (report_id) rendered for the target record; sanitized before insertion to avoid nested layouts/duplicate pages.
    • view – a QWeb template/view (view_id) rendered for the target record.
  • page_break_after inserts a page break between sections when generating a document.
• Generated Document (document.generated):
  • Instantiates a template for a specific record (res_model via template, and res_id).
  • Concatenates all sections to produce the final HTML body, with QWeb rendering and embedded report sanitization.
  • Has a workflow: Draft → Generated → Validated.
  • “Print PDF” action exports the current body via a dedicated QWeb PDF report and auto‑attaches the output to the target record.

Main Features

• Model‑agnostic: target any model by setting res_model on the template and res_id on the generated document.
• Mixed content assembly with QWeb rendering:
  • Manual HTML sections (QWeb fragment with placeholders and conditionals).
  • Embedded report sections (existing ir.actions.report on the target model), sanitized to avoid nested external_layout/div.page wrappers.
  • Embedded QWeb view sections by view_id.
• Page breaks between sections using <div style="page-break-before: always;"></div> when page_break_after is set (never appended after the last section).
• Print menu integration (server action with binding_type = 'report'): opens an existing document.generated for the active record and template, or starts a new one if it does not exist yet.
• Uniqueness enforced: only one generated document per (template_id, res_model, res_id) via a Python constraint (no _sql_constraints in Odoo 19).
• Clear workflow with button visibility by state:
  • Generate: visible in Draft/Generated; hidden in Validated.
  • Validate: visible in Generated only.
  • Reset to Draft: visible in Generated/Validated.
  • Print PDF: visible in Generated/Validated.
• Printing auto‑attaches the resulting PDF (or HTML fallback) to the target res_model/res_id.
• Chatter integration: when a generated document is created (or when its target is set later), a note with a link to the generated document is posted automatically on the target record’s chatter.

Models & Fields

1. document.template
   • name (Char): Optional label of the template.
   • res_model (Char): Technical name of the target model (e.g., res.partner).
   • section_ids (One2many): Related document.template.section rows.
   • server_action_id (Many2one → ir.actions.server, readonly): Optional server action bound to the model’s Print menu to open/reuse a generated document.
2. document.template.section
   • name (Char, required)
   • sequence (Integer): Ordering within the template.
   • template_id (Many2one → document.template)
   • content_type (Selection): html | report | view (default html).
   • body_html (Html, QWeb‑enabled): Manual content with placeholders and directives; sanitized settings keep QWeb attributes.
   • report_id (Many2one → ir.actions.report): For content_type = 'report'. Domain constrained to template’s res_model and QWeb types.
   • view_id (Many2one → ir.ui.view): For content_type = 'view' (QWeb views/templates).
   • page_break_after (Boolean): Insert a page break after this section (not after the last section overall).
   • res_model (Char, related): Mirrors template_id.res_model for editors and dynamic placeholders.
   • Helpers: action_clear_report() clears report_id.
3. document.generated
   • name (Char, computed): “: “ or “Generated Document”.
   • template_id (Many2one → document.template, required)
   • res_model (Char, related & stored): From template.
   • res_id (Many2oneReference): Target record ID, validated against res_model.
   • body (Html): Concatenated result built from sections.
   • date_issued (Date): Defaults to today.
   • state (Selection): draft, generated, validated.
   • Uniqueness: one row per (template_id, res_model, res_id) enforced by a server‑side constraint.
   • Actions:
     • action_generate(): Build body from sections with QWeb rendering and embedded report sanitization, then set state to generated.
     • action_validate(): Set state to validated.
     • action_reset_to_draft(): Set state back to draft.
     • action_print_pdf(): Render QWeb PDF and return action; also auto‑attach the output to the target record (res_model/res_id).

User Interface

• Templates: Tree and form views to define res_model and manage sections inline. Button box to add/remove the Print‑menu server action.
• Sections: Standalone tree and form; fields shown depend on content_type (report/view/body_html). The HTML widget is configured with code view and dynamic placeholders enabled. A “Clear Report” button resets report_id.
• Generated Documents: Tree and form with header buttons for workflow and printing. Button visibility adapts to state (see above). Body is shown for review/edit in a notebook tab.
• Menus: Under Settings → Technical → Document Templates
  • Templates
  • Sections
  • Generated Documents

Printing

• Generated documents have a dedicated QWeb PDF report (report_document_generated_action). The QWeb template wraps the body within the standard external layout; it avoids adding extra page wrappers so embedded reports are not duplicated.
• The “Print PDF” action is available in states generated and validated and will auto‑attach the produced file to the target record. If PDF rendering is not available, an HTML attachment is stored as fallback.

Print‑menu Integration

• Each template can register a server action (bound to the target model with binding_type='report') that appears under the model’s Print menu.
• When invoked on a record, it opens the existing document.generated for (template_id, res_model, active_id) if present; otherwise, it opens the creation form with defaults (default_template_id, default_res_model, default_res_id).

Typical Workflow

1. Create a Document Template and set its res_model (e.g., res.partner). Optionally register the Print‑menu action.
2. Add one or more Sections and choose their content_type:
   • html: author content with QWeb placeholders in body_html;
   • report: select a report to embed; the module will sanitize the HTML before insertion;
   • view: select a QWeb view/template to render.
   • Enable page_break_after where you want page boundaries.
3. Create a Generated Document (either via the Print menu on a target record or manually):
   • Pick the template and the target res_id (defaults are filled by the Print‑menu action).
   • Click Generate to assemble content from sections.
   • Use Print PDF (available from generated) to review or share; the file will be attached to the target record. Validate once finalized.

Compatibility

• Targeted at Odoo 19 and aligned with its UI guidelines (no legacy attrs/states in XML). The views use simple invisible expressions where needed.
• The standalone web view for document.generated uses the new editor stack: html_builder/html_editor assets (Odoo 19). No legacy web_editor bundle is used.

Installation

1. Ensure the module path is on your addons_path (this repository already configures custom paths in the provided .conf).

2. Install the module:

   ./odoo/odoo-bin -c odoo18.conf -d o19_dev -i deltatech_document_template --stop-after-init
   

• Running Tests

• The module ships with SavepointCase tests that cover: QWeb rendering for manual HTML, report/view sections, sanitization/page breaks, uniqueness constraint, Print‑menu server action (open existing vs create new), and printing with auto‑attachment.

• Run tests in a disposable database:

  ./odoo/odoo-bin -c odoo18.conf -d o19_test -u deltatech_document_template --test-tags=deltatech_document_template --stop-after-init
  

Security

• Basic ACLs allow internal users (base.group_user) to create, read, update, and delete templates, sections, and generated documents.

Known Limitations & Notes

• Reports defined strictly for PDF may not provide HTML rendering for embedding; the section falls back to its manual body_html when this occurs.
• The sanitizer removes common layout wrappers (e.g., web.external_layout, web.html_container, div.page) from embedded reports and keeps the inner page content to avoid duplication when printing the final PDF.
• The generated HTML body is printed through a dedicated QWeb PDF wrapper; ensure your PDF stack (wkhtmltopdf or Qt‑WebEngine based) handles page breaks and CSS as expected.

Table of contents

Authors

• Deltatech

Maintainers

This module is part of the terrabit-ro/bitshop project on GitHub.

You are welcome to contribute.