[IMP] Studio: new report editor

task-3553091

closes odoo/documentation#7517

X-original-commit: cf389c1c3e
Signed-off-by: Audrey Vandromme (auva) <auva@odoo.com>

content/applications/productivity/knowledge/articles_editing.rst

@@ -19,6 +19,8 @@ to move to the next line.
    later, you must do it manually. To do so, click the name on the top bar and proceed to the
    modification.
 
+.. _knowledge/text-editor:
+
 Text editor
 -----------
 
@@ -90,6 +92,8 @@ proceed equally and click the red-circled :guilabel:`x`.
    - The emoji is also displayed before the corresponding article in the side panel hierarchic tree.
    - Click the emoji on the side panel to change it without opening the related article.
 
+.. _knowledge/powerbox:
+
 Commands
 ========
 

content/applications/productivity/studio/pdf_reports.rst

@@ -2,341 +2,541 @@
 PDF reports
 ===========
 
-With Studio, you can edit existing PDF reports (e.g., orders and quotations) or create new ones.
-
-.. important::
-   To edit a standard PDF report, it is strongly recommended to **duplicate** it and make changes to
-   the duplicated version, as changes made to standard reports will be overwritten after an Odoo
-   upgrade. To duplicate a report, go to :menuselection:`Studio --> Reports`. Hover the mouse
-   pointer on the top right corner of the report, click the vertical ellipsis icon (:guilabel:`⋮`),
-   and then select :guilabel:`Duplicate`.
-
-   .. image:: pdf_reports/duplicate-report.png
-      :alt: Duplicating a PDF report
+With Studio, you can :ref:`edit existing PDF reports <studio/pdf-reports/edit>` (e.g., invoices,
+quotations, etc.) or :ref:`create new ones <studio/pdf-reports/edit>`.
 
 .. _studio/pdf-reports/default-layout:
 
 Default layout
 ==============
 
-The default layout of reports is managed outside Studio. Go to :menuselection:`Settings -->
-Companies: Document Layout --> Configure Document Layout`. Layout settings apply to all reports but
-only to the current company.
+The default layout of reports is managed outside Studio. Go to :menuselection:`Settings`, then, in
+the :guilabel:`Companies` section, click :guilabel:`Configure Document Layout`. Layout settings are
+company-specific but apply to all reports.
 
 .. tip::
-   Use :guilabel:`Download PDF Preview` to view how the different settings affect the layout of a
-   sample invoice.
+   You can see how the different settings affect the report layout in the report preview on the
+   right, or download  a sample invoice PDF by clicking :guilabel:`Download PDF Preview`.
+
+Use the following settings:
 
 .. _studio/pdf-reports/default-layout/layout:
 
-Layout
-------
+- :guilabel:`Layout`: Four layouts are available:
 
-Four layouts are available.
+  .. tabs::
 
-.. tabs::
+     .. tab:: Light
 
-   .. tab:: Light
+        .. image:: pdf_reports/layout-light.png
+           :alt: Light report layout sample
 
-      .. image:: pdf_reports/light.png
-         :alt: Light report layout sample
+     .. tab:: Boxed
 
-   .. tab:: Boxed
+        .. image:: pdf_reports/layout-boxed.png
+           :alt: Boxed report layout sample
 
-      .. image:: pdf_reports/boxed.png
-         :alt: Boxed report layout sample
+     .. tab:: Bold
 
-   .. tab:: Bold
+        .. image:: pdf_reports/layout-bold.png
+           :alt: Bold report layout sample
 
-      .. image:: pdf_reports/bold.png
-         :alt: Bold report layout sample
+     .. tab:: Striped
 
-   .. tab:: Striped
-
-      .. image:: pdf_reports/striped.png
-         :alt: Striped report layout sample
+        .. image:: pdf_reports/layout-striped.png
+           :alt: Striped report layout sample
 
 .. _studio/pdf-reports/default-layout/font:
 
