Advanced functions in iReport

+ Advanced functions in iReport +

+ Text + + There are two types of text in iReport: «Text labels» and «Text fields» (data fields). They work in different ways, and should be used for different purposes. The main point is that text fields are just placeholders that will be filled with the correct text from the report table when the report is run, while text labels will stay the way they are when the report is run. +

+ Static text + Static text are text plain text labels that can be edited normally. There are two ways to edit text labels: + + + By double clicking in the text box + + + By using the Static text properties in the Properties panel + + + + Click to edit text label + + + + + + +

+ Text fields + Text fields are formulas that will be filled from the report table when the report is run. Unlike static text, these can not be edited in a normal way. However, they can be manipulated in various ways to ensure that the desired output will be produced. There are three ways to edit the text fields: + + + + By right clicking on the text box and selecting Edit expression + + + By double clicking the text field (not recommended, as this will not bring up the expression editor) + + + By using the Text field properties in the Properties panel + + + + Click to open Expression editor + + + + + + + + Click to open Expression editor + + + + + + + Text fields can represent either numbers or text, so that they can be used both for showing for example names of district or for numeric values. It is therefore important the the Expression class, seen in the Text field properties matches the Text field expression. For the default text fields in the .jrxml file downloaded from DHIS 2 this is not a problem, but it is important when making new text fields. The two most important Expression classes are java.lang.Double for numbers and java.lang.String for text. + +

+ Example + For example, let us say you have a quarterly report where you would like to add a new column with the yearly total. You therefore add a new Static text field to the column header band, and a Text field to the details band in. By default, new Text fields are set to java.lang.String (text). However, the yearly total column will be filled with numbers. We therefore have to change the Expression class for the new text field to java.lang.Double: + + Click to show expression class options + + + + + + + + Choose desired class + + + + + + + When we edit the text field expression, we see the Expression editor window with all the available columns from the report table. We can see here that each of these are marked with what type they are - text or number. What we need to make sure of is therefore that the expression class we choose for the text field matches the actual expression. + + Expression editor + + + + + + +

+ Filtering the table rows + In the default table exported from DHIS 2, there are some rows that it might be better to leave out of the table, and some that it would be preferable to have at the end. For example, when making a table based on a report table with the «parent organisation unit» parameter, the default table might have a row with the national level somewhere in between all the regions. In iReport, this can be changed so that the «parent organisation unit» appears at the bottom of the table. This involves two steps that will be explained below. Note that this will not work where there is only one organisation units, and it is therefore most useful when using the «parent organisation unit» or «grand parent organisation unit» parameters in the report table. +

+ Hiding the «parameter organisation unit» from the table + First, we must make sure that the row with the parent organisation unit (for example the national level) is left out of the regular table. We do this by using a property specific to the Details band called Print when expression. To set a Print when expression, start by selecting the Detail band in the Report inspector, then edit the Print when expression in the properties panel. + + Select Detail 1 in the Report Inspector + + + + + + + + Open the Expression Editor by clicking next to Print When Expression + + + + + + + The Expression editor window should now appear. What we must do is to create an expression that checks if the row being generated is the row with the organisation unit given as a parameter. The report table contains a column that we can use for this called organisation_unit_is_parent. To exclude the row with the parameter organisation unit, double click on organisation_unit_is_parent in the list to copy it to the expression area, then add .equals("No") at the end so that the code is: + $F{organisation_unit_is_parent}.equals("No") + This tells the report engine to only print table rows where the organisation unit is not the parent organisation unit. + + Code to skip parent organisation unit + + + + + + +

+ Hiding other rows + Using the expression editor it is also possible to exclude other rows from the table, in addition to the parent organisation unit as was explained above. In Ghana, for example, all regions have a «fake district» which is the name of the region in square brackets. This can also be excluded from the table using the Print when expression that was introduced above. To to this, follow the instructions above to bring up the Expression editor window. Then, we use Java expressions to test whether or not the row should be hidden. +

