| 1. Dynamic Element Formatting | top |
| |
| | Some reports may require that the same kind of data be displayed differently, depending on its significance. |
| |
| | For example, someone would want to highlight on an orders list, all the orders that have a total value greater than 100$, like in the following table: |
| |
| |
| OrderID | City | Date | Value |
| 10251 | Buenos Aires | 07/15/2001 | 98.64 |
| 10263 | Paris | 09/19/2001 | 106.75 |
| 11320 | Caracas | 10/19/2001 | 88.10 |
|
| |
| | How to do that, since the format of a text field can not change dynamically? |
| |
| | The solution is within reach. |
| |
| | We can put in the same place two text fields, one on top of the other, both displaying the same value, but having different formats: one black and the other bold and red. |
| | In addition, we should make use of the |
| |
| | The red text field should be displayed only when its value is greater than 100 and the black one in the rest of the cases. |
| |
| 2. "Page i of n" Trick | top |
| |
| | Quite often we might need to put at the beginning of our reports, values that are calculated only after the entire document is generated. |
| | The most common situation of this kind would be the display of the total number of pages on the page footer or header of each page. |
| |
| | How to do that, since the report is filled page by page and the total number of pages is known only when we reach the end of our document? |
| |
| | Well, that's easy! |
| | ^JasperReports allows us to specify the exact moment at which an expression for a text field is evaluated. To display the total number of pages, we only need to put on our page footer (or any other report section) a text field that will use the PAGE_NUMBER report variable in its expression. For this field we will specify that the evaluation time should be "Report", because only when the end of the report is reached, this system variable will contain the total number of pages on our report. |
| |
| | The text field declaration in the XML report design file for the total number of pages in a document will look like this: |
| |
| |
$V{PAGE_NUMBER}
|
| | If we remove the attribute evaluationTime from the |
| |
| | To display the current page number and the total number of pages simultaneously, like in "Page 3 of 5" phrases, we need two text fields with the same expression (PAGE_NUMBER variable value), but with differentevaluationTime attributes: |
| |
| | evaluationTime="Now" for the current page number (default) |
| | evaluationTime="Report" for the total number of pages |
| |
| | There are 5 possible values for the attribute evaluationTime: Now, Report, Page, Column and Group. For more information about this attribute, see the |
| |
| | An example is also supplied in the sample application. |
| |
| 3. Bands larger than one page | top |
| |
| | Sometimes the content of a particular report band is larger than one page and we have to find a way to force page breaks at certain points, inside the band structure. |
| |
| | Of course, this issue does not concern all the report bands. I imagine that we shall never have page or column headers or footers larger than one page ... but who knows? |
| |
| | If the title band or the summary band are larger than one page, you should consider placing their content into a subreport element and applying the following trick to this particular subreport. This might even work for the page or column headers, but never for the page or column footers, since the engine judge them to be of fixed height and do not perform stretch for the elements placed on those sections. |
| |
| | We have eliminated from our discussion some of the report sections and all that remains are the group headers and footers and the detail band. |
| |
| | The group headers and footers we'll be treated together, so let's start with the detail band. |
| |
| | If we have a detail band that contains so many elements on it that we have to split it on multiple pages, we have to find a way to introduce page breaks. But there is no such "page break" element available in ^JasperReports, so what to do? |
| |
| | The only way to deliberately introduce page breaks in ^JasperReports is by using the isStartNewPage attribute of the |
| |
| | Normally, the reporting engine starts a new page or column every time it sees that the band it has to fill does not fit on the remaining space on the current page. This is why we have that validation performed when the report design is compiled, so that the bands do not have a height greater than the page height. Without such a constraint, the reporting engine would get confused and behave uncontrollably. |
| |
| | So, in order to solve our problem, we have to find a way to somehow pass this band height validation check. |
| |
| | Well, we could do that by splitting the detail band content on multiple bands, each one of them smaller that one page, so that the report design remains valid. |
| | And what other report bands could we use? Group headers and footers of course. |
| |
| | We could place some of our detail elements on a special group header, some of them will probably remain on the detail section, and the rest could go on the group footer. The only condition to this is that the group header and footer should always accompany our detail section, so that all three behave like a normal large detail band. |
| | That's the easiest part, because we can introduce a dummy group that will break with every row in the data source. Such a group would have an expression like the following: |
| |
| | $V{REPORT_COUNT}
|
| | If one dummy group is not sufficient for you and you have a giant detail band, you could introduce as many dummy groups as you want to, all of them with the same dummy expression. |
| |
| | Problem solved. |
| |
| | Hey, we forgot about that other situation when one of the group headers or footers is larger than one page. |
| | No problem. The solution is the same. You just have to introduce a new group, with the same expression as the one which poses the problem, and to split that group header or footer content between the two. Those two groups will break together and behave like one, so you can distribute the elements on their headers and footers as you want to. |
| | The band height validation check could be passed this way. |
| |
| 4. Making HTML, XLS or CSV friendly reports | top |
| |
| | When generating reports, the ^JasperReports engine uses the absolute position of each report element to layout the content of each page. Absolute positioning the report elements allows full control over the content of the output documents. |
| |
| | The PDF format supports absolute positioning of the text and graphic elements on a document page and this is why it is widely used on various platforms. You can be sure that once created, a PDF document will look the same no matter what is the viewer's platform. |
| | The ^JasperReports proprietary document format (net.sf.jasperreports.engine.JasperPrint objects) is also based on absolute positioning of elements on the page. The position and size of each element are defined by the x, y, width and height properties. |
| |
| | However, other document formats such as HTML or XLS, do not support absolute positioning of the text and graphic elements. The content of such documents is arranged in a grid or table structure. |
| | Of course, some may argue that absolute positioning of elements in HTML is possible thanks to CSS, but you can be sure that the CSS standard functionality is far from being implemented in all browsers or that the same HTML document won't look the same everywhere. |
| |
| | This is why the ^JasperReports built-in exporters that produce HTML, XLS or CSV documents use a special algorithm in order to arrange the elements present on a certain document page in some sort of a grid. |
| | When the report designs are very complex or agglomerated, passing from absolute positioning to grid or table layout produces very complex tables with many unused rows and columns, to make it for the empty space between elements or their special alignment. |
| |
| | There are a few, very simple guidelines that should be followed by those who want to obtain optimized HTML, XLS or CSV documents when using the built-in^JasperReports grid exporters. |
| |
| | 1. Minimizing the number of rows and columns in the grid oriented formats (minimizing the number of "cuts"). |
| | To do that, you have to make sure you align your report elements as often as you can, both on the horizontal and the vertical axis and that you eliminate the space between elements. |
| |
a) Inefficient layout
b) Grid friendly layout |
| |
| | 2. Avoiding overlapping report elements. |
| | Make sure report element will not overlap when the report will be generated. This is because if you have two elements that share some region, it will be impossible for them to share the same cell in the resulting grid structure. You might obtain some unexpected results if elements overlap. |
| |
| | 3. Give up using page headers and page footers. |
| | Especially when you want to obtain documents in which the page breaks are not relevant (CSV for example), make sure that you suppress the page header and page footer sections in your report design. You could also minimize the top and bottom margins for your report, so that when exported to HTML, XLS or CSV, your documents will be made of a single chunk, without page separators. |
| |
| 5. Excel Color Palette | top |
| |
| | ^JasperReports allows you to use any color for your report elements. |
| | However, when exporting to XLS format, you have to be aware that this type of files supports only a limited set of colors. |
| |
| | Here is the Excel Color Palette containing all the 40 colors that XLS may use. Make sure you use one of these colors if you want to eventually export your reports to XLS format. |
| |
| | |
| | #FFFF00 YELLOW |
| | #969696 GREY_40_PERCENT |
| | #99CC00 LIME |
| | #CC99FF LAVENDER |
| | #FFFF99 LIGHT_YELLOW |
| | #008000 GREEN |
| | #C0C0C0 GREY_25_PERCENT |
| | #339966 SEA_GREEN |
| | #FF9900 LIGHT_ORANGE |
| | #FF0000 RED |
| | #003366 DARK_TEAL |
| | #FFFFFF WHITE |
| | #99CCFF PALE_BLUE |
| | #00FFFF TURQUOISE |
| | #008080 TEAL |
| | #000080 DARK_BLUE |
| | #FFCC00 GOLD |
| | #33CCCC AQUA |
| | #333300 OLIVE_GREEN |
| | #808080 GREY_50_PERCENT |
|
| | |
| | #003300 DARK_GREEN |
| | #808000 DARK_YELLOW |
| | #FF00FF PINK |
| | #FF99CC ROSE |
| | #3366FF LIGHT_BLUE |
| | #FF6600 ORANGE |
| | #993300 BROWN |
| | #993366 PLUM |
| | #800080 VIOLET |
| | #333399 INDIGO |
| | #000000 BLACK |
| | #00CCFF SKY_BLUE |
| | #333333 GREY_80_PERCENT |
| | #CCFFFF LIGHT_TURQUOISE |
| | #CCFFCC LIGHT_GREEN |
| | #666699 BLUE_GREY |
| | #0000FF BLUE |
| | #00FF00 BRIGHT_GREEN |
| | #800000 DARK_RED |
| | #FFCC99 TAN |
|
|
| |
| | If the colors you use in your report designs do not match any of these acceptable colors, the XLS exporter will use a special algorithm to determine which is the nearest one by comparing the RGB levels. But the results might not be always what you expect. |
| |
| 6. Returning values from subreport | top |
| |
| | You can return values from subreports using special parameters as containers. |
| |
| | Here�s an example: |
| |
| | Problem: |
| | I want to pass to my master report the total number of records that the subreport had. |
| |
| | Solution: |
| | In the master report, I define a special container parameter that will hold the values that I want to return from the subreport. |
| |
| |
new java.util.HashMap()
|
| | I pass this container parameter to my subreport, so that it can store the returned values in it. |
| |
| |
$P{ReturnedValuesMap}
|
| | In the subreport template, I declare the container parameter. Even they both have the same name, the master report parameter and the subreport parameter are in fact totally different entities. |
| |
| |
|
| | In the subreport, I use the dummy |
| |
| |
($P{ReturnedValuesMap}.put(
"MY_RETURNED_VALUE", $V{REPORT_COUNT}) == null
)?Boolean.FALSE:Boolean.FALSE
|
| | Remember that the returned value can be placed in the container parameter also using scriptlets. I chose this trick for simplicity reasons. |
| |
| | Back in the master report, if I want to display the returned value, I just extract it from the container parameter: |
| |
| |
$P{ReturnedValuesMap}.get("MY_RETURNED_VALUE")
|
| | You might ask why is it that the text field uses evaluationTime="Group". |
| | This is because one of the problems with the returned values from subreports is that these values are returned after the content of the band elements has already been evaluated. |
| | If you want to display subreport returned values in the same band as the subreport itself, you'll end up seeing that they were returned too late for that. |
| |
| | So, in order to be able to display the returned values in the same master report band that contains the subreport itself, I had to delay the text field evaluation. This was done by introducing a dummy group in the master report and let my text field be evaluated when this dummy group ends. |
| | This dummy group breaks with every record in the data source and has no header and footer of its own. |
| |
| |
$V{REPORT_COUNT}
|
| | This dummy group served my purpose because my subreport and the text field were placed in the detail section of the master report and it had to break with every detail. If the subreport is placed in a different report section, the dummy group expression should be adapted to fit the given situation. |
| | The use of a dummy group is not necessary if you do not need to display the returned values in the same report section that contains the subreport itself. |
| |
| 7. Fake title and summary sections | top |
| |
| | The title and the summary are special report sections that are not accompanied by the page header and footer on the pages that they occupy. This is more obvious when the title or the summary overflows. |
| |
| | Sometimes is useful to have a title section that starts after the page header on the first page or a summary section that gets accompanied by the page header and footer on all the pages that it overflows to. |
| |
| | This can be achieved by introducing fake title and summary sections. |
| | A fake title can be the group header section of a report group that breaks only once per report. Such a dummy group would have an empty group expression. Its header will get printed only once at the beginning of the report. |
| | The fake summary can be introduced also by using the footer section of such a dummy group wit an empty group expression. |