-Font
-----
-
-Seven fonts are available. Click on the links below to preview them on `Google Fonts
-<https://fonts.google.com/>`_.
-
-- `Lato <https://fonts.google.com/specimen/Lato#type-tester>`_
-- `Roboto <https://fonts.google.com/specimen/Roboto#type-tester>`_
-- `Open Sans <https://fonts.google.com/specimen/Open+Sans#type-tester>`_
-- `Montserrat <https://fonts.google.com/specimen/Montserrat#type-tester>`_
-- `Oswald <https://fonts.google.com/specimen/Oswald#type-tester>`_
-- `Raleway <https://fonts.google.com/specimen/Raleway#type-tester>`_
-- `Tajawal <https://fonts.google.com/specimen/Tajawal#type-tester>`_
-
-  .. note::
-     :guilabel:`Tajawal` supports both Arabic and Latin scripts.
+- :guilabel:`Font`: Seven fonts are available: Lato, Roboto, Open Sans, Montserrat, Oswald, Raleway,
+  and Tajawal (which supports Arabic and Latin scripts). Go to the
+  `Google Fonts website <https://fonts.google.com/>`_ to preview them.
 
 .. _studio/pdf-reports/default-layout/logo:
 
-Company logo
-------------
-
-Upload an image file to add a :guilabel:`Company Logo`.
-
-.. note::
-   This adds the logo to the company’s record on the *Company* model, which you can access by going
-   to :menuselection:`General Settings --> Companies --> Update Info`.
+- :guilabel:`Company logo`: Click the :guilabel:`Edit` button to upload or change the logo. This
+  adds the logo to the company’s record on the *Company* model, which you can access by going to
+  :menuselection:`Settings` and then clicking :guilabel:`Update Info` in the :guilabel:`Companies`
+  section.
 
 .. _studio/pdf-reports/default-layout/colors:
 
-Colors
-------
-
-Change the primary and secondary colors used throughout reports to highlight important elements.
-The default colors are automatically generated based on the colors of the logo.
+- :guilabel:`Colors`: Change the primary and secondary colors used to structure reports. The default
+  colors are automatically generated based on the colors of the logo.
 
 .. _studio/pdf-reports/default-layout/background:
 
-Layout background
------------------
+- :guilabel:`Layout background`: The following backgrounds are available:
 
-Change the :guilabel:`Layout Background` of the report:
-
-- :guilabel:`Blank`: nothing is displayed.
-- :guilabel:`Geometric`: an image featuring geometric shapes is displayed in the background.
-- :guilabel:`Custom`: use a custom background image by uploading one.
+  - :guilabel:`Blank`: nothing is displayed.
+  - :guilabel:`Geometric`: an image featuring geometric shapes is displayed in the background.
+  - :guilabel:`Custom`: upload a custom background image.
 
 .. _studio/pdf-reports/default-layout/tagline:
 
-Company tagline
----------------
-
-The :guilabel:`Company Tagline` is displayed on the header of :ref:`External reports
-<studio/pdf-reports/header-footer/external>`. You can add multiple lines of text.
+- :guilabel:`Company tagline`: This is displayed in the header of :ref:`external reports
+  <studio/pdf-reports/header-footer/external>`. You can add multiple lines of text.
 
 .. _studio/pdf-reports/default-layout/details:
 
-Company details
----------------
-
-The :guilabel:`Company Details` are displayed on the header of :ref:`External reports
-<studio/pdf-reports/header-footer/external>`. You can add multiple lines of text.
+- :guilabel:`Company details`: These are displayed in the header of :ref:`external reports
+  <studio/pdf-reports/header-footer/external>`. You can add multiple lines of text.
 
 .. _studio/pdf-reports/default-layout/footer:
 
-Footer
-------
-
-Use the :guilabel:`Footer` field to put any text in the :ref:`External reports'
-<studio/pdf-reports/header-footer/external>` footers. You can add multiple lines of text.
+- :guilabel:`Footer`: This text is used in the footer of :ref:`external reports
+  <studio/pdf-reports/header-footer/external>`. You can add multiple lines of text. You can also
+  edit the footer using the :ref:`report editor <studio/pdf-reports/edit>`.
 
 .. _studio/pdf-reports/default-layout/paper:
 
-Paper format
-------------
+- :guilabel:`Paper format`: to define the default paper size of reports. You can select
+  :guilabel:`A4` (21 cm x 29.7 cm), :guilabel:`US Letter` (21.59 cm x 27.54 cm), or
+  :guilabel:`QR codes page`. This can also be defined for individual reports in the
+  :guilabel:`Paper format` field in :ref:`Studio <studio/pdf-reports/create>`.
 
