237 lines
10 KiB
ReStructuredText
237 lines
10 KiB
ReStructuredText
.. image:: https://odoo-community.org/readme-banner-image
|
||
:target: https://odoo-community.org/get-involved?utm_source=readme
|
||
:alt: Odoo Community Association
|
||
|
||
==================
|
||
Py3o Report Engine
|
||
==================
|
||
|
||
..
|
||
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
||
!! This file is generated by oca-gen-addon-readme !!
|
||
!! changes will be overwritten. !!
|
||
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
||
!! source digest: sha256:dd09d33437e18bcf07a71714ec039c5a9795fbaa3d034b89a60a1d7d9f57ddb6
|
||
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
||
|
||
.. |badge1| image:: https://img.shields.io/badge/maturity-Beta-yellow.png
|
||
:target: https://odoo-community.org/page/development-status
|
||
:alt: Beta
|
||
.. |badge2| image:: https://img.shields.io/badge/license-AGPL--3-blue.png
|
||
:target: http://www.gnu.org/licenses/agpl-3.0-standalone.html
|
||
:alt: License: AGPL-3
|
||
.. |badge3| image:: https://img.shields.io/badge/github-OCA%2Freporting--engine-lightgray.png?logo=github
|
||
:target: https://github.com/OCA/reporting-engine/tree/18.0/report_py3o
|
||
:alt: OCA/reporting-engine
|
||
.. |badge4| image:: https://img.shields.io/badge/weblate-Translate%20me-F47D42.png
|
||
:target: https://translation.odoo-community.org/projects/reporting-engine-18-0/reporting-engine-18-0-report_py3o
|
||
:alt: Translate me on Weblate
|
||
.. |badge5| image:: https://img.shields.io/badge/runboat-Try%20me-875A7B.png
|
||
:target: https://runboat.odoo-community.org/builds?repo=OCA/reporting-engine&target_branch=18.0
|
||
:alt: Try me on Runboat
|
||
|
||
|badge1| |badge2| |badge3| |badge4| |badge5|
|
||
|
||
The py3o reporting engine is a reporting engine for Odoo based on
|
||
[Libreoffice](http://www.libreoffice.org/):
|
||
|
||
- the report is created with Libreoffice (ODT or ODS),
|
||
- the report is stored on the server in OpenDocument format (.odt or
|
||
.ods file)
|
||
- the report is sent to the user in OpenDocument format or in any output
|
||
format supported by Libreoffice (PDF, HTML, DOC, DOCX, Docbook, XLS,
|
||
etc.)
|
||
|
||
The key advantages of a Libreoffice based reporting engine are:
|
||
|
||
- no need to be a developer to create or modify a report: the report is
|
||
created and modified with Libreoffice. So this reporting engine has a
|
||
full WYSIWYG report development tool!
|
||
- For a PDF report in A4/Letter format, it's easier to develop it with a
|
||
tool such as Libreoffice that is designed to create A4/Letter
|
||
documents than to develop it in HTML/CSS, also some print
|
||
peculiarities (backgrounds, margin boxes) are not very well supported
|
||
by the HTML/CSS based solutions.
|
||
- If you want your users to be able to modify the document after its
|
||
generation by Odoo, just configure the document with ODT output (or
|
||
DOC or DOCX) and the user will be able to modify the document with
|
||
Libreoffice (or Word) after its generation by Odoo.
|
||
- Easy development of spreadsheet reports in ODS format (XLS output
|
||
possible).
|
||
|
||
This module *report_py3o* is the base module for the Py3o reporting
|
||
engine. If used alone, it will spawn a libreoffice process for each ODT
|
||
to PDF (or ODT to DOCX, ..) document conversion. This is slow and can
|
||
become a problem if you have a lot of reports to convert from ODT to
|
||
another format. In this case, you should consider the additionnal module
|
||
*report_py3o_fusion_server* which is designed to work with a libreoffice
|
||
daemon. With *report_py3o_fusion_server*, the technical environnement is
|
||
more complex to setup because you have to install additionnal software
|
||
components and run 2 daemons, but you have much better performances and
|
||
you can configure the libreoffice PDF export options in Odoo (allows to
|
||
generate PDF forms, PDF/A documents, password-protected PDFs,
|
||
watermarked PDFs, etc.).
|
||
|
||
This reporting engine is an alternative to
|
||
[Aeroo](https://github.com/aeroo-community/aeroo_reports): these two
|
||
reporting engines have similar features but their implementation is
|
||
entirely different. You cannot use aeroo templates as drop in
|
||
replacement though, you'll have to change a few details.
|
||
|
||
**Table of contents**
|
||
|
||
.. contents::
|
||
:local:
|
||
|
||
Installation
|
||
============
|
||
|
||
Install the required python libs:
|
||
|
||
:literal:`` pip install py3o.template pip install py3o.formats`\ \`
|
||
|
||
To allow the conversion of ODT or ODS reports to other formats (PDF,
|
||
DOC, DOCX, etc.), install libreoffice:
|
||
|
||
:literal:`` apt-get --no-install-recommends install libreoffice`\ \`
|
||
|
||
Configuration
|
||
=============
|
||
|
||
For example, to replace the native invoice report by a custom py3o
|
||
report, add the following XML file in your custom module:
|
||
|
||
:literal:`` <?xml version="1.0" encoding="utf-8"?> <odoo> <record id="account.account_invoices" model="ir.actions.report"> <field name="report_type">py3o</field> <field name="py3o_filetype">odt</field> <field name="module">my_custom_module_base</field> <field name="py3o_template_fallback">report/account_invoice.odt</field> </record> </odoo>`\ \`
|
||
|
||
where *my_custom_module_base* is the name of the custom Odoo module. In
|
||
this example, the invoice ODT file is located in
|
||
*my_custom_module_base/report/account_invoice.odt*.
|
||
|
||
It's also possible to reference a template located in a trusted path of
|
||
your Odoo server. In this case you must let the *module* entry empty and
|
||
specify the path to the template as *py3o_template_fallback*.
|
||
|
||
:literal:`` <?xml version="1.0" encoding="utf-8"?> <odoo> <record id="account.account_invoices" model="ir.actions.report"> <field name="report_type">py3o</field> <field name="py3o_filetype">odt</field> <field name="py3o_template_fallback">/odoo/templates/py3o/report/account_invoice.odt</field> </record> </odoo>`\ \`
|
||
|
||
Moreover, you must also modify the Odoo server configuration file to
|
||
declare the allowed root directory for your py3o templates. Only
|
||
templates located into this directory can be loaded by py3o report.
|
||
|
||
:literal:`` [options] ... [report_py3o] root_tmpl_path=/odoo/templates/py3o`\ \`
|
||
|
||
If you want an invoice in PDF format instead of ODT format, the XML file
|
||
should look like:
|
||
|
||
:literal:`` <?xml version="1.0" encoding="utf-8"?> <odoo> <record id="account.account_invoices" model="ir.actions.report"> <field name="report_type">py3o</field> <field name="py3o_filetype">pdf</field> <field name="module">my_custom_module_base</field> <field name="py3o_template_fallback">report/account_invoice.odt</field> </record> </odoo>`\ \`
|
||
|
||
If you want to add a new py3o PDF report (and not replace a native
|
||
report), the XML file should look like this:
|
||
|
||
:literal:`` <?xml version="1.0" encoding="utf-8"?> <odoo> <record id="partner_summary_report" model="ir.actions.report"> <field name="name">Partner Summary</field> <field name="model">res.partner</field> <field name="report_name">res.partner.summary</field> <field name="report_type">py3o</field> <field name="py3o_filetype">pdf</field> <field name="module">my_custom_module_base</field> <field name="py3o_template_fallback">report/partner_summary.odt</field> <!-- Add entry in "Print" drop-down list --> <field name="binding_type">report</field> <field name="binding_model_id" ref="base.model_res_partner"/> </record> </odoo>`\ \`
|
||
|
||
## Configuration parameters
|
||
|
||
py3o.conversion_command The command to be used to run the conversion,
|
||
libreoffice by default. If you change this, whatever you set here must
|
||
accept the parameters --headless --convert-to $ext $file and put the
|
||
resulting file into $file's directory with extension $ext. The command
|
||
will be started in $file's directory.
|
||
|
||
Usage
|
||
=====
|
||
|
||
The templating language is [extensively
|
||
documented](http://py3otemplate.readthedocs.io/en/latest/templating.html),
|
||
the records are exposed in libreoffice as objects, on which you can also
|
||
call functions.
|
||
|
||
## Available functions and objects
|
||
|
||
user Browse record of current user
|
||
|
||
lang The user's company's language as string (ISO code)
|
||
|
||
b64decode base64.b64decode
|
||
|
||
format_multiline_value(string) Generate the ODF equivalent of <br/> and
|
||
for multiline fields (ODF is XML internally, so those would be skipped
|
||
otherwise)
|
||
|
||
html_sanitize(string) Sanitize HTML string
|
||
|
||
time Python's time module
|
||
|
||
display_address(partner) Return a formatted string of the partner's
|
||
address
|
||
|
||
o_format_lang(value, lang_code=False, digits=None, grouping=True,
|
||
monetary=False, dp=False, currency_obj=False, no_break_space=True)
|
||
Return a formatted numeric or monetary value according to the context
|
||
language and timezone
|
||
|
||
o_format_date(value, lang_code=False, date_format=False) Return a
|
||
formatted date or time value according to the context language and
|
||
timezone
|
||
|
||
## Sample report templates
|
||
|
||
Sample py3o report templates for the main Odoo native reports (invoice,
|
||
sale order, purchase order, picking, etc.) are available on the Github
|
||
project
|
||
[odoo-py3o-report-templates](https://github.com/akretion/odoo-py3o-report-templates).
|
||
|
||
Known issues / Roadmap
|
||
======================
|
||
|
||
- generate barcode ?
|
||
- add more detailed example in demo file to showcase features
|
||
- add migration guide aeroo -> py3o
|
||
|
||
Bug Tracker
|
||
===========
|
||
|
||
Bugs are tracked on `GitHub Issues <https://github.com/OCA/reporting-engine/issues>`_.
|
||
In case of trouble, please check there if your issue has already been reported.
|
||
If you spotted it first, help us to smash it by providing a detailed and welcomed
|
||
`feedback <https://github.com/OCA/reporting-engine/issues/new?body=module:%20report_py3o%0Aversion:%2018.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**>`_.
|
||
|
||
Do not contact contributors directly about support or help with technical issues.
|
||
|
||
Credits
|
||
=======
|
||
|
||
Authors
|
||
-------
|
||
|
||
* XCG Consulting
|
||
* ACSONE SA/NV
|
||
|
||
Contributors
|
||
------------
|
||
|
||
- Florent Aide ([XCG Consulting](http://odoo.consulting/))
|
||
- Laurent Mignon <<laurent.mignon@acsone.eu>>,
|
||
- Alexis de Lattre <<alexis.delattre@akretion.com>>,
|
||
- Guewen Baconnier <<guewen.baconnier@camptocamp.com>>
|
||
- Omar Casti??eira <<omar@comunitea.com>>
|
||
- Holger Brunn <<hbrunn@therp.nl>>
|
||
- Phuc Tran Thanh <<phuc@trobz.com>>
|
||
- Souheil Bejaoui <<souheil.bejaoui@acsone.eu>>,
|
||
|
||
Maintainers
|
||
-----------
|
||
|
||
This module is maintained by the OCA.
|
||
|
||
.. image:: https://odoo-community.org/logo.png
|
||
:alt: Odoo Community Association
|
||
:target: https://odoo-community.org
|
||
|
||
OCA, or the Odoo Community Association, is a nonprofit organization whose
|
||
mission is to support the collaborative development of Odoo features and
|
||
promote its widespread use.
|
||
|
||
This module is part of the `OCA/reporting-engine <https://github.com/OCA/reporting-engine/tree/18.0/report_py3o>`_ project on GitHub.
|
||
|
||
You are welcome to contribute. To learn how please visit https://odoo-community.org/page/Contribute.
|