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 run the "Find and register all pERP reports" to register all the reports before you can do anything else.
- 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. Users without permission to a report cannot generate it.
Each pERP application that has reports will have a Reports section on its index page. This will take you to a list of reports allowed.
Ad Hoc
If the user has their preferred report format set to OpenOffice.org, they can generate any reports that you have set as ad hoc at any time they wish. The report will be immediately generated, and sent to the user. As the admin, you can disable reports that take too long. This is in addition to the restrictions on OpenOffice.org, and ACLs.
Due to limitations in the report format conversion system, other formats must be scheduled. If the user's preferred report format is NOT OpenOffice.org, they cannot get reports on demand.
Scheduled
Reports can be set to run at a time other than now. For users that do not use OpenOffice.org, this is the only option. Be careful if you disable scheduling for a report, as some users may not have adhoc as an alternative.
You can choose to generate the report:
- As soon as possible
- Once at a certain time
- At a regular [recurring] time
The exact timing depends on your Asynchronous timed services. If they run every hour, you could be waiting a bit for your ASAP report. If your asynchronous services use "Fallback", reports will not be generated when someone is not using the system.
Once the report is generated, it will be distributed according to the settings chosen. Usually this means it will be emailed to the user.
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 for adhoc reports 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.
For scheduling, the eTemplate name is in the style <app_name>.schedule.<report_name>. If this template exists for the report, it will be displayed instead of the above template when you are scheduling the report. If it is missing, the above template will be used for scheduling, if it exists, as well as adhoc. Data for the template, such as selectbox options and defaults, can be returned from the function get_schedule_settings(). When the time comes to generate the report, these settings will be passed to the report's get_data() method.
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'