-Use the :guilabel:`Paper format` field to change the paper size of reports. You can either select
-:guilabel:`A4` (21 cm x 29.7 cm) or :guilabel:`US Letter` (21.59 cm x 27.54 cm).
+.. _studio/pdf-reports/create:
 
-.. tip::
-   You can change the :guilabel:`Paper format` on individual reports. Open the app containing the
-   report, then go to :menuselection:`Studio --> Reports --> Select or Create a report --> Report
-   --> Select a Paper format`.
+Creating new PDF reports
+========================
 
-.. image:: pdf_reports/default-layout.png
-   :alt: Configuration pop-up window for the default layout of PDF reports
-
-.. _studio/pdf-reports/header-footer:
-
-Header and footer
-=================
-
-When creating a new report in Studio, you must choose between one of three styles of reports first.
-This is solely used to determine what is displayed on the header and footer. To do so, go to the app
-on which you want to add a new report, click the **Toggle Studio** button, then click
-:guilabel:`Reports`. Click :guilabel:`New` and select
-:ref:`studio/pdf-reports/header-footer/external`, :ref:`studio/pdf-reports/header-footer/internal`,
-or :ref:`studio/pdf-reports/header-footer/blank`.
+To create a new report for a model, access the model, click the **Toggle Studio** button, then click
+:guilabel:`Reports`. Click :guilabel:`New` and, in the popup window that opens, select the type of
+report. This is solely used to determine what is displayed in the header and footer:
 
 .. _studio/pdf-reports/header-footer/external:
 
-External
---------
+- :guilabel:`External`:
 
-The header displays the company :ref:`studio/pdf-reports/default-layout/logo` and several values
-set on the *Company* model: the :guilabel:`Company Name`, :guilabel:`Phone`, :guilabel:`Email`, and
-:guilabel:`Website`.
+  - The header displays the company's :ref:`logo <studio/pdf-reports/default-layout/logo>`,
+    :ref:`tagline <studio/pdf-reports/default-layout/tagline>`, and
+    :ref:`details <studio/pdf-reports/default-layout/details>`.
+  - The footer displays the values set in the
+    :ref:`Footer <studio/pdf-reports/default-layout/footer>` field and the page number.
+
+- :guilabel:`Internal`: The header displays the user's current date and time,
+  :guilabel:`Company Name`, and page number. There is no footer.
+
+- :guilabel:`Blank`: There is neither a header nor a footer. Click in the upper left corner of the
+  page to edit the report.
+
+Once you have created the report, you can start :ref:`editing it <studio/pdf-reports/edit>`.
+
+.. _studio/pdf-reports/edit:
+
+Editing PDF reports
+===================
+
+To access the reports available for a model, access the model (e.g., sales orders), click the
+**Toggle Studio** button, then click :guilabel:`Reports`. Select an existing report to open it or
+:ref:`create a new one <studio/pdf-reports/create>`.
 
 .. tip::
-   To change a company's information, go to :menuselection:`Settings --> Companies --> Update Info`.
+   Alternatively, you can also open Studio, click :guilabel:`Reports`, and search for a specific
+   report or model.
 
-.. image:: pdf_reports/external-header.png
-   :alt: Example of an External header
+.. important::
+   It is strongly recommended to **duplicate** the standard report and perform changes in the
+   duplicated version. To duplicate a report, hover the mouse pointer on the top right corner
+   of the report, click the vertical ellipsis icon (:guilabel:`⋮`), and then select
+   :guilabel:`Duplicate`.
 
-The footer displays the values set on the :ref:`studio/pdf-reports/default-layout/footer`,
-:ref:`studio/pdf-reports/default-layout/details`, and
-:ref:`studio/pdf-reports/default-layout/tagline` fields, as well as the page number.
+   .. image:: pdf_reports/duplicate-report.png
+      :alt: Duplicating a PDF report
 
-.. image:: pdf_reports/external-footer.png
-   :alt: Example of an External footer
+Options
+-------
 
-.. _studio/pdf-reports/header-footer/internal:
+Once you've selected or created a report, you can use the options in the left part of the screen to:
 
