Reports
From PERPWiki
Reports use TinyButStrong's OpenOffice.org extension, slightly customized, to transform an ODF template document into your report. The user downloads the transformed document. You do not need to have OpenOffice.org installed on your server.
If the optional format converter is set up, users have the option to download the document in either PDF or Microsoft Office formats.
Contents |
Where are they?
Before users can generate reports, some setup is required. Check the FAQ for some common problems.
You must allow users access to the reports using Admin -> <pERP App> -> Configure Access Permissions before they will be able to see and generate the reports. Each pERP application that has reports will have a Reports section on it's index page. This will take you to a list of reports allowed.
Customizing
TinyButStrong Tags are used in the OOo template, and they are replaced by the actual data. You can check the TBS manual for details on tags and their parameters.
Each report has three parts: the PHP class, the eTemplate, and the OO.o template.
OpenOffice.org Template
If you just want to change the look of the report, this is the only file you need to change. These files can be found in
<perp_application>/inc/reports/<your_language>/
Look for a README in the reports directory, some files have special notes. Sometimes OpenOffice.org ruins the template when you open it, so the README will contain warnings and corrective actions.
If there is no README, or no warnings about the report you want to change, you can open the template using OO.o and reformat it as needed. At this point, you are limited to formatting changes, you can't add any new information.
Save your modified template into
<perp_application>/inc/reports/default/
to prevent subsequent updates from overwriting your changes. If the default directory doesn't exist, you can create it. pERP will use your customized template instead of the standard one.
It should be possible to use any ODF document, but only ODT and ODS (writer and spreadsheet) have been used.
eTemplate
The eTemplate is used to get parameters for the report from the user. It lets them specify which client(s), invoice(s), date range, etc. The eTemplate is optional, and must be named in the style <app_name>.report.<report_name>. If there is an eTemplate for a report, it will be displayed before the report is generated. It is not necessary to add a 'Submit' button, the framework handles this.
Data, such as selectbox options and defaults, can be set in the $this->parameters variable in your report's constructor. Your eTemplate can submit on change, or even have buttons. The data will be passed to the report constructor. When the user clicks the 'Generate Report' button, the report's get_data() method is called with the eTemplate results.
PHP class
This is where the information for the report is extracted. Every report should include /perp_api/inc/class.perp_report.inc.php, and extend perp_report.
There are two methods that your report should override:
__constructor(Array $incoming = array())
This is where you set up your report, including:
- Call the parent.
parent::perp_report($incoming) - Set your ODT template file. Just the file name, no path, as in 'statement.odt'.
- Default parameters, and other eTemplate information.
For selectboxes, you must use the options-field_name style of passing selectbox options.
get_data(Array $query)
This is where you generate and return one array that contains all the information for the report.
The easiest way to learn about this is to take a look at an existing report, and look for the return statement. Right before the return, add:
_debug_array($data); die();
This will let you look at the data being sent to the report, and compare it to the template so you can see how they fit together. From there, you can mess around with the OO.o template to add and remove fields to / from your report.
Also of note, you can change $this->filename to a name more specific to your report. For example, if you don't set $this->filename, your users will download 'Invoice.odt'. If you set $this->filename = lang('Invoice') . ' ' . $invoice->get_our_reference_number(); your users will get 'Invoice 1234.odt'
