Index

Using Styles in Your Report

Introduction

JReport style is one of the most important concepts in both JReport Designer and JReport Enterprise Server. JReport styles, organized in style groups, can hold a large amount of pre-defined object properties, which gives you more controls over the appearance and presentation of your report. By using JReport styles, you can create various visual presentation sets from a single report, and change the visual presentation of your report at run-time according to your needs. 

What is a style?

A style in JReport is a set of object attributes that you can assign to objects in your report to alter their appearance and characteristics. When you apply a style, you apply a whole group of property entries at once. For example, you may want to format the headings of a report to make them stand out. Instead of formatting them step by step as 12pt, Arial, and center-aligned with blue background, you can simply achieve the same goal in one step by applying a pre-defined style that contains the style properties you desire.

Each style has a style type to indicate its application scope, e.g., a style with Label type can only be applied to label objects, and a style with DBField type can only be applied to a dbfield.

What is a style group?

A style group is a set of styles that you can apply to a report to quickly change its appearance and characteristics. When you apply a style group, you apply a whole group of styles at once. To apply a style group to several report objects, you must first have the report objects selected, and then apply the style group. The style of each style type will be applied to the report object of the corresponding type.

By simply selecting a style group at run time, you change the look and feel of your report in a dramatic way. JReport style groups can be nested, where the parent group is used as a container of other groups.

Static Styles and Dynamic Styles

JReport style falls into two categories - static style and dynamic style.

A static style is a style that you can directly apply to the object in report, which means that you can see the style effect immediately, just like what you get after setting the properties step by step in Report Inspector. The static styles are mainly used to simplify the repetitive formatting work during design period. The styles you apply using the Style box on the Standard toolbar are all static styles.

Starting with version 5.2 JReport supports a new feature - dynamic style groups. Both of the static and dynamic styles work together, and your existing reports still work as before.

A dynamic style, created and edited using Catalog Browser, is a style that takes effect at run-time; it doesn't affect the report design layout in design mode. You can switch among the style groups according to your needs at run-time to present your report in rather different look and feel. The styles you specify in the Style property entry in Report Inspector will run as dynamic styles.

Predefined Style Groups

There are some pre-defined style groups in JReport Designer, which is mainly used as a demonstration for reports that contain table objects and crosstabs.

In each predefined group, you can find styles named as column1 and column2. These two styles are used as an example to show how to alter the styles for each column of the table object. For reports that contain a table object, if you want the style of each table column to alter, in the Report Inspector, select the table object, specify a style group for the Pattern property entry. When you view the report, you will find the styles column1 and column2 are repeatedly applied to each table column, in order. If you choose to run the report using other style group, the style of the table columns will also be changed, so long as the style group you select contains the styles column1 and column2.

If you want to apply another different style for more table columns, create a new column type style using the name column3. The styles will be applied to the columns accordingly like below:

Suppose there are three column type style in the style group, which includes column1, column2, and column3.

Column Type Style	Applies to	Column of the Table object
column1	=>	the 1st table column
column2	=>	the 2nd table column
column3	=>	the 3rd table column
column1	=>	the 4th table column
...	...	...

You can create as many column type styles as you wish, please remember to name the style as column1, column2, column3, and so on.

Setting up Styles in JReport Designer

You create and set up your own styles in JReport Designer, using the Styles tab on Catalog Browser. To open Catalog Browser, on the View menu, click Catalog Browser.

To set up the dynamic style group feature for your report, take the following procedures:

1. Create new dynamic style groups
2. Create new dynamic styles
3. Specify a dynamic style group for your report
4. Link the dynamic styles to report objects

Create a new dynamic style group

To create a new dynamic style group,

1. On the Styles tab of Catalog Browser, select the group node where you want to create the new group, and then click New Style Group on the toolbar.
2. Specify the Group Name and Description, and then click OK.

Note:

• The root of the style group tree can hold only style groups. The styles must reside in the style groups. You cannot create a style directly under the style group tree root.
• The default style group can neither be deleted nor nested; you cannot create style groups in the default style group.
• The name of each style group must be unique in the style group tree.

Create a new dynamic style

1. On the Styles tab of Catalog Browser, right-click the group node where you want to create the new style, and then click New Style.
2. Specify the Style Name, Style Types and Description, and then click OK.
3. Add the property items you want to change for the style, and then click Save. You can also change the property values on this dialog.
4. On the Catalog Browser, double-click the style you created to show the Properties sheet.
5. Edit the property entries for the style.

Notes:

• Sometimes you may not be able to edit the property entries in the Properties sheet. In such case, on the File menu, click Options, click the Advanced tab, and then uncheck the Forbid editing data object properties option.
• You can create more than one style that use the same style type, thus you can apply different styles to the report objects that have the same type.
  
  For example, suppose that you have a number of dbfields in your report, such as address fields, totals, quantity fields, and so on. Probably, you do not want all this fields look the same. You can create two or more styles, using the same style type - DBField, and then apply them separately to the fields that you want to distinguish from others.