-Internal
---------
-
-The header displays the user's current date and time, :guilabel:`Company Name`, and page number.
-
-There is no footer.
-
-.. _studio/pdf-reports/header-footer/blank:
-
-Blank
------
-
-There is neither a header nor a footer.
-
-.. _studio/pdf-reports/elements:
-
-Add tab
-=======
-
-After opening an existing report or creating a new one, go to the :guilabel:`Add` tab to add or edit
-elements. The elements are organized into four categories: :ref:`studio/pdf-reports/elements/block`,
-:ref:`studio/pdf-reports/elements/inline`, :ref:`studio/pdf-reports/elements/table`, and
-:ref:`studio/pdf-reports/elements/column`.
-
-.. _studio/pdf-reports/elements/block:
-
-Block
------
-
-Block elements start on a new line and occupy the full width of the page.
-
-.. tip::
-   You can set an element's width by selecting it and going to the :guilabel:`Options` tab.
-
-- :guilabel:`Text`: add any text using small font size by default.
-
-- :guilabel:`Title Block`: add any text using larger font size by default.
-
-- :guilabel:`Image`: add an image. You can either upload one from your device, add one from
-  an URL, or select one already existing on your database.
-
-- :guilabel:`Field`: dynamically add a field's value.
-
-- :guilabel:`Field & Label`: to dynamically add a field's value and label.
-
-- :guilabel:`Address Block`: to dynamically add the values, if any, of a contact's (`res.partner`
-  model): *Name*, *Address*, *Phone*, *Mobile*, and *Email*.
-
-  .. image:: pdf_reports/address-block.png
-     :alt: Example of an Address Block
-
-.. _studio/pdf-reports/elements/inline:
-
-Inline
-------
-
-Inline elements are used around other elements. They do not start on a new line and the width adapts
-to length of the content.
-
-.. tip::
-   You can set an element's width and margins by selecting it and going to the :guilabel:`Options`
-   tab.
-
-- :guilabel:`Text`: add any text using small font size by default.
-
-- :guilabel:`Field`: dynamically add a field's value.
-
-.. _studio/pdf-reports/elements/table:
-
-Table
------
-
-Table elements are used together to create a data table.
-
-- :guilabel:`Data table`: create a table and dynamically add a first column displaying the *Name*
-  values of a :ref:`Many2Many <studio/fields/relational-fields/many2many>` or :ref:`One2Many
-  <studio/fields/relational-fields/one2many>` field on your model.
-
-  .. image:: pdf_reports/data-table.png
-     :alt: Example of a Data table
-
-- :guilabel:`Field Column`: add a new column to the table displaying the values of a :ref:`Related
-  Field <studio/fields/relational-fields/related-field>` to the one used to create the
-  :guilabel:`Data table`.
-
-- :guilabel:`Text in Cell`: add any text within an existing table cell.
-
-- :guilabel:`Field in Cell`: add, within an existing table cell, the values of a :ref:`Related
-  Field <studio/fields/relational-fields/related-field>` to the one used to create the
-  :guilabel:`Data table`.
-
-- :guilabel:`Subtotal & Total`: add an existing :guilabel:`Total` field's value. If a
-  :guilabel:`Taxes` field exists, the untaxed and taxes amounts are added before the total amount.
-
-.. _studio/pdf-reports/elements/column:
-
-Column
-------
-
-Columns are used to add multiple :ref:`blocks <studio/pdf-reports/elements/block>` elements on the
-same line.
-
-- :guilabel:`Two Columns`: add any text in two different columns.
-
-- :guilabel:`Three Columns`: add any text in three different columns.
-
-Report tab
-==========
-
-Several configuration options are available under the :guilabel:`Report` tab.
-
-- :guilabel:`Name`: change the report name. The new name is applied everywhere (in Studio, under
-  the :guilabel:`Print` button, and for the PDF file name).
-
-- :guilabel:`Paper format`: change the paper size of the report.
-
-- :guilabel:`Add in print`: add the report under the :guilabel:`🖶 Print` button available on the
+- Change the :guilabel:`Report name`. The new name is applied everywhere (in Studio, under
+  the :guilabel:`Print` button, and in the PDF file name).
+- Modify the :guilabel:`Paper format`. If no value is selected, the format defined in the
+  :ref:`default layout <studio/pdf-reports/default-layout/paper>` is used.
+- :guilabel:`Show in print menu`: to add the report in the :guilabel:`Print` menu available from the
   record.
