Introduction to JasperReports styles
JasperReports provides the concept of report style. Style in JasperReports is actually the subset of all the report element properties that can be defined in report template. Every report element like rectangle, text element, image, chart and others can be associated with report style. There are several main use-cases of what property value is taken from where based on different criteria. But before diving into these rules we need to understand what does it mean default style. If any style (internal or external) marked as default - it means that the style will be applied to all the report elements in report template without explicitly associated with them. So don't be surprised if report element look and feel is different from its default one - check if there is default style defined. But with JasperWave everything will be easy and transparent - you will see immediately where property value is taken from. Will see it soon...
Let's first describe the cases:
- UC1. Property default value - No style assigned (explicitly or by default style). The default property value will be applied.
- UC2. Property non-default value - No style assigned (explicitly or by default style). Overridden (non-default) property value will be applied.
- UC3. Property default value - Style assigned (explicitly or by default style). The style property value (if defined in the style) will be applied.
- UC4. Property non-default value - Style assigned (explicitly or by default style). Overridden (non-default) property value will be applied even if the property is defined in style. So the property non-default value has the highest priority.
Explicitly means that style is associated with report element by defining corresponding property of report element. The goal of this tutorial is not to describe in details the JasperReports styles approach and use - so please refer to JasperReports official documentation if you are not familiar enough with JasperReports reporting engine and styles there.
For now just try to remember the cases above and understand what everyone means.
Internal and external styles
Every style can defined and saved in two different let's call it locations: report template and style template. Let's further call the first style internal and second one external.
Internal styles are saved in the same report template definition file and can be used in one report template only. External styles are defined and saved in special style template file. Then these style templates can be associated with any report template and styles defined there can be applied on report elements inside report template.
It is possible to associate several style templates with one report template in two ways:
- Directly. Several style templates are connected with report template by explicitly adding references from report template to style templates.
- Indirectly. Style template can have reference to another style template. So by adding reference to style template that itself has reference to another style template you will have report template associated with several style templates.
Here is the concepts. For details please refer to JasperReports documentation. Especially it will be helpful to look at JasperReport official report template example StylesReport.jrxml and associated style templates styles.jrtx and base_styles.jrtx.
What is very important to know about styles in JasperReports is that styles are organized in hierarchy way. It means that every style can have parent style. For simplicity lets take a look at JasperReport official report template example StylesReport.jrxml and associated style templates styles.jrtx and base_styles.jrtx:
There are several important points that you should understand and remember from the hierarchy above:
- Styles hierarchy is constructed without taking into account if the style is internal or external. In the example above the style are defined internally and externally inside two style templates
- Styles inheritance. It means that if the Very Strong (base_style.jrtx) style will be assigned to report elements then the property values will try to be resolved Very Strong (base_style.jrtx) - Strong (base_style.jrtx) - Base (base_style.jrtx) according to the tree structure.
- Internal style has higher priority over external one with the same name. In our case we have Serif Note style defined both internally and inside styles.jrtx style template.
The example above shows most of JasperReports styles features but it is too complicated to be a real life example. So it is not recommended to repeat it - try to design hierarchy and location of styles as simple as possible.
Styles management in JasperWave
The section presents the way JasperWave works with JasperReports styles. The goal was to provide transparent and intuitive solution by improving JasperWave properties framework, style management dialog and connect them to each other. On the next sections all the details of this approach will be presented. Also several special cases will be explained to help you understand JasperReports styles more deeply.
JasperWave properties framework
All the properties that can be populated from assigned style have several major improvements:
- The property always shows the real value currently used. No more DEFAULT or NULL values.
- The property has two new buttons to the right:
- Style. It will be clickable and enabled when the property value is taken from style. The result of button clicked will be the opened style management dialog with the associated style in focus.
- Default. It will be clickable and enabled when the property value is overridden. The result of button clicked will be to assign (or reset) the property to its default value.
UC1. Property default value - No style assigned or property is not defined in assigned style
The property reflects the case when the default value is not changed and there is no style (or default style) associated with the corresponding report element. Or the style assigned has no such property defined in the style and in all its parent styles. In any case it tells you that the default value of the property is not changed and nothing taken from styles (if assigned).
UC2. Property non-default value - No style assigned
The property value that is overridden has the highest priority over any values comes from the style. So this case shows the property value that is different from default one. The property value can be set to the default one by using enabled default button.
UC3. Property default value - Style assigned
The property value is not defined in report template and is taken from assigned style or default style. The style management dialog can be opened by using enabled style button.
UC4. Property non-default value - Style assigned
The case is similar to UC2 but here there is property value taken from some style. But property value that is overridden in the template has the highest priority over any values comes from the style. But if the default button will be clicked then the UC3 case will be activated.
So everything is very simple - these two buttons always show you where the property values is taken from:
- The value is not explicitly defined anywhere - in report template or style. So the default value will be applied. Both buttons are disabled.
- Value is explicitly defined in report template and it doesn't matter if it is defined in any style associated with report element. Style button is disabled and default button is enabled.
- Value is not explicitly defined in report template and there is style (associated or default one) where the value for the property is defined and taken from. Style button is enabled and default button is disabled.
Remember that it doesn't matter if the style is internal or external.
External style templates
As it was said above JasperReports styles can be internal and external. External styles are stored in separate files with .jrtx extension.
To add or create new style template select the action shown below:
References to external styles are actually Java expressions with Type and Value.
By default java.lang.String Type is used.
Value is just Java string that will be cast to the Type when report will be compiled: (Type)Value.
JasperWave allows to load style templates that are located in file system. java.lang.String Type must be used and Value must contain the relative or absolute path to a style template file.
- Relative . It means that path needs to be relative to the report template location. So if the style template is located in the same directory as report template then just file name can be used.
- Absolute . It means that the complete path to the style template file must be defined in template expression.
For you convenience JasperWave expression editor has special tool item that will open File Select dialog. Yoг can select existing style template file or define new one.
After pressing OK button in expression editor JasperWave will do the following:
- Will try to find existing style template treating the location as relative path. If the template is available then styles will be loaded from there.
- Will try to find existing style template treating the location as absolute path. If the template is available then styles will be loaded from there.
- Will try to create new style template treating the location as relative path. Then this template will be available in Style Manager Dialog and styles can be placed there.
- Will try to create new style template treating the location as absolute path. Then this template will be available in Style Manager Dialog and styles can be placed there.
- If none of above steps is successful then the reference to style template will be saved in report template but style template will not be available in Style Manager Dialog and it will not be possible to place styles there.
Below is the example of new style template with absolute location:
More sophisticated style template management will come with the next releases. Current approach allows to easily create/add style templates and work with styles there.
Style management dialog
This is how style management dialog looks like in JasperWave.
Tree view presents all the styles loaded from report template and style templates. Styles are presented as a hierarchical tree. Internal. external and default styles are accompanied with special icon and displayed with special fonts.
External style is displayed with special icon, has italic font and the name of style template is added to the right.
Internal (embedded) style.
Internal style is displayed with special icon and has normal font.
Default style (whether internal or external) is displayed with bold font.
Every style has several attributes.
The name of the style.
If the style is default. If default it will be shown with bold font on style tree.
Attribute shows if the style has parent style where report properties definitions will be inherited from.
Attribute indicates if the style is internal or internal (embedded). By changing this attribute value you will move the style between report template (making it internal) and style templates (making it external).
Report element properties
The section consists of all the report element properties that can be part of report style. All the properties are logically grouped based on their visual influence on different report elements. Group names are self-describing.
Defined / not define property value.
The icon/button to the right of every report element property is very important. If it is blue and enabled then it means that the property is defined inside this style. Clicking this button will cancel the property definition inside this style. If the property is not defined in the selected style then the button is disabled and grayed.
Preview section allows to see how the selected style (and its parents hierarchy) will change the rendering of report element it will be assigned to. You can select text, rectangle and image report elements for preview.
The whole picture
Now it is time refresh everything that was learned previously and take a look at real example. Let's open the report StylesReport.jrxml from the official JasperReports distribution in JasperWave.
Let's select one of the static text elements in the report and explore how style staff is presented in JasperWave.
- Static text is selected.
- Open property categories Text Element and Style.
- In Style category it is seen that the report element is associated with Very Strong style.
- In Text Element category we see that Horizontal alignment is defined on report template level and is not taken from the style. Its value is Right.
- Vertical alignment property has value Middle and the value is taken from the style.
- Click the Style button to the right of Vertical alignment property. The style management dialog will be opened.
- It is interesting to know where the Vertical alignment property value is defined.
- Very Strong style has no such values defined.
- Navigate to parent styles of Very Strong.
- Strong style has no Vertical alignment property defined but Base style has this property defined.
- Also you see that Horizontal alignment property is defined in Base style but the property is also defined on report template level. As you remember the property defined on report template level has priority over property defined in any style.
Default style concept
When any style is marked as default then every report element will be implicitly associated with this style. It can be strange when new report element is placed inside report template and is rendered differently from default properties values and properties in property view don't show what values are applied to the report element. Now everything is transparent. Every property shows the real value and where the value is taken from. In our example we see that Horizontal alignment has Center value and style button is highlighted and enabled. Click the button and style management dialog will be opened with default style selected.
Box properties is a special case because there can be confusion for someone who don't understand how it works. Let's take an example and explain what, where and why is displayed.
- Static text element is created.
- Style Box Style is created and assigned to static text.
- Box width, style and color properties are defined for all sides and top in the style. See style definition in the screenshot.
- Static text takes all box properties from the style except box color for right and left sides. These two properties are defined locally on report element level which has higher priority over ones taken from the style.
It is very easy to navigate and understand what is taken from where.
One important point is that you should remember that color, style, width and padding are taken from all sides definition if not defined on top, right, bottom or left levels. But the property control in properties view shows its own values. So it is common situation like we have in our example.
- Property control in properties view for box bottom color show that is not defined locally and is not taken from style. It seems that it should be black.
- But assigned style has box all sides color defined as blue. This color is taken to render the box bottom color.
- Box top color is defined as red in the style.This is explicitly reflected in properties controls and visual editor.
- Box right and left colors are overridden as green on static text locally. This is explicitly reflected in properties controls and visual editor.
Summary - no more magic!
JasperWave goal with implementing JasperReports properties was ta make it very intuitive and transparent. So everyone always knows what, from where and why is taken. No more DEFAULT or NULL values in properties controls, magic and time spent to understand why the element is rendered this way. Just a few seconds and several clicks to understand and see the whole picture.
Use it with pleasure.