Designing Reports
Once you have successfully defined the data that you wish your report to produce, the next step is to determine how you want this data to be output to your users. The reporting module provides a flexible framework for defining and designing your report outputs, using what we call Report Renderers. There are several Report Renderers that ship with the Reporting Module. They vary in complexity and in the amount of configuration that they accept and require. Additional Report Renderers can be easily registered by any other module with a single new class definition. The renderers that come shipped with the reporting module are described in detail below.
Report Design Manager
You can access or add any of these types of renderers by first clicking in the Report Administration section and then in the Report Designs link.
1 | Report Administration | |
2 | Report Design Manager. In this section you can add a renderer and link it to a Report Definition (keep reading for a detail explanation). This way the renderer will become an output option for that report. On this page you will find a list of all Report Designs that a user creates and that can be edited. | |
3 | Another way to add a renderer is from the Output Designs box on the Report Editor page when creating a Report Definition. |
Report Renderers
The Report Renderers could be easily divided in two types: configurable and non-configurable renderers. Please keep reading to learn more about the currently available type of renderers and their configuration (if any).
Default Web Renderer
The only Report Renderer that is available by default for all report definitions is the Default Web Renderer which will output the data of your report to be readable directly from OpenMRS. This basically means that the data cannot be exported or taken out of the system. The main characteristics of this renderer are:
- No configuration needed.
- Handles multiple data set definitions.
- Produce a nicely formatted web-optimized display for the data, with each data set contained within its own tab.
Since this renderer is a default one for all the reports that a user might create, it won’t appear among the options listed in the Report Design Manager, but it should always be as an output option when running a report.
1 | Listed options under Report Design Manager page. | |
2 | This type of renderer should always be a default output option for any user-defined report. | |
3 | Expected output |
Delimited Text Report Renderer
The Report Designs section has two types of Delimited Text Report Renderer: CSV Report Renderer and TSV Report Renderer and they share the following characteristics:
- Both handle multiple data set definitions. If only one Data Set Definition is being used then the final output will be a cvs, tsv or a user-defined file extension file. In case that the Report Definition has more than one data set, then the output will be a zip containing all of the delimited text files (csv, tsv or user-defined) for each data set (see examples below).
- The user can easily change what delimiters should be used when rendering the data. Please keep reading to learn more about this.
CSV Report Renderer
This comma-separated value renderer will allow you to export the data of your report to a flat file suitable for importing into Excel, SAS or another external analysis tool. The main characteristics of this renderer are:
- It allows you to change the filename extension of the final file.
- Even when the output is pre-configured to be a comma-separated value file, the user can change both the field delimiter and text delimiter (see examples below).
1 | Select the CSV option from the drop-down list and click on the Add another button. | |
2 | On the configuration page, only the description field is optional. The filename extension, field delimiter and text delimiter fields have default values. | |
3 | If you run your report, the new added design will appear as an output option of the Report Definition you previously linked it to and it will be added to the list displayed on the Report Designs Manager page as well. | |
4 | Running the same report used earlier in the Default Web Renderer example, the expected output should be a file with csv extension containing columns separated by a comma and with a text delimiter which is the closing quotation mark (the text delimiter is the character that follows a field, in this example the field is composed of the opening quotation mark and the word: type). | |
5 | Now let's say you would like your fields to be separated by a dash, then you would have to modify the field delimiter like this: | |
6 | Then the expected output file is a character-separated value (the character is a dash). | |
7 | In case that your report has more than one Data Set Definition, then the output will be a zip of delimited text files (csv files for this example). |
TSV Report Renderer
There’s not much difference between the CSV and TSV (tab-separated value) renderers, both share the same characteristics. The main discrepancy is that the user cannot change the field delimiter value which always will be a Tab. The filename extension and the text delimiter are the only fields that can be modified.
1 | The Field Delimiter value will always be a Tab. | |
2 | If you run your report, the new added design will appear as an output option of the Report Definition you previously linked it to and it will be added to the list displayed on the Report Designs Manager page as well. | |
3 | The expected output is a file with tsv extension and the columns are separated by a tab with a text delimiter which is the closing quotation mark (the text delimiter is the character that follows a field, in this example the field is composed of the opening quotation mark and the word: type). | |
4 | In case that your report has more than one Data Set Definition, then the output will be a zip of delimited text files (tsv files for this example). |
HTML Report Renderer
It is a very basic renderer that produces an HTML file that contains the data of your report. Its main characteristics are:
- No configuration is needed.
- Handles multiple data set definitions and each one is rendered to a table in the HTML output file.
1 | Select the HTML (Dafault) option from the drop-down list and click on the Add another button. | |
2 | Only the description field is optional. The report definition used for this example has more than one data set definition. | |
3 | If you run your report, the new added design will appear as an output option of the Report Definition you previously linked it to and it will be added to the list displayed on the Report Designs Manager page as well. | |
4 | The expected output is an HTML file. | |
5 | If you inspect the page source code should be something like this: |
XML Report Renderer
A very basic renderer which produces an XML file that contains the data of your report. Its main characteristics are:
- No configuration is needed.
- Handles multiple data set definitions.
- The output format of the XML document is the following:
<?xml version="1.0"?> <dataset name="theNameOfTheDataSetInTheReport"> <rows> <row> <eachColumnLabel>eachColumnValueAsString</eachColumnLabel> ... <row> ... <rows> </dataset> ...
1 | Select the XML option from the drop-down list and click on the Add another button. | |
2 | Only the description field is optional. The report definition used for this example has more than one data set definition. | |
3 | If you run your report, the new added design will appear as an output option of the Report Definition you previously linked it to and it will be added to the list displayed on the Report Designs Manager page as well. | |
4 | The expected output is an XML file with the format mentioned earlier. |
XLS Report Renderer
The output of this type of renderer will be an xls file and its main characteristics are:
- No configuration needed.
- Handles multiple data set definitions and each one will be put in a new tab (worksheet) inside the .xls document.
- From its configuration page you can choose to change the output to a custom Excel document.
1 | Select the Excel (Default) option from the drop-down list and click on the Add another button. | |
2 | Only the description field is optional. The report definition used for this example has more than one data set definition. From this page you can change the output of this design to be a custom Excel document. | |
3 | If you run your report, the new added design will appear as an output option of the Report Definition you previously linked it to and it will be added to the list displayed on the Report Designs Manager page as well. | |
4 | The expected output should be a .xls document with a tab (worksheet) for each data set definition. |
Excel Report Renderer
The Excel Report Renderer allows you to upload an Excel document with .xls extension that might contain all of the layout, formatting, formulas, graphs, and other styling that you might want in your final report. Then this document is used as a template to render the output data. This Report Design handles multiple data set definitions and can be configured in different ways, keep reading to learn more about the configuration options.
To access this Report Design follows these steps:
1 | Select the Excel-based Template option from the drop-down list and click on the Add another button. | |
2 | The description field is optional. From this page you can change the output of this design to be a XLS Report Renderer. | |
3 | Keep reading to learn more about the configuration options. |
Excel Report Renderer Configuration and Access Options
Section | Configuration and Access Information | Examples | |||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Expressions |
Both will help to identify in the template pieces of text that are expected to be replaced with data. | If you stick with the default values, then everything that is between the # character will be replaced: #myDataset.myValue# You can change to the Suffix and Prefix to be an character, for example the $ character, then you should be able to access your data in your template this way: $myDataset.myValue$ | |||||||||||||||||||||||||||||||||||
Repeating Sections | The output data of your report might have rows and columns of information instead of just having one single value. If this is your case, then you should configure Repeating Sections to access all of your rows and/or columns. As a side note, if the data of your report has a lot of rows and columns, might be possible that the XLS Report Renderer is more suitable for you. The following options literally mean if a sheet | row | column should be repeated in a template.
| For the following examples let's assume that our report output the following table using the encountersByType key as name for the Data Set Definition:
| |||||||||||||||||||||||||||||||||||
Designing Properties | You can define any key-value property that your template might need.
|
| |||||||||||||||||||||||||||||||||||
Miscellaneous |
|
Here is another example for the Excel-based Template Report Design Renderer
For technical guidance consult the Java ExcelTemplateRendererTest class.
Text Template Renderer
This Report Design Renderer evaluates a template and produces an HTML or XML or any other text-based report output. Its main characteristics are:
- Handles multiple data set definitions.
- Handles templates with scripting in Groovy and Velocity.
1 | Select HTML/text-based template option from the drop-down list and click on the Add another button. | |
2 | Only the description field is optional. Let's assume a Data Set Definition that can be accessed with the name "encountersByTypeByGender" and the following template. <?xml version="1.0"?> <dataset> <rows> <% dataset = reportData.dataSets.get("encountersByTypeByGender"); for (row in dataset) { %> <row> <% for (column in dataset.metaData.columns) { colValue = row.getColumnValue(column); colValue = (colValue instanceof java.util.Date) ? util.format(colValue, 'dd/MMM/yyyy') : util.format(colValue); %> <$column.label>$colValue</$column.label> <% } %> </row> <% } %> </rows> </dataset> | |
3 | If you run your report, the new added design will appear as an output option of the Report Definition you previously linked it to and it will be added to the list displayed on the Report Designs Manager page as well. | |
4 | The expected output is a text file, an XML in this example. |
To learn more about how to add different types of data to your template using Groovy please check here.
For technical guidance consult the Java TextTemplateRendererTest class.