start reports

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 OpenOfficeOrg which

[ced1, 2009/09/09 12:34:45]

It is not linked to OpenOffice, you can use any editor that know odt (Abiword,
Word + plugins)

+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 office text

[ced1, 2009/09/09 12:34:45]

open office text -> 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 OpenOfficeOrg.

[ced1, 2009/09/09 12:34:45]

not specific to OOo but to odt

+
+.. 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.
+

[Ian Wilson, 2009/07/21 08:47:22]

I kind of understand this but I don't know a lot about openoffice styles. 
They(styles) seem like they won't apply well to other formats though besides
.odt.

[udono, 2009/07/21 10:04:45]

Oh yes, this could be. Maybe each document type need a style template of the
same type - if styles exist. And we need to check if the style node which is
replaced by tryton parse is equal for all document types.

+
+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
+************
+

[Ian Wilson, 2009/07/21 08:47:22]

This section is starting to get really confusing.  Mainly its hard to break
apart: 
- how to handle reports in a non-format-specific way
and(create template file in module, create xml)
- how to handle reports in a very format specific way(genshi, odt, relatorio,
etc)

I'm going to keep thinking about an easy way to say it and I'm learning more as
I try my own reports.  Any suggestions ?

[udono, 2009/07/21 10:04:45]

Don't understand correctly. Reporting system in Tryton is relatorio + genshi +
X) Non format specific in genshi/relatorio context is for me a simple text
document. Styles will not work on this, since the style node is missing.
Here I have some knowledge with odt and ods (OOCalc).

+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)

[ced1, 2009/09/09 12:34:45]

You can add that this is to speed opening

+
+ - Usage
+    * Use Liberation fonts

[ced1, 2009/09/09 12:34:45]

This is only for inclusion into 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 OpenOfficeOrg

[ced1, 2009/09/09 12:34:45]

Not specific to Ooo

+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.

[ced1, 2009/09/09 12:34:45]

I don't know if it is good to give the path because Ooo changes often the place
of such tools.

+An alternative for embedding genshi that is supported by relatorio is use·
+special hyperlinks, this is described in the examples on relatorio's site.

[ced1, 2009/09/09 12:34:45]

As we don't want to use it, I don't think it is good to talk about it here.

+
+Also note that relatorio only supports a subset of genshi. The directives
+that are supported are:

[ced1, 2009/09/09 12:34:45]

How will we keep this uptodate.
It is better to have only link to relatorio doc.

+
+ - for
+ - if
+ - choose
+ - when
+ - otherwise
+ - with
+
+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
+=============================================
+
+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

[ced1, 2009/09/09 12:34:45]

Instead of XML, you can create a record in "Administration>User
Interface>Actions>Reports"

[Ian Wilson, 2009/09/14 05:44:29]

How complete is this?  Can a printable report for a model be created so that it
is an accessible action when an instance of that model is selected?  All from
the tryton client interface?

[ced1, 2009/09/14 06:02:31]

Yes

+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