From 4809f55cae196cd9bbd4c11d554a9b6a333245e4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?C=C3=A9dric=20Krier?= Date: Sun, 25 Dec 2022 11:12:14 +0100 Subject: [PATCH] Improve report documentation topic Out dated information are removed, links to demo server are added and a new section customize existing report from client is added. Closes #11925 --- trytond/doc/topics/reports/index.rst | 197 ++++++++++++++------------- 1 file changed, 100 insertions(+), 97 deletions(-) diff --git a/trytond/doc/topics/reports/index.rst b/trytond/doc/topics/reports/index.rst index bb84d011da..42b4756666 100644 --- a/trytond/doc/topics/reports/index.rst +++ b/trytond/doc/topics/reports/index.rst @@ -23,8 +23,7 @@ snippets of the Genshi_ templating language. Here is an example of the text that would be placed in an open document text document, ``*.odt``, that displays the full name and the address lines of the first address of each party. -The Genshi code is placed in the template using -``Functions->Placeholder->Text`` Fields. +The Genshi code is placed in the template using "Placeholder Text Fields". These are specific to ODT files. .. _relatorio: https://relatorio.tryton.org/ @@ -71,29 +70,20 @@ steps: - Remove user data - * "File > Properties..." + * Open :menuselection:`File --> Properties...` * Uncheck "Apply user data" - * Click on "Reset" + * Uncheck "Save preview image with this document" - - Select Style and Formatting - - * Press F11 or "Format > Style and Formatting" - - * Click on the drop down at the right top - - * Select "Load Styles" - - * Click on "From File..." - - * Select a existing report (``company/header_A4.odt``) + * Click on "Reset Properties" - Set some parameters * Set the zoom to 100% (View>Zoom) - * Set the document in read-only mode (``File>Properties>Security``) + * Set the document to read-only mode (:menuselection:`File --> Properties.. + --> Security`) (Decreases the time it takes to open the document.) - Usage @@ -106,34 +96,18 @@ steps: Using Genshi in an ODT file ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The Genshi code is placed in the template using Functions->Placeholder->Text -Fields. These are specific to ``*.odt`` files and can be found in the open -office menu at Insert -> Fields -> Other and then Functions -> Placeholder -> -Text. -Type Genshi code into the Placeholder field. +The Genshi code is placed in the template using "Placeholder Text Fields". +These are specific to ``*.odt`` files and can be found in the open office +:menuselection:`Insert --> Fields --> More Fields...` menu and then by +selecting Functions tab, Placeholder Type and Text Format. +The Genshi code is placed into the Placeholder value. There are alternatives for embedding Genshi that are supported by relatorio but their use is not encouraged within Tryton. -Also note that relatorio only supports a subset of Genshi. -The directives that are supported by relatorio can be found here: `Quick -Example`_ . - See Genshi's documentation for more information: `Genshi XML Template Language`_. -Examples -^^^^^^^^ - -The modules company, account_invoice and stock all contain helpful examples. - -Also see relatorio's site for some examples: - - - `Quick Example`_ - - - `In Depth Introduction`_ - - - `Example Documents`_ - +.. _Genshi XML Template Language: https://genshi.edgewall.org/wiki/Documentation/xml-templates.html Accessing models from within the report --------------------------------------- @@ -145,89 +119,126 @@ You can access any of the models relations as well. For example within the invoice report each record is an invoice and you can access the name of the party of the invoice via ``invoice.party.name``. Additional objects can be passed to a report. -This is discussed below in `Passing custom data to a report`_ +This is discussed below in `Passing custom values to a report`_ -Within Tryton the underlying model the report can be found by following the -Menu to ``Administration > UI > Actions > Report``. -Furthermore in Tryton the fields for that model can be found by following the -menu to ``Administration > Models > Models``. -Relation fields can be accessed to any depth. +Within Tryton the model, the report is based on, can be found by opening the +menu item: -Creating a simple report template for a model from client ---------------------------------------------------------- + |Administration --> Models --> Models|__ + + .. |Administration --> Models --> Models| replace:: :menuselection:`Administration --> Models --> Models` + __ https://demo.tryton.org/model/ir.model + +Furthermore in Tryton the fields for that model can be found by opening the +menu item: + + |Administration --> Models --> Models --> Fields|__ + + .. |Administration --> Models --> Models --> Fields| replace:: :menuselection:`Administration --> Models --> Models --> Fields` + __ https://demo.tryton.org/model/ir.model.field + + +Creating a simple report template for a model from the client +------------------------------------------------------------- + +Once you have created a report template it has to be uploaded to the server. +This can be done by creating a new record by opening the menu item: + + |Administration --> User Interface --> Actions --> Reports|__ + + .. |Administration --> User Interface --> Actions --> Reports| replace:: :menuselection:`Administration --> User Interface --> Actions --> Reports` + __ https://demo.tryton.org/model/ir.action.report -Once you have created a report template it has to be uploaded to ``trytond``. -This can be done by creating a new record in the ``Administration > UI > -Actions > Report`` menu. Just make sure to include the template file in the content field. In order to make the report printable from a record create a ``Print form`` keyword related to the model where the report should be available. -Creating a simple report template for a model in XML ----------------------------------------------------- +Customizing an existing report from the client +---------------------------------------------- -Less work has to be done if you just want a simple report representation of a -model. -First, create a report template file in a format supported by relatorio. -Second, describe your report in XML making sure to define the correct -``report_name`` and ``model``. +The content of existing reports can be updated from the menu item: -Replacing existing Tryton reports ---------------------------------- + :menuselection:`Administration --> User Interface --> Actions --> Reports` + +The easiest way is to download the existing content, edit it and upload it back +to the server. + +.. note:: + + It is possible to restore the original content by clearing the content and + saving the record. + + +Creating a simple report template for a model within a module +------------------------------------------------------------- + +Once you have created a report template stored in your module, you must create +an XML record of ``ir.action.report`` and another XML record of +``ir.action.keyword`` like: + +.. code-block:: xml + + + + + My Report + my_module.my_report + model.name + my_module/report.fodt + odt + + + form_print + model.name,-1 + + + + + +Replacing existing Tryton reports withing a module +-------------------------------------------------- To replace an existing report you must deactivate the old report and activate the new report. For example to deactivate the sale report: -.. highlight:: xml +.. code-block:: xml -:: + + + - - - +Then you must create your new sale report: -Then you must activate the new sale report that exists in your new module: +.. code-block:: xml -.. highlight:: xml - -:: - - - Sale - sale.sale - sale.sale - my_module/sale.odt - odt - - -And create the keyword for the new report: - -.. highlight:: xml - -:: - - + + Sale + sale.sale + sale.sale + my_module/sale.odt + odt + + form_print sale.sale,-1 - + -Passing custom data to a report -------------------------------- +Passing custom values to a report +--------------------------------- In this example ``Report.get_context`` is overridden and an employee record is set into context. Now the invoice report will be able to access the employee record. -.. highlight:: python - -:: +.. code-block:: python from tryton.pool import Pool from trytond.report import Report + from trytond.transaction import Transaction class InvoiceReport(Report): __name__ = 'account.invoice' @@ -243,11 +254,3 @@ Now the invoice report will be able to access the employee record. context['employee'] = employee return context - -.. _Genshi XML Template Language: https://genshi.edgewall.org/wiki/Documentation/xml-templates.html - -.. _Quick Example: https://relatorio.readthedocs.io/en/latest/quickexample.html - -.. _In Depth Introduction: https://relatorio.readthedocs.io/en/latest/indepthexample.html - -.. _Example Documents: http://hg.tryton.org/relatorio/file/default/examples