odoo-forge-bundle 0.1.0

package/payload/skills/odoo18-docs/references/docs/applications/studio/pdf_reports.md

@@ -0,0 +1,558 @@
+---
+title: "PDF reports"
+source_url: "https://docs.odoo.sbggai.top/applications/studio/pdf_reports.html"
+---
+
+===========
+# PDF reports
+
+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`, then, in
+the :guilabel:`Companies` section of the main page, click :guilabel:`Configure Document Layout`.
+Layout settings are company-specific but apply to all reports.
+
+> **tip**:
+>    You can see how the different settings affect the report layout in the report preview on the
+   right side of the :guilabel:`Configure your document layout` window. When creating or editing a
+   report, you can see a preview of the report by clicking :guilabel:`Print preview` on the left
+   side of the screen.
+
+Use the following settings:
+
+.. _studio/pdf-reports/default-layout-layout:
+
+- :guilabel:`Layout`: Seven layouts are available:
+
+  .. tabs::
+
+     .. tab:: Light
+
+        .. image:: pdf_reports/layout-light.png
+           :alt: Light report layout sample
+           :scale: 90%
+
+     .. tab:: Boxed
+
+        .. image:: pdf_reports/layout-boxed.png
+           :alt: Boxed report layout sample
+           :scale: 90%
+
+     .. tab:: Bold
+
+        .. image:: pdf_reports/layout-bold.png
+           :alt: Bold report layout sample
+           :scale: 90%
+
+     .. tab:: Striped
+
+        .. image:: pdf_reports/layout-striped.png
+           :alt: Striped report layout sample
+           :scale: 90%
+
+     .. tab:: Bubble
+
+        .. image:: pdf_reports/layout-bubble.png
+           :alt: Bubble report layout sample
+           :scale: 90%
+
+     .. tab:: Wave
+
+        .. image:: pdf_reports/layout-wave.png
+           :alt: Wave report layout sample
+           :scale: 90%
+
+     .. tab:: Folder
+
+        .. image:: pdf_reports/layout-folder.png
+           :alt: Folder report layout sample
+           :scale: 90%
+
+.. _studio/pdf-reports/default-layout-background:
+
+- :guilabel:`Background`: The following backgrounds are available:
+
+  - :guilabel:`Blank`: Nothing is displayed.
+  - :guilabel:`Demo logo`: A demo logo is displayed in the background.
+  - :guilabel:`Custom`: Upload a custom background image.
+
+.. _studio/pdf-reports/default-layout-font:
+
+- :guilabel:`Text`: Eight fonts are available: Lato, Roboto, Open Sans, Montserrat, Oswald,
+  Raleway, Tajawal (which supports Arabic and Latin scripts), and Fira Mono. Go to the [Google Fonts
+  website ](https://fonts.google.com/) to preview them.
+
+.. _studio/pdf-reports/default-layout-logo:
+
+- :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:
+
+- :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-address:
+
+- :guilabel:`Address`: The company name and address are displayed in the header of :ref:`external
+  reports <studio/pdf-reports/header-footer>`. You can add multiple lines of text.
+
+.. _studio/pdf-reports/default-layout-tagline:
+
+- :guilabel:`Tagline`: This is displayed in the header of :ref:`external reports
+  <studio/pdf-reports/header-footer>` using the Light, Striped, Bubble, Wave and Folder
+  layouts and in the footer of external reports using the Boxed and Bold layouts. You
+  can add multiple lines of text.
+
+.. _studio/pdf-reports/default-layout-footer:
+
+- :guilabel:`Footer`: This text is used in the footer of :ref:`external reports
+  <studio/pdf-reports/header-footer>`. 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:
+
+- :guilabel:`Paper format`: This defines the default paper size of reports. You can select
+  :guilabel:`A4` (21 cm x 29.7 cm) and :guilabel:`US Letter` (21.59 cm x 27.54 cm). This can also be
+  defined for individual reports in the :guilabel:`Paper format` field in
+  :ref:`Studio <studio/pdf-reports/edit-options>`.
+
+  > **note**:
+>      Other paper formats may be available depending on which apps or modules you have installed, for
+     example, label sheets for the Inventory app or event badges for the Events app.
+
+.. _studio/pdf-reports/create:
+
+# Creating new PDF reports
+
+To create a new report for a :doc:`model </applications/studio/models_modules_apps>`,
+(e.g., sales orders) access the model, click the :icon:`oi-studio` (:guilabel:`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:
+
+- :guilabel:`External`:
+
+  - The header displays the company's :ref:`logo <studio/pdf-reports/default-layout-logo>` and its
+    :ref:`name and address <studio/pdf-reports/default-layout-address>`. For reports using the
+    Light, Striped, Bubble, Wave and Folder layouts, the
+    :ref:`tagline <studio/pdf-reports/default-layout-tagline>` also appears in the header.
+
+  - The footer displays the values set in the
+    :ref:`Footer <studio/pdf-reports/default-layout-footer>` field and the page number. For
+    reports using the Boxed and Bold layouts, the
+    :ref:`tagline <studio/pdf-reports/default-layout-tagline>` also appears in the footer.
+
+- :guilabel:`Internal`: The header displays the user's current date and time, the company's
+  :ref:`name and address <studio/pdf-reports/default-layout-address>` and the 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, click the
+:icon:`oi-studio` (:guilabel:`Toggle Studio`) button, then click :guilabel:`Reports`. Select an
+existing report to open it.
+
+Alternatively, you can also open Studio, click :guilabel:`Reports`, and search for a specific
+report or model.
+
+> **important**:
+>    It is strongly recommended to **duplicate** the standard report and make changes in the
+   duplicated version. To duplicate a report, hover the mouse pointer on the top right corner
+   of the report, click the :icon:`fa-ellipsis-vertical` (:guilabel:`vertical ellipsis`) icon, and
+   then select :guilabel:`Duplicate`.
+
+   .. image:: pdf_reports/duplicate-report.png
+      :alt: Duplicating a PDF report
+
+.. _studio/pdf-reports/edit-options:
+
+## Options
+
+Once you have selected or created a report, you can use the options in the left part of the screen
+to:
+
+- Change the :guilabel:`Report name`: The new name is applied everywhere (in Studio, in the
+  :guilabel:`Print` menu under the :icon:`fa-cog` (:guilabel:`gear`) icon in the form view, 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 to the :guilabel:`Print` menu in the form view.
+- :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.
+
+.. _studio/pdf-reports/report-editor:
+
+## Report editor
+
+The report editor allows you to modify the content and formatting of the report.
+
+> **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**:
+>    Conditions can only be edited in the :ref:`XML <studio/pdf-reports/XML-editing>`.
+
+### Other content
+
+There are two types of text content in reports:
+
+- Static text, i.e., the text that is not highlighted in blue, which can be modified directly in the
+  editor.
+- Dynamic text, i.e., the text that is highlighted in blue, which is replaced by
+  :doc:`field </applications/studio/fields>` values when the report is generated, e.g., the sales order number or
+  the quotation date.
+
+You can add content (e.g., fields, lists, tables, images, banners, etc.) to the report using
+commands. Type `/` to open the :ref:`powerbox <essentials/html_editor/commands>`, then type the
+command's name or select it from the list.
+
+To add static text to the report, type the text where you want it.
+
+For more advanced changes, you can :ref:`edit the report in the XML directly
+<studio/pdf-reports/XML-editing>`.
+
+.. _studio/pdf-reports/add-field:
+
+Add a field
+***********
+
+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 that will be shown if the field is not completed
+in the record and press `Enter`.
+
+.. image:: pdf_reports/powerbox-field.png
+   :alt: Select a related field.
+
+.. _studio/pdf-reports/add-edit-table:
+
+Add or edit a table
+*******************
+
+There are two types of tables in reports:
+
+- :ref:`Static tables <studio/pdf-reports/static-table>`, which are used to display static text or fields. For this type of table, you define
+  the number of columns and rows when adding the table.
+- :ref:`Dynamic tables <studio/pdf-reports/dynamic-table>`, which are used to display data from
+  :ref:`relational fields <studio/fields/relational-fields>`.
+  For this type of table, you only define the number of columns when adding the table. The number
+  of rows in the generated report will be determined by the number of records in the related model
+  that are linked with the current model.
+
+  .. example::
+     In a sales order report, a dynamic table is used to show the order lines related to the sales
+     order. If the sales order contains 10 order lines, the table in the generated report has 10 rows;
+     if it contains two order lines, the table has two rows.
+
+.. _studio/pdf-reports/static-table:
+
+#### Add or edit a static table
+
+To add a static table, type `/` and select the :guilabel:`Table` command. Determine the number of
+columns and rows for the table. Once the table has been added, you can start editing it.
+
+You can insert, move and delete columns and rows using the table tools. Position the cursor on top
+of the column or to the left of the row then click the purple rectangle and select an option.
+
+.. image:: pdf_reports/table-tools.png
+   :alt: List of available options for editing table structure.
+
+To resize a column, drag the column border to the desired position; reset all columns
+to their standard size by selecting :guilabel:`Reset Size` from the table tools.
+
+Add the :ref:`field of your choice <studio/pdf-reports/add-field>` in a cell or add static text
+by typing.
+
+> **tip**:
+>    To add text in a structured way without using a table, you can use columns. Add columns by
+   typing `/` and selecting the appropriate command: :guilabel:`2 columns`, :guilabel:`3 columns` or
+   :guilabel:`4 columns`.
+
+.. _studio/pdf-reports/dynamic-table:
+
+#### Add or edit a dynamic table
+
+  > **note**:
+>      - Only relations of type `one2many` or `many2many` can be displayed as dynamic tables.
+     - An existing dynamic table in a standard report has a more complex structure than a dynamic table
+       you add yourself. For such tables, it is possible to insert or delete columns; it is not possible
+       to move columns or to insert, move or delete rows.
+
+To add a dynamic table, type `/` and select the :guilabel:`Dynamic Table` command. In the list that
+opens, select or search for the relation the table will be based on and press `Enter`. Once the
+table has been added, you can start editing it.
+
+You can insert, move and delete columns using the table tools, as for a
+:ref:`static table <studio/pdf-reports/static-table>`. It is also possible to insert static rows
+that will appear above or below the generated rows.
+
+To add a field to a cell, delete any placeholder text then add the :ref:`field of your choice
+<studio/pdf-reports/add-field>`. The dialog box that opens shows the source object for the
+field (e.g., the *Order Lines* model) and the list of available fields.
+
+.. image:: pdf_reports/available-fields.png
+   :alt: List of available fields for the sale order lines model.
+
+Replace the :guilabel:`Column name` label by the label of your choice.
+
+> **note**:
+>    The default row automatically iterates over the field's content, generating a row on the report
+   for each field value (e.g., one row per order line).
+
+Formatting
+**********
+
+To format text in the report, select it, then format it using the options in the
+:doc:`text editor </applications/essentials/html_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 the widget of a field
+
+   To change how data is presented in your report, you can modify a field's default
+   :doc:`widget </applications/studio/fields>` manually. In the example below, the order date shows
+   the date and time by default, while the unit price defaults to a precision of two decimal
+   places.
+
+   ```xml
+      :emphasize-lines: 2,3
+
+      <div class="oe_structure">
+       <span t-field="doc.date_order"/>
+       <span t-field="doc.price_unit"/>
+      </div>
+
+  By using `t-options`, in this case the `widget` option, these fields can be modified to show
+  only the date and a precision of four decimal places, respectively:
+
+   ```xml
+      :emphasize-lines: 2,3
+
+      <div class="oe_structure">
+       <span t-field="doc.date_order" t-options="{'widget': 'date'}"/>
+       <span t-field="doc.price_unit" t-options="{'widget': 'float', 'precision': 4}"/>
+      </div>
+
+.. 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.
+
+   ```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:
+
+   ```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.
+
+   ```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
+   (by using the :ref:`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).
+
+   ```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:
+
+   ```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.