-
-- :guilabel:`Limit visibility to groups`: limit the availability of the PDF report to specific
+- :guilabel:`Reload from attachment`: to save the report as an attachment on the record the first
+  time it is generated and reload the original version of the report any subsequent time. This is
+  legally required for invoices and is mainly used in this case.
+- :guilabel:`Limit visibility to groups`: to limit the availability of the PDF report to specific
   :doc:`user groups <../../general/users/access_rights>`.
+- :guilabel:`Edit sources`: to modify the report directly in the :ref:`XML file
+  <studio/pdf-reports/XML-editing>`.
+- :guilabel:`Reset report`: to discard all changes made to the report and reset it to its standard
+  version.
+- :guilabel:`Print preview`: to generate and download a report preview.
 
-Options tab
-===========
+Report editor
+-------------
 
-Select an element on the report to access the element's options and edit it.
+The report editor allows you to modify the formatting and contents of the report.
 
-.. image:: pdf_reports/text-options-tab.png
-   :alt: The Options tab for a text element
+.. tip::
+  - You can :guilabel:`Undo` or :guilabel:`Redo` changes using the related buttons or the shortcuts
+    `CTRL Z` and `CTRL Y`.
+
+  - Changes are saved automatically when you leave the report or manually using the
+    :guilabel:`Save` button.
+
+  - You can reset the report to its standard version by clicking the :guilabel:`Reset report` button
+    in the left part of the screen.
+
+.. important::
+   Editing the header and footer of a report impacts all standard and custom reports.
+
+Conditional blocks
+~~~~~~~~~~~~~~~~~~
+
+The dashed rectangles represent **conditional blocks** (*if/else* statements). These are used to
+show/hide content based on specific conditions. Click on the block to view the conditions.
+
+.. image:: pdf_reports/conditional-block-if.png
+   :alt: View conditions applied to a block.
+
+Select a value to preview its corresponding output and edit it if necessary.
+
+.. image:: pdf_reports/conditional-block-else.png
+   :alt: Preview the output of another condition.
 
 .. note::
-   You can select and edit multiple elements at the same time by clicking on the different sections
-   or divisions (e.g., `div`, `table`, etc.).
+   Conditions can only be edited in :ref:`XML <studio/pdf-reports/XML-editing>`.
 
-Below are presented some of the most common options:
+Other content
+~~~~~~~~~~~~~
 
-- :guilabel:`Margins`: add spacing at the :guilabel:`top`, :guilabel:`right`, :guilabel:`bottom`,
-  and :guilabel:`left` of the element.
+There are two types of text content in reports:
 
-- :guilabel:`Width`: set the element's maximum width.
+- Static text, i.e., the text that's not highlighted in blue, which can be modified directly in the
+  editor.
+- Dynamic text, i.e., the text that's highlighted in blue, which is replaced by field values when
+  the report is generated, e.g., the SO number or the quotation date.
 
-- :guilabel:`Visible if`: set under which condition(s) the element should be displayed.
+You can add content (e.g., fields, lists, tables, images, banners, etc.) to the report using
+commands. Type `/` to open the :ref:`powerbox <knowledge/powerbox>`, then type the command's
+name or select it from the list.
 
-- :guilabel:`Visible for`: set for which :doc:`users groups <../../general/users/access_rights>`
-  the element should be displayed.
+To add static text to the report, type the text where you want it.
 
-- :guilabel:`Remove from View`: remove the element from the report's view.
+For more advanced changes, you can :ref:`edit the report in the XML directly
+<studio/pdf-reports/XML-editing>`.
 
-- :guilabel:`Text decoration`: bold, italicize, and underline the font.
+.. _studio/pdf-reports/add-field:
 
-- :guilabel:`Alignment`: align the element to the left, center, or right of the report.
+Add a field
+***********
 
-- :guilabel:`Font style`: use one of the default font styles.
+To add a field, type `/` and select the :guilabel:`Field` command. In the list that opens, select
+or search for the field; click the right arrow next to the field name to access the list of related
+fields if needed. Then, specify the default value and press `Enter`.
 
