tryton/doc/reports.rst

Reports
#######

Tryton can generate dynamic reports in many formats from report and style
templates. The reports are generated in one step as follows: a report template
in a special file format, explained later, is interpolated with dynamic data
and placed into document of the same file format. Tryton's ability to generate
documents in this way allows documents to be generated for any editor that
supports the Open Document Format which can be converted to third party
formats, such as PDF.  Extra libraries are required for this, see INSTALL
for more information.

Report Templates
****************

Report templates are files with a format supported by relatorio, that contain
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. These are specific to ODT files.

.. highlight:: genshi

::

  <for each="party in objects">
    <party.full_name>
    <if test="party.addresses">
      <for each="line in party.addresses[0].full_address.split('\n')">
        <line>
      </for>
    </if>
  </for>

  
Report styles
*************

Reports styles let you standardize the header, footer and styles of your
templates.


Report API
**********

.. _report:

Python API
==========

.. _trytond.report.Report
.. autoclass:: trytond.report.Report
    :members:
    :undoc-members:

.. _trytond.ir.action.ActionReport
.. autoclass:: trytond.ir.action.ActionReport
    :members:
    :undoc-members:


XML Description
===============

When defining an `ir.action.report` the following attributes are available:

    * ``name``: The name of the report.

    * ``report_name``: The name of the report model, for example
      my_module.my_report.  This is the name you would use with `pool.get`

    * ``module_name``: If this report is of an existing model this is its name.
      For example my_module.my_model. Custom reports that aren't of a specific
      model will need to leave this blank.

    * ``report``: The path to the template file starting with the module, for 
      example my_module/my_report.odt.

    * ``style``: The path to the style file starting with the module, for 
      example, my_module/my_style.odt. If no style is to be used this field
      will be blank.


Report Usage
************

Using genshi and open office reports
====================================

Setting up an ODT file
----------------------

If you are creating a report from scratch you should perform the following
steps:

 - Remove user data
    * "File > Properties..."
    * Uncheck "Apply user data"
    * Click on "Reset" 

 - 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')
    
 - Set some parameters
    * Set the zoom to 100% (View>Zoom)
    * Set the document in read-only mode
 (Tools>Options>OpenOffice.org>Security) (Decreases the time it takes to
 open the document.)

 - Usage
    * Use Liberation fonts (Only necessary if being officially included in Tryton)
    * Try to use styles in report templates so that they can be extended in
      report styles.

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.
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 Templates`_

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`_


Accessing models from within the report
=======================================

By default instances of model that the report is for are passed in to the
report via a list of objects called `objects`.  These objects behave just
as they would within trytond itself. You can access any of the models 
relations as well.  For example within the invoice report each object 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`.

Within tryton the model the report is for 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 > Model > Model.  Model relation fields can be accessed to any
depth, for example, one could access `invoice.party.addresses` to get a list of
addresses for the party of an invoice.

Creating a simple report template for a model from client
=========================================================

TODO: Explain the steps necessary to do this.

Creating a simple report template for a model in XML
====================================================

Less work has to be done if you just want a simple report representation of a
model.  There are just 2 steps.  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 module_name.

Replacing existing Tryton reports
=================================

To replace an existing report you must deactivate the old report and activate
the new report.

For example to deactivate the invoice report:

.. highlight:: xml

::

  <record model="ir.action.report" id="account_invoice.report_invoice">
    <field name="active" eval="False"/>
  </record>

Then you must activate the new invoice report that exists in your new module:

.. highlight:: xml

::

  <record model="ir.action.report" id="report_invoice_new">
    <field name="name">Invoice</field>
    <field name="report_name">account.invoice</field>
    <field name="model">account.invoice</field>
    <field name="report">my_module/invoice.odt</field>
    <field name="style">module_name/header_A4.odt</field>
  </record> 

Passing custom data to a report
===============================

TODO: Examples of overriding Report.execute.

In this example `Report.parse` is overridden and an employee object is 
set into context.  Now the invoice report will be able to access the employee 
object.

.. highlight:: python

::

  class InvoiceReport(Report):
      _name = 'account.invoice'
      def parse(self, cursor, user_id, report, objects, datas, context):
          employee_obj = self.pool.get('company.employee')
          employee = False
          if context.get('employee', False):
              employee = employee_obj.browse(cursor, user_id,
                                             context['employee'],
                                             context=context)
          context['employee'] = employee
          return super(InvoiceReport, self).parse(cursor, user_id, report,
                                                  objects, datas, context)
  InvoiceReport()


Replacing existing Tryton styles
================================

TODO: Explaination of how to override `ir.report.get_style_content` to change
the default style.


.. External Links

.. _Genshi XML Templates: http://genshi.edgewall.org/wiki/Documentation/0.5.x/xml-templates.html

.. _Quick Example: http://relatorio.openhex.org/wiki/QuickExample

.. _In Depth Introduction: http://relatorio.openhex.org/wiki/IndepthIntroduction

.. _Example Documents: http://relatorio.openhex.org/browser/examples