Added basic reports documentation.
This commit is contained in:
Ian Wilson committed
1 parent
de860e50ce
commit
434d2a9b8f
1 file changed
+252
-1
+252
-1
@@ -1,2 +1,253 @@
|
||||
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
|
||||
Reference in new issue
Block a user