From 434d2a9b8f23e1661643ffa54ff1133d7af3679e Mon Sep 17 00:00:00 2001 From: Ian Wilson Date: Tue, 15 Sep 2009 23:51:14 -0700 Subject: [PATCH] Added basic reports documentation. --- doc/reports.rst | 253 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 252 insertions(+), 1 deletion(-) diff --git a/doc/reports.rst b/doc/reports.rst index ef98156d46..790fae4c41 100644 --- a/doc/reports.rst +++ b/doc/reports.rst @@ -1,2 +1,253 @@ Reports -####### \ No newline at end of file +####### + +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 + +:: + + + + + + + + + + + +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 + +:: + + + + + +Then you must activate the new invoice report that exists in your new module: + +.. highlight:: xml + +:: + + + Invoice + account.invoice + account.invoice + my_module/invoice.odt + module_name/header_A4.odt + + +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