• You can apply a default style to all the objects that hold the same type.
  
  In the Default style group, create a new style, make sure the style name and style type are the same, for example, style name=Label, style type=Label, and then modify the style properties. Therefore, when a new object of that type is inserted into the report, the default style will be applied to it automatically. Please note that you can see the difference only at run-time.

Apply a static style

 

To apply a static style, first select one or more report objects to which you want apply the style, and then select a style or style group in the Style box on the Standard toolbar.

To apply a style that you created in Catalog Browser as a static style,

1. In Report Inspector, click the report root node, scroll down the Properties sheet to find the StyleGroup property entry, and then select the style group that contains the style you want to apply from the StyleGroup drop-down list.
2. On the report design layout, do one of the following:
   
   To apply a style to a single object, select the object, and then select the style in the Style box on the Standard toolbar.
   
   To apply styles to more than one object, select the objects, and then select the style group in the Style box on the Standard toolbar.

Notes:

• If only one object is selected, the styles of the same type will be shown in the Style box. If more than one object is selected, the style groups for the report will be shown in the Style box.
• The styles or style groups you select in the Style box always function as static styles or style groups. Always use the Style box to apply static styles.
  
  Please do not try to key in the style name in Style property entry of Report Inspector, because JReport will consider the style you enter as a dynamic style.
• The styles or style groups you created using Catalog Browser are marked with asterisks *  in the Style box to make them stand out from the built-in ones.
  
  The styles or style groups with asterisks (*) in the Style box are used as static styles (style groups), just like normal static styles (style groups) listed in the Style box, say, they will take effect immediately after selection, and the applied styles of the selected objects cannot be changed dynamically.
• If more than one style entry in a style group share one style type, when you select this style group from the Style box, JReport will randomly apply a style with matching type to the objects you select.
  
  For example, suppose you have two DBField type styles - stlNormalField and DbField - in the style group Default, as shown in the picture below, when you select *Default in the Style box, JReport will randomly select a style to apply, either stlNormalField or DbField.
  
  In such case, you are recommended to keep at most one style of each style type in one style group.
  
  
• When you apply a style (style group) to an object (objects), the Style property entry in Report Inspector will be filled with the style name, or prefixed with an asterisk (*) if it is not a built-in one,  for example, *Label. This does not mean that you can key in the style name in Report Inspector to make the styles take effect immediately, say use as static ones. Any styles you specify in Report Inspector will work as dynamic styles, which work at run-time only.

Specify a dynamic style group for your report

By default, JReport Designer does not use any style group for the reports you developed. To switch among style group at run time, you must specify a default style group for your report.

In the Report Inspector, select a style group for the StyleGroup property.

By setting the StyleGroup property to a style group you switch on the dynamic style group feature for this report.

Link a dynamic style

You need to link a dynamic style with the report objects before they can take effect at run-time.

To link a dynamic style, first select one object, or more with the same type, to which you want to link the style, and then type the style name in the Style property entry in Report Inspector.

Notes:

• You can also select the style name from the drop-down list of the Style property. However, newly created styles will not appear in the drop-down list of the Style property until the catalog is saved and the report is re-opened.
• The style you link to the report object(s) will not affect the report layout in design mode until run-time.

Modify a style

To modify a style, do one of the following:

• On the Styles tab of Catalog Browser, right-click the style you want to modify, and then click Edit Style. Add or remove the property entries according to your needs, and then click Save. You can also change the property values on this dialog.
• On the Styles tab of Catalog Browser, double-click the style you want to modify to show the properties sheet, change the property values on the properties sheet.

Note:

Sometimes you may not be able to edit the property entries in the Properties sheet. In such case, on the File menu, click Options, click the Advanced tab, and then uncheck the Forbid editing data object properties option.

Remove a style

On the Styles tab of Catalog Browser, right-click the style you want to remove, and then click Delete.

Modifying the XML Style Files

In addition to modifying the styles (style groups) in JReport Designer, you can modify the xml format styles (style groups) outside JReport Designer.

When you save the catalog, the style information will be saved to disk at the same time, the location of the related file is like below:

	File Name	File Description	Location
1.	CatalogName_stl.xml	Style Group Structure in the Catalog	Catalog Folder (The directory where the catalog resides)
2.	StyleGroupName_stl.xsd	Group/Style information	%JReportInstallRoot%\template

The CatalogName_stl.xml file keeps the style group structure information, which might be like the following sample.

The style group structure in Catalog Browser:	The corresponding information in Tutorial_stl.xml:
	<?xml version="1.0" encoding="UTF-8"?> <StyleGroup> <StyleGroup name="Default"></StyleGroup> <StyleGroup name="GroupA"></StyleGroup> <StyleGroup name="GroupB"></StyleGroup> </StyleGroup>

The StyleGroupName_stl.xsd file keeps the group/style information, which in the above sample might be like the following:

The file content of GroupA_stl.xsd:

As you can see in the above code sample, an xml style group file contains style group information, style information, and the style property entry information. You can edit the attributes of an element, such as name, type, default, and so on.

To add a style entry, copy and paste the style information section, and then modify the attributes.

To add a style property entry, copy and paste any element line, and then modify the attributes.

To delete a style entry or style property entry, select corresponding section, and delete it.

To add a new style group,