-- :guilabel:`Colors`: change the font's color and the background color.
+.. image:: pdf_reports/powerbox-field.png
+   :alt: Select a related field.
 
-.. note::
-   You may need to select a section or division above the element you want to edit to see some of
-   the options described above.
+Formatting
+**********
+
+To format text in the report, select it, then format it using the options in the
+:ref:`knowledge/text-editor`.
+
+  .. image:: pdf_reports/text-editor.png
+     :alt: Format text using the text editor.
+
+.. _studio/pdf-reports/XML-editing:
+
+Editing the report's XML
+------------------------
+
+.. warning::
+   Modifying the XML directly may result in report issues during :doc:`upgrades
+   <../../../administration/upgrade>`. If this happens, simply copy your changes from the old
+   database into your upgraded database.
+
+To edit the report's XML, click :guilabel:`Edit sources` in the left pane.
+
+Examples
+~~~~~~~~
+
+.. spoiler:: Modify a non-compliant table
+
+   Sometimes, tables are not properly recognized as such due to complex structures. In those cases,
+   you can still modify them manually in the report XML. For example, with a sales order, you can
+   find the following structure in the XML (simplified for documentation purposes):
+
+    .. code-block:: xml
+
+       <!-- table root element -->
+       <table>
+           <!-- thead = table header, the row with column titles -->
+           <thead>
+               <!-- table row element -->
+               <tr>
+                   <!-- table header element -->
+                   <th>Name</th>
+                   <th>Price</th>
+               </tr>
+           </thead>
+           <!-- table body, the main content -->
+           <tbody>
+               <!-- we create a row for each subrecord with t-foreach -->
+               <tr t-foreach="record.some_relation_ids" t-as="line">
+                   <!-- for each line, we output the name and price as table cells -->
+                   <td t-out="line.name"/>
+                   <td t-out="line.price"/>
+               </tr>
+           </tbody>
+       </table>
+
+    To modify a table, you must ensure that each row has the same number of data cells. For example,
+    in the case above, you need to add a cell in the header section (with e.g., the column title)
+    and another one in the body section with the field content (usually, with a `t-out` or
+    `t-field` directive).
+
+    .. code-block:: xml
+       :emphasize-lines: 6,13
+
+       <table> <!-- table root element -->
+           <thead> <!-- thead = table header, the row with column titles -->
+               <tr> <!-- table row element -->
+                   <th>Name</th> <!-- table header element -->
+                   <th>Price</th>
+                   <th>Category</th>
+               </tr>
+           </thead>
+           <tbody>  <!-- table body, the main content -->
+               <tr t-foreach="record.some_relation_ids" t-as="line">  <!-- we create a row for each subrecord with t-foreach -->
+                   <td t-out="line.name"/>  <!-- for each line, we output the name and price as table cells -->
+                   <td t-out="line.price"/>
+                   <td t-out="line.category_id.display_name"/>
+               </tr>
+           </tbody>
+       </table>
+
+    .. note::
+       Cells can span multiple rows or columns. For more information, go to the
+       `Mozilla Developer Network website <https://developer.mozilla.org/en-US/docs/Learn/HTML/Tables/Basics>`_.
+
+    For example, you can modify the **Quotation/Order** report to add a column to display the
+    product category in the main table:
+
+      .. code-block:: xml
+         :emphasize-lines: 6,13
+
+         <table class="table table-sm o_main_table table-borderless mt-4">
+             <!-- In case we want to repeat the header, remove "display: table-row-group" -->
+             <thead style="display: table-row-group">
+                 <tr>
+                     <th name="th_description" class="text-start">Description</th>
+                     <th>Product Category</th>
+                     <th name="th_quantity" class="text-end">Quantity</th>
+                     <th name="th_priceunit" class="text-end">Unit Price</th>
+         [...]
+                     <tr t-att-class="'bg-200 fw-bold o_line_section' if line.display_type == 'line_section' else 'fst-italic o_line_note' if line.display_type == 'line_note' else ''">
+                         <t t-if="not line.display_type">
+                             <td name="td_name"><span t-field="line.name">Bacon Burger</span></td>
+                             <td t-out="line.product_id.categ_id.display_name"/>
+                             <td name="td_quantity" class="text-end">
+                                 <span t-field="line.product_uom_qty">3</span>
+                                 <span t-field="line.product_uom">units</span>
+                                 <span t-if="line.product_packaging_id">
+
+    .. image:: pdf_reports/XML-SO-product-category.png
+       :alt: Add a Product Category column in a SO.
+
+.. spoiler:: Add a data table
+
+   To add a table in XML, you need to know the names of the fields and objects you wish to access
+   and display. As an example, let's add a table that details the tags on a sales order:
+
+   .. code-block:: xml
+
+      <!-- table root element -->
+      <table class="table">
+          <!-- thead = table header, the row with column titles -->
+          <thead>
+              <!-- table row element -->
+              <tr>
+                  <!-- table header element -->
+                  <th>ID</th>
+                  <th>Name</th>
+              </tr>
+          </thead>
+          <!-- table body, the main content -->
+          <tbody>
+              <!-- we create a row for each subrecord with t-foreach -->
+              <tr t-foreach="doc.tag_ids" t-as="tag">
+                  <!-- for each line, we output the name and price as table cells -->
+                  <td t-out="tag.id"/>
+                  <td t-out="tag.name"/>
+              </tr>
+          </tbody>
+      </table>
+
+   .. image:: pdf_reports/XML-data-table.png
+      :alt: Add a data table in XML
+
+   .. note::
+      When adding tables manually, style them using `Bootstrap classes
+      <https://getbootstrap.com/docs/5.1/content/tables>`_, like the `table` class included in the
+      example above.
+
+.. spoiler:: Conditional blocks
+
+   If you want to show/hide content based on specific conditions, you can manually add `if/else`
+   control statements in the report XML.
+
+   For example, if you want to hide a custom data table if there are no tags, you can use the `t-if`
+   attribute to define the condition, which is then evaluated as `True` or `False`. The table will
+   not be displayed if there are no tags in the quotation.
+
+   .. code-block:: xml
+      :emphasize-lines: 2
+
+      <!-- table root element -->
+      <table class="table" t-if="len(doc.tag_ids) > 0">
+          <!-- thead = table header, the row with column titles -->
+          <thead>
+              <!-- table row element -->
+              <tr>
+                  <!-- table header element -->
+                  <th>ID</th>
+                  <th>Name</th>
+              </tr>
+          </thead>
+          <!-- table body, the main content -->
+          <tbody>
+              <!-- we create a row for each subrecord with t-foreach -->
+              <tr t-foreach="doc.tag_ids" t-as="tag">
+                  <!-- for each line, we output the name and price as table cells -->
+                  <td t-out="tag.id"/>
+                  <td t-out="tag.name"/>
+              </tr>
+          </tbody>
+      </table>
+
+   If you want to display another block in case the `t-if` statement is evaluated as `False`, you
+   can specify it using the `t-else` statement. The `t-else` block must directly follow the `t-if`
+   block in the document structure. There is no need to specify any condition in the `t-else`
+   attribute. As an example, let's show a quick message explaining that there are no tags on the
+   quotation:
+
+   .. code-block:: xml
+      :emphasize-lines: 22
+
+      <!-- table root element -->
+      <table class="table" t-if="len(doc.tag_ids) > 0">
+          <!-- thead = table header, the row with column titles -->
+          <thead>
+              <!-- table row element -->
+              <tr>
+                  <!-- table header element -->
+                  <th>ID</th>
+                  <th>Name</th>
+              </tr>
+          </thead>
+          <!-- table body, the main content -->
+          <tbody>
+              <!-- we create a row for each subrecord with t-foreach -->
+              <tr t-foreach="doc.tag_ids" t-as="tag">
+                  <!-- for each line, we output the name and price as table cells -->
+                  <td t-out="tag.id"/>
+                  <td t-out="tag.name"/>
+              </tr>
+          </tbody>
+      </table>
+      <div class="text-muted" t-else="">No tag present on this document.</div>
+
+   By using the `t-if/t-else` notation, the report editor recognizes that these sections are
+   mutually exclusive and should be displayed as conditional blocks:
+
+   .. image:: pdf_reports/XML-condition-if.png
+      :alt: Output preview if there are tags.
+
+   You can switch conditions using the editor to preview their output:
+
+   .. image:: pdf_reports/XML-condition-else.png
+      :alt: Output preview if there are no tags.
+
+   If you wish to have multiple options, you can also use `t-elif` directives to add intermediary
+   conditions. For example, this is how the title of sales order reports changes based on the
+   condition of the underlying document.
+
+   .. code-block:: xml
+
+      <h2 class="mt-4">
+          <span t-if="env.context.get('proforma', False) or is_pro_forma">Pro-Forma Invoice # </span>
+          <span t-elif="doc.state in ['draft','sent']">Quotation # </span>
+          <span t-else="">Order # </span>
+          <span t-field="doc.name">SO0000</span>
+      </h2>
+
+   The title *Pro-Forma Invoice* is used depending on some contextual conditions. If these
+   conditions are not met and the state of the document is either `draft` or `sent`, then
+   *Quotation* is used. If none of those conditions are met, the report's title is *Order*.
+
+.. spoiler:: Images
+
+   Working with images in a report can be challenging, as precise control over image size and
+   behavior is not always obvious. You can insert image fields using the report editor
+   (:ref:`by using the /Field command <studio/pdf-reports/add-field>`), but inserting them in XML
+   using the `t-field` directive and accompanying `t-options` attributes provides better sizing and
+   positioning control.
+
+   For example, the following code outputs the field `image_128` of the line's product as a
+   64px-wide image (with an automatic height based on the image's aspect ratio).
+
+   .. code-block:: xml
+
+      <span t-field="line.product_id.image_128" t-options-widget="image" t-options-width="64px"/>
+
+   The following options are available for image widgets:
+
+   - `width`: width of the image, usually in pixels or CSS length units (e.g., `rem`) (leave empty
+     for auto-width).
+   - `height`: height of the image, usually in pixels or CSS length units (e.g., `rem`) (leave empty
+     for auto-height).
+   - `class`: CSS classes applied on the `img` tag; `Bootstrap classes
+     <https://getbootstrap.com/docs/5.1/content/tables>`_ are available.
+   - `alt`: alternative text of the image
+   - `style`: style attribute; it allows you to override styles more freely than with
+     `Bootstrap classes <https://getbootstrap.com/docs/5.1/content/tables>`_.
+
+   These attributes must contain strings, i.e., text enclosed within quotes within quotes, e.g.,
+   `t-options-width="'64px'"` (or, alternatively, a valid Python expression).
+
+   .. note::
+      The image widget cannot be used on an `img` tag. Instead, set the `t-field` directive on a
+      `span` (for inline content) or `div` (for block content) node.
+
+   For example, let's add a column with the product image in the quotation table:
+
+   .. code-block:: xml
+      :emphasize-lines: 4,14-20
+
+      <table class="table table-sm o_main_table table-borderless mt-4">
+          <thead style="display: table-row-group">
+              <tr>
+                  <th>Image</th>
+                  <th name="th_description" class="text-start">Description</th>
+                  <th>Product Category</th>
+                  <th name="th_quantity" class="text-end">Quantity</th>
+                  <th name="th_priceunit" class="text-end">Unit Price</th>
+      [...]
+              <t t-foreach="lines_to_report" t-as="line">
+                  <t t-set="current_subtotal" t-value="current_subtotal + line.price_subtotal"/>
+                  <tr t-att-class="'bg-200 fw-bold o_line_section' if line.display_type == 'line_section' else 'fst-italic o_line_note' if line.display_type == 'line_note' else ''">
+                      <t t-if="not line.display_type">
+                         <td>
+                             <span t-field="line.product_template_id.image_128"
+                                   t-options-widget="'image'"
+                                   t-options-width="'64px'"
+                                   t-options-class="'rounded-3 shadow img-thumbnail'"
+                                 />
+                         </td>
+                          <td name="td_name"><span t-field="line.name">Bacon Burger</span></td>
+                          <td t-out="line.product_id.categ_id.display_name"/>
+
+   The `t-options-width` attribute restricts the image width to 64 pixels, and the Bootstrap classes
+   used in `t-options-class` create a thumbnail-like border with rounded corners and a shadow.
+
+   .. image:: pdf_reports/XML-images.png
+      :alt: Add a column with the product image in the quotation table.