diff --git a/doc/reference/actions.rst b/doc/reference/actions.rst index fe2dfb6d68c..a0698be5516 100644 --- a/doc/reference/actions.rst +++ b/doc/reference/actions.rst @@ -370,10 +370,36 @@ server actions: .. _reference/actions/report: -Report Actions -============== +Report Actions (``ir.actions.report.xml``) +========================================== -.. todo:: sle-odoo +Triggers the printing of a report + +``name`` (mandatory) + only useful as a mnemonic/description of the report when looking for one + in a list of some sort +``model`` (mandatory) + the model your report will be about +``report_type`` (mandatory) + either ``qweb-pdf`` for PDF reports or ``qweb-html`` for HTML +``report_name`` + the name of your report (which will be the name of the PDF output) +``groups_id`` + :class:`~openerp.fields.Many2many` field to the groups allowed to view/use + the current report +``paperformat_id`` + :class:`~openerp.fields.Many2one` field to the paper format you wish to + use for this report (if not specified, the company format will be used) +``attachment_use`` + if set to ``True``, the report is only generated once the first time it is + requested, and re-printed from the stored report afterwards instead of + being re-generated every time. + + Can be used for reports which must only be generated once (e.g. for legal + reasons) +``attachment`` + python expression that defines the name of the report; the record is + accessible as the variable ``object`` .. _reference/actions/client: diff --git a/doc/reference/reports.rst b/doc/reference/reports.rst index 7dfbfb1c8c7..6f33100aedd 100644 --- a/doc/reference/reports.rst +++ b/doc/reference/reports.rst @@ -1,37 +1,126 @@ -.. _reference/reports: +.. highlight:: xml ============ QWeb Reports ============ -Paper Formats -------------- +Reports are written in HTML/QWeb, like all regular views in Odoo. You can use +the usual :ref:`QWeb control flow tools `. The PDF rendering +itself is performed by wkhtmltopdf_. -There is a model called Paper Format allowing to define details specific to -the PDF output. These details include margins, header line, ... Everything -related to the printed pdf. Defining a paper format is not mandatory as there -is a default one set on the company. If you want a specific report to be -associated to a specific paper format , just link the ir.actions.report.xml to -it. +If you want to create a report on a certain model, you will need to define +this :ref:`reference/reports/report` and the +:ref:`reference/reports/templates` it will use. If you wish, you can also +specify a specific :ref:`reference/reports/paper_formats` for this +report. Finally, if you need access to more than your model, you can define a +:ref:`reference/reports/custom_reports` class that gives you access to more +models and records in the template. -Expressions used in Odoo report templates ------------------------------------------ +.. _reference/reports/report: -There are some magic variables used in the report rendering. The main ones are -the following: +Report +====== + +Every report must be declared by a :ref:`report action +`. + +For simplicity, a shortcut ```` element is available to define a +report, rather than have to set up :ref:`the action +` and its surroundings manually. That ```` +can take the following attributes: + +``id`` + the generated record's :term:`external id` +``name`` (mandatory) + only useful as a mnemonic/description of the report when looking for one + in a list of some sort +``model`` (mandatory) + the model your report will be about +``report_type`` (mandatory) + either ``qweb-pdf`` for PDF reports or ``qweb-html`` for HTML +``report_name`` + the name of your report (which will be the name of the PDF output) +``groups`` + :class:`~openerp.fields.Many2many` field to the groups allowed to view/use + the current report +``attachment_use`` + if set to True, the report will be stored as an attachment of the record + using the name generated by the ``attachment`` expression; you can use + this if you need your report to be generated only once (for legal reasons, + for example) +``attachment`` + python expression that defines the name of the report; the record is + acessible as the variable ``object`` + +.. warning:: + + The paper format cannot currently be declared via the ```` + shortcut, it must be added afterwards using a ```` extension on the + report action itself:: + + + + + +Example:: + + + +.. _reference/reports/templates: + +Report template +=============== + + +Minimal viable template +----------------------- + +A minimal template would look like:: + + + +Calling ``external_layout`` will add the default header and footer on your +report. The PDF body will be the content inside the ``
``. The template's ``id`` must be the name specified in the +report declaration; for example ``account.report_invoice`` for the above +report. Since this is a QWeb template, you can access all the fields of the +``docs`` objects received by the template. + +There are some specific variables accessible in reports, mainly: ``docs`` records for the current report ``doc_ids`` list of ids for the ``docs`` records ``doc_model`` - model for teh ``docs`` records + model for the ``docs`` records ``time`` - a reference to time_ from the Python standard library + a reference to :mod:`python:time` from the Python standard library ``translate_doc`` a function to translate a part of a report. It must be used as follow: - .. code-block:: xml + :: @@ -39,36 +128,182 @@ the following: ``user`` ``res.user`` record for the user printing the report ``res_company`` - record the current ``user``'s company + record for the current ``user``'s company -Custom report -------------- +If you wish to access other records/models in the template, you will need +:ref:`a custom report `. -A generic report use the default rendering context, containing the magic -variables as explained before. If you want a new rendering context containing -anything you want to process your data Odoo AbstractModel, a custom module is -needed. These reports are called "particular report". +Translatable Templates +---------------------- -For a particular report, you have to write an Odoo Model containing a -render_html method. Classically, this method returns a call to the original -**QWeb render** with a **custom rendering context**. +If you wish to translate reports (to the language of a partner, for example), +you need to define two templates: + +* The main report template +* The translatable document + +You can then call translate_doc from your main template to obtain the +translated document. If you wish to see the details of the translation in the +backend, you can go to :menuselection:`Settings --> Reports --> Report --> + --> Search associated QWeb views --> --> +Associated translations`. + +For example, let's look at the Sale Order report from the Sale module:: + + + + + + + + +The main template calls translate_doc with ``partner_id.lang`` as a parameter, +which means it uses :ref:`a custom report model +` to access a ``res.partner`` record. + +Barcodes +-------- + +Barcodes are images returned by a controller and can easily be embedded in +reports thanks to the QWeb syntax: + +.. code-block:: html + + + +More parameters can be passed as a query string + +.. code-block:: html + + + + +Useful Remarks +-------------- +* Twitter Bootstrap and FontAwesome classes can be used in your report + template +* Local CSS can be put directly in the template + +* Global CSS can be inserted in the main report layout by inheriting its + template and inserting your CSS:: + + + +.. _reference/reports/paper_formats: + +Paper Format +============ + +Paper formats are records of ``report.paperformat`` and can contain the +following attributes: + +``name`` (mandatory) + only useful as a mnemonic/description of the report when looking for one + in a list of some sort +``description`` + a small description of your format +``format`` + either a predefined format (A0 to A9, B0 to B10, Legal, Letter, + Tabloid,...) or ``custom``; A4 by default. You cannot use a non-custom + format if you define the page dimensions. +``dpi`` + output DPI; 90 by default +``margin_top``, ``margin_bottom``, ``margin_left``, ``margin_right`` + margin sizes in mm +``page_height``, ``page_width`` + page dimensions in mm +``orientation`` + Landscape or Portrait +``header_line`` + boolean to display a header line +``header_spacing`` + header spacing in mm + +Example:: + + + French Bank Check + + custom + 80 + 175 + Portrait + 3 + 3 + 3 + 3 + + 3 + 80 + + +.. _reference/reports/custom_reports: + +Custom Reports +============== + +The report model has a default ``get_html`` function that looks for a model +named :samp:`report.{module.report_name}`. If it exists, it will use it to +call the QWeb engine; otherwise a generic function will be used. If you wish +to customize your reports by including more things in the template (like +records of others models, for example), you can define this model, overwrite +the function ``render_html`` and pass objects in the ``docargs`` dictionnary: .. code-block:: python from openerp import api, models - class ParticularReport(models.AbstractModel): - _name = 'report.<>' + _name = 'report.module.report_name' @api.multi def render_html(self, data=None): report_obj = self.env['report'] - report = report_obj._get_report_from_name('<>') + report = report_obj._get_report_from_name('module.report_name') docargs = { 'doc_ids': self._ids, 'doc_model': report.model, 'docs': self, } - return report_obj.render('<>', docargs) + return report_obj.render('module.report_name', docargs) -.. _time: https://docs.python.org/2/library/time.html +Reports are web pages +===================== + +Reports are dynamically generated by the report module and can be accessed +directly via URL: + +For example, you can access a Sale Order report in html mode by going to +\http:///report/html/sale.report_saleorder/38 + +Or you can access the pdf version at +\http:///report/pdf/sale.report_saleorder/38 + +.. _wkhtmltopdf: http://wkhtmltopdf.org