1. Copy and paste an existing xml style group file.
2. Rename it using the expected name (Format: GroupName_stl.xsd).
3. Change default attribute in the GroupName element line using the expected group name, please make sure it is the same as the group name specified in the xml style group file name.
4. Add a new line for this group in the CatalogName_stl.xml file. For example, if the new group name is GroupC, then insert the following line to the file:
   
   <StyleGroup name="GroupC"></StyleGroup>
5. Do the modification work in the xml style group file (GroupName_stl.xsd).
6. Open the catalog in JReport Designer, you can see the changes.

Note:

• The value you type must be consistent with other attributes in the element, and can be recognized by JReport Designer.
  
  For example, if you want to change the FontFace property, you must type a proper font name that JReport support for the default attribute, such as Arial, Times New Roman, Tahoma, and so on. You cannot type strings that cannot be recognized by JReport, otherwise the element will not take effect at run-time.
• You must be sure that the GroupName attribute must be consistent with the xml style group file name.
  
  Take GroupA for example, in the xml file, the GroupName attribute is <xs:attribute name="GroupName" type="xs:string" default="GroupA"></xs:attribute>, then the xml style group file name should be GroupA_stl.xsd.

Deploying Reports to Enterprise Server

When you deploy your reports to Enterprise Server and you have set Style Group property, Deploy Wizard will ask you to transfer the style group files.

Add the style groups and then click OK, the files get transferred.

Viewing Reports on JReport Enterprise Server

After you set up the styles for your reports in JReport Designer, you deploy your reports to JReport Enterprise Server. When you schedule the report, please make sure you have the Enable Style Group option enabled and a style group selected.

Using Styles in Your Report

JReport styles can simplify your work in a lot of aspects, now let's use a simple example to illustrate how to use JReport styles and style groups in your report. 

1. Start JReport Designer, open the existing report invoice.cls in Tutorial.cat. We are going to apply styles to this report.
   
   
2. Open Catalog Browser, switch to the Styles tab. Create a new style group called Red under style tree root.
3. Create a new style with the following information:
   
   

   StyleName:	Title
   StyleType:	Label
   Description:	[You may leave this field blank.]

   Add the property entries and fill their values as follow:
   
   

   Bold:	true
   FontSize:	30
   FontFace:	Times New Roman
   Alignment:	LeftCenter
   Italic:	true
   Background:	Transparent
   Foreground:	0xfc5e03

   Create other new styles using the information below:
   
   

   StyleName:	Line
   StyleType:	Line
   LineColor:	0xfc5e03

   
   

   StyleName:	lblFieldName
   StyleType:	Label
   FontFace:	Verdana
   FontSize:	7
   Bold:	true
   Background:	0xfc5e03
   Foreground:	0xffffff

    

   StyleName:	Box
   StyleType:	Box
   BorderColor:	0xfc5e03

4. Open Report Inspector, select invoice report root, scroll to find StyleGroup property entry in the Property Sheet, type Red in the value field.
5. Select the report title label Invoice on the report design canvas, and then type Title for the Style property field in Report Inspector.
6. Select field name labels Bill to, Ship to, Cust ID, No., Order Date, Required Date, Ship Date, Ship Via, Terms, Item, Product No., Unit Price, Quantity, Amount, and Total, and then type lblFieldName for the Style property field in Report Inspector. Use the CTRL key to select multiple objects. If you have difficulties in selecting the objects, please use Report Inspector as an aid.
7. In Report Inspector tree view, select all the line objects, and then type Line for the Style property field in the Property Sheet of Report Inspector. To select consecutive objects in Report Inspector, select the first object, hold down the SHIFT key, and then click the last item.
8. In Report Inspector tree view, select the box object, and then type Box for the Style property field in the Property Sheet of Report Inspector.
9. Now we are going to create a new style group called Green. In Catalog Browser, right-click Red style group, and then click Copy Style Group. Rename the new group to Green, double-click group Green to show the Property Sheet, and then modify the information of each style in using the below information:
   
   

   Title
   FontFace:	Arial Black
   FontSize:	25
   Foreground:	0xfc5e03
   Line
   LineColor:	0xfc5e03
   Box
   BorderColor:	0xfc5e03
   lblFieldName
   Bold:	true
   FontSize:	7
   FontFace:	Arial
   Background:	0xfc5e03
   Foreground:	0x000000

10. Save the report and catalog.
11. Start JReport Enterprise Server, and then deploy the report Invoice.cls together with the catalog Tutorial to the server.
12. Visit the URL http://localhost:8888 to access the AccessDemo catalog, point to the report Invoice and then pick Advanced Run.
13. On the View Format tab, check Enable Style Group, select Red from the drop down list to the right, and then click Submit. The report may somewhat look like the below picture.
    
    
    
14. Run the report again, this time choose the Green group as the style group.
    
    

Limitations

The subreport in the main report works as a report object and can be applied with a Subreport type style. That is to say, the original styles (if any) applied to an individual report works no longer after this report is inserted into another report as a subreport, instead, you can apply a Subreport type style to the inserted subreport to control its appearance and presentation, just like what you do with a normal dbfield.

Index