+ Example - removing rows with organisation units starting with [ + Example - removing rows with organisation units starting with [ + ($F{organisationunitname}.charAt( 0 ) != '[') + This makes the report skip any rows where the first character of the organisation unit name is [. + It is also possible to combine several of these expressions. To do this we put the expressions in a parenthesis with the two characters && in between. For example, to make a table that leaves both organisation units whose name starts with [ and the parent organisation unit, we can use the following expression: + ($F{organisationunitname}.charAt( 0 ) != '[')&&$F{organisation_unit_is_parent}.equals("No") + + Combining expressions in the Expression editor + + + + + + +

+ Showing the parameter organisation unit at the end of the table + We have now made sure that the parameter organisation unit is not included in the table as a regular row. However, we often want to include it somewhere in the report. A good way to do this is to add it in the summary band so that it will appear below the table. The easiest way to do this is to copy all the text fields from the Detail band into the summary band, and then just edit the expression for the first column. + + + Select all the fields in the detail band and choose + + + Copy from the Edit menu + + + Click once on the Summary area + + + Choose Paste from the Edit menu + + + Position the new fields correctly + + + + Select fields in the details band and copy them + + + + + + + + Past fields into Summary band + + + + + + + + Realign fields + + + + + + + The final step is to edit the expression of the first column to make sure that the correct organisation unit is displayed here. Open the Expression editor window and change the expression to $F{param_organisationunit_name}. + + Choose the parameter organisation unit + + + + + + + The report should now have all the «regular» organisation units as normal rows with their «parent» or «grand parent» at the bottom of the table. +

+ Sorting + Often you will be making reports where the first column is organisation unit names. However, it can be a problem that the list of organisation units are not sorted alphabetically. This can be fixed in iReport through a few simple steps. + In the report inspector, right click on the name of the report (by default this is dpt) and select Edit query. + + Choose Edit Query + + + + + + + A Report query window will appear. Click on the Sort options button. + + Choose Sort Options... + + + + + + + A Sorting window as show below will appear. Here, we can add our sorting options. Click the Add field button. Another small window will show up, with a drop down menu where you can choose Sort by organisationunitname to have the table sorted alphabetically by name. + + Choose Add + + + + + + + + Choose sort parameter + + + + + + + Click OK - Close - OK to close the three windows. The table should now be sorted. +

+ Changing indicator/data element names + By default, the reports from DHIS 2 uses the short names for indicators and data elements in reports and charts. In some cases these are not always very meaningful for third parties, but with some work they can be given custom names through iReport. This is useful for example if you are making a report with indicators as rows and periods as column, or for charts with indicators. + + Shortnames - before and after + + + + + + + To change the names of an indicator or data element, we have to edit its «expression» or formula, for example by right clicking the text box and choosing Edit expression to bring up the Expression editor. + + Choose Edit Expression + + + + + + + Next, we have to insert some Java code. In the following example, we will be replacing the shortname of three indicators with their proper names. The code searches for the shortname, and then replaces it with a proper name. + + Expression editor, showing replacing shortnames + + + + + + + ($F{indicatorname}.equals("Bed Util All")) ? "Bed Utilisation - All Wards":($F{indicatorname}.equals("Bed Util Mat")) ? "Bed Utilisation - Maternity":($F{indicatorname}.equals("Bed Util Ped")) ? "Bed Utilisation - Paediatric":$F{indicatorname} + From this, we can see a pattern that is reusable for more general cases. + + + For each indicator or data element we want to change the name for, we need one line + + + Each line is separated by a colon : + + + We finish the expression with a «regular» line + + + Each line has the same format, where the red text is the shortname, the blue text is what we want to insert instead. + + Code for replacing shortnames. Shortname in red, new name in blue + + + + + + + The same expressions can be used for example when having indicator names along the category axis of a chart. +

+ Groups of tables + There are cases when it can be useful to have several tables in one report. This can be done using Report groups. Using this functionality, one can for example create a report one table for each indicator, or one table of each organisation unit. In the following, we will go through the steps needed to make a report with three indicators, each represented in one table. It is important that the report table does not crosstab on indicators when we want to make groups of tables based on indicators. + In our example, the .jrxml file downloaded from DHIS 2 will by default have one column for organisation unit and on for indicators (assuming we have chosen periods as the only crosstab dimension). We start by removing the indicator column, since this in not needed in our case, and realign the other fields to fit the report. + + Delete column + + + + + + + Next, we create out Report group. Go to the report insepctor, right click on the report name (dpt is the default) and choose Add Report Group. + + Add Report Group + + + + + + + A window will appear, with a report group wizard. Select a name for the group, in this case we choose «Indicator». In the drop down menu, we can select what columns in the report table we want the groups to be based on. So, if we wanted one table for each organisation unit, we would choose organisation unit name as the report object to group according to. However, since we are grouping by indicators in this example, we choose indicatorname. Then click next. + + Choose grouping parameter - here, indicators + + + + + + + The next step is to select whether or not we want a separate Group header and Group footer band for each report group. In this case, we choose to include both. Click Finish, and the group bands should appear in the report. + + Add group header/footer + + + + + + + If you upload and run the report, it will now create one table for each indicator. However, it will not look very good as there will be no header row over each table - only one header at the top of each page. Also, there is no indication as to which table is showing which indicator. In the following, we will fix this. + Instead of having the title row in the column header, we can instead move it to the Group header. This will make the heading show up above each individual table. Furthermore, we can add a heading to each table with the name of the indicator. + Move the column headers from the Column header band to the Indicator group header band. + + Move header row to column header + + + + + + + Next, add a text field to the Indicator group heading band, and edit it’s expression to display the indicator name. + + Add text field to use as heading + + + + + + + + Edit text field expression to show indicator name + + + + + + + The report should now have three tables, one for each indicator. Each table will have a heading with the name of the indicator, and also a table header row. + + Example of finished report table + + + + + + +

+ Sorting and grouping + When using grouping, some precautions must be taken with regards to sorting. Notably, when adding sorting parameters, whatever parameter is used as basis for the grouping must come first. Thus if you are grouping the report by indicator, and want sort the organisation units alphabetically, you have to choose to sort first by indicator, then by organisation unit name as shown below. For instructions on how to add sorting, see the sorting section above. + + Sorting by indicator and organisation unit name + + + + + + +

+ Charts + By default, a 3D bar chart is included in the .jrxml file that is downloaded from DHIS 2. This is set up so that only data from the «parameter orgnisation unit» (often the parent or grand parent) is used. Usually, this is a good solution. Since it is the default, we will start by looking at bar charts, before looking at line charts. +

+ Bar charts + Bar charts are the default. To edit the chart, right click and choose Chart data. + + Choose Edit Chart Data + + + + + + + A window will appear. By default, the Filter expression is filled in so that only data for the parent organisation unit will be displayed. If for some reason you do not want this, simply delete the text in the text box. To continue, click the details tab. + + Select the Details tab + + + + + + + Under details, you see the list of series for the chart. By default, one series is created per crosstab column. In this case, we are looking at data with four quarters along the crosstab dimension. + + List of data series + + + + + + + To make changes to any of the series, select it and click modify. Another window will appear where there are four areas that can be edit. The three first are required, but it is sufficient to add an empty quote («») in one of the first two. + + The data series editor + + + + + + + The first box is a text field where the name of the series can be inserted or edited. This is the field that will be used to fill the text in the legend box (shown below). + + Chart legend + + + + + + + However, if you want to have the name of each bar along the x-axis of the chart instead of using the legend, this can be done by adding whatever text you want to present in the Category expression field. + If you add a good description in the Category expression area, you can leave out the legend box. This is done in the Report properties panel of iReport, where you can also edit many other details of the chart. + + Checkbox to show/hide chart legend + + + + + + + We can also add a title to the chart, for example the name of the indicator. This is also done in the Chart properties panel, under Title expression. + + Edit chart title + + + + + + + The Expression editor window will appear, where you can enter the title. Note that the title must be in quotes, as shown below. + + Expression editor + + + + + + + Below, you can see what effect the above changes have had to make the chart more clean and readable. + + Chart - before + + + + + + + + Chart - after + + + + + + +

+ Line charts + Line charts can be useful in many circumstances. However, to make line charts the report data (report table) must be suited for it. Thus if you want to make a line chart, it is important that the report table does not have periods in the crosstab dimension. Examples where this is useful is if you are making a report for a single organisation unit with one or more indicators, or if you are making a report with one indicator and one or more organisation units. + Below, we will go though the steps needed to make a report with a line chart showing the development of three indicators over one year, for one organisation unit. We start by making a report table with the choices shown below: + + Report table - crosstab dimensions + + + + + + + + Report table - periods and parameters + + + + + + + When we open the resulting .jrxml-file in iReport, the default line chart is included. Since we want to make a line chart, we delete this chart and drag a new chart element into the report from the Palette panel. + + Delete the default chart + + + + + + + + Drag in new chart element + + + + + + + As soon as we drag the Chart element into the report, a window will appear. We choose the Line chart, as shown below. + + Choose Line chart + + + + + + + A chart wizard will appear. Click next in the first step, then Finish in the next - we will add the data later. + + Choose Next + + + + + + + + Choose Finish + + + + + + + Next, adjust the size and position of the chart in your report. Then, we will add one data series for each of our three indicators. Right-click on the chart and choose Chart data. If you are making a chart with one indicator and several organisation units, you probably want to make a filter expression so that only data from the paramter/parent organisation unit is used in the chart. To do this, add this line to the Filter expression area: + $F{organisation_unit_is_parent}.equals("Yes") + In our example, we only have on organisation unit, so this is not necessary. Next, click the details tab to see a list of the series in the chart. For now, this list is empty, but we will add one series for each of our three indicators. To add a series, click the Add button. + + Choose the Details tab + + + + + + + + Choose Add + + + + + + + In the window that appears, enter the name of the first of the indicators in the Series expression window. Remember to put the name in quotes. In the category expression (along the x-axis) we want the months, so we use the button next to the field to open the Expression editor and add periodname. + + Edit the category expression + + + + + + + + Choose periodname as the expression + + + + + + + In the value expression, we add the actual data values for our first indicator. Use the Expression editor again to do this. When we are finished, the window should look like the one below, only with different names according to the indicator. + + The finished category series + + + + + + + You can then Click OK to close the window. Follow the same steps to add a series for the other indicators. + + Chart details after adding three series + + + + + + + Close the window, and the data for the line chart should be ready. However, some additional adjustments might be needed - most of these can be found in the Line chart properties panel. For example, when making a month by month chart as we have in example, there is often not enough space for the month names along the category axis. This can be fixed by rotating the labels by for example -40 degrees, by using the property Category Axis Tick Label Rotation. + + Changing the appearance of the category labels + + + + + + + Many other options are available to give the chart the desired look. + + The finished line chart + + + + + + +