morlandin

OverviewInstead of repeatedly defining similar styles for each report, you can define a style in the styles library and reuse it in other reports. To achieve this you can use a style template (called also Styles Library in iReport), which is a container where one or more styles are stored. In this container there must be only styles. Creation of a TemplateFrom JasperSoft Studio open the menu File->New->Style Template File Now select the folder in your workspace where to put the template file and the name of the file. Then hit Finish. Now a new style template will be created, with already a style in it. At this point you can create new styles by right clicking on the Styles node, into the Outline view, and select "Create Style". To edit a style simply select it and edit its properties from the property tab, like you do in a normal report. Using of a template inside the reportOpen a report, right click on the Styles node into the Outline View and select "Create Style Template". Now a new dialog will be opened and from here you can select a style template created before. Select the style and hit Ok. Now you can use the styles defined in the imported template in a similar way of the normal styles. Just select an element and from its properties use the one named "Style". Here you will find a combobox showing the available styles. But note that are shown only the internal ones, the external ones (which comes from a template) must be selected by typing directly their names.

Overview JasperReports Server is a stand-alone and embeddable reporting server. In this tutorial we will see how to connect Jaspersoft Studio to JasperReports Server, and how to upload and download a report from the server. Prerequisites Since we need to interact with JasperReports Server we need the server's URL and the credentials to access it. If you do not have both of these, you can install JasperReports Server locally. To do this, follow THIS link and download the correct version for your operating system, then install it following the on-screen instructions. Connection to JasperReports Server To have an easy-to-replicate example, suppose that we are using a local installation of JasperReports Server. To check if our server is running, open your browser and copy in the address bar this URL: http://localhost:8080/jasperserver/login.html You should see a window like this: Now you can start Jaspersoft Studio. Click the Repository Explorer tab, then select Create a JasperReports Server Connection. A dialog to insert the server data appears. Fill it in as follows: Name: the name of the connection. You can use any name you want. For this example we will leave the default name: JasperReports Server. URL: the address of the server. The default address is already correct if we are using a local server. For this example the correct address is http://localhost:8080/jasperserver/services/repository. User: the username to access the server. The default for the local server is "jasperadmin". Password: as with the username, for the local server by default it is "jasperadmin". Then click the Test Connection button to test the connection. If everything is working, click Finish. Now you are connected to the server and you can upload and download reports. Publishing a Report on JasperReports Server For this section, we will use the one created during the tutorial Report Structure in Jaspersoft Studio. Open the report and click the button with a blue arrow in the upper-right corner of the designer. In the opened window you can browse the server directory structure to choose where to place the report. Select the Reports folder as in the image above. Name the report unit you are creating to contain all the files for the report we are uploading (for this example we can use "ColumnsSample"). Then click Next. In the next step we have to handle the data source. Exporting a report is quite simple, but exporting the data source used to fill the report it isn't so trivial. For exporting the data source we have three options: Data source from repository: the server will use a data source already there it to fill the report, so we will only need to browse the server until we find the wanted data source. Local data source: This option is useful is we want to publish a Datasource which already exists in the Studio, to the Server. Further details in the following section. Don't use any data source: only the report is exported without any data source connection We will use the third option, which is the default one, and click Finish. The report is uploaded to the server and, if there are no errors, an appropriate message will be shown. Local data source details As stated previously, this option is useful to publish a datasource which has been already defined in the studio to the JasperReports Server. After selecting Local Datasource, you can select the kind of Datasource that you want to publish to th JasperReports Server, like jdbc. After doing that, you will have to provide the name the Datasource will be having as a whithin the Report unit's folder, and after that, the next window will give you the possibility to select the Import from Jaspersoft Studio button, where you can pick any of the already defined Datasource, and as soon as you that, all the Datasource's details will be filled in and ready to be published on the JapserReport Server as well! Al you have to do is to press Finish and it's done.

Overview A report is defined by means of a type page. This is divided into different horizontal portions named bands. When the report is joined with the data generating the print, this section is printed many times according to their functions (and according to the rules that the report author has set up). For instance, the page header is repeated at the beginning of every page, while the detail band is repeated for every single read record. What is a Band The type page is divided into nine predefined bands to which new groups are added. In addition, Jaspersoft Studio manages a heading band (group header) and a recapitulation band (group footer) for every group. A band is always wide as the page width (right and left margins excluded). However, its height, even if it is established during the design phase, can vary during the print creation according to the contained elements; it can "lengthen" toward the bottom of a page in an arbitrary way. This typically occurs when bands contain subreports or text fields that have to adapt to the content vertically. Generally, the height specified by the user should be considered "the minimal height" of the band. Not all bands can be stretched dynamically according to the content, in particular the column footer, page footer and last page footer bands. The sum of all band heights (except for the background) has to always be less than or equal to the page height minus the top and bottom margins. Band Types Following there is a brief descriptions of the available bands. Title The title band is the first visible band. It is created only once and can be printed on a separate page. Regarding the allowed dimensions, it is not possible during design time to exceed the report page height (top and bottom margins are included). If the title is printed on a separate page, this band height is not included in the calculation of the total sum of all band heights, which has to be less than or equal to the page height, as was mentioned previously. Page Header The page header band allows you to define a page header. The height specified during the design phase usually does not change during the creation process (except for the insertion of vertically resizable components, such as a text fields that contain long text and subreports). The page header appears on all printed pages in the same position defined during the design phase. Title and summary bands do not include the page header when printed on a separate page. Column Header The column header band is printed at the beginning of each detail column (The column concept will be explained later in the "Columns" section). Usually, labels containing the column names of a tabular report are inserted in this band. Group Header A report can contains zero or more group bands, which permit the collection of detail records in real groups. A group header is always accompanied by a group footer (both can be independently visible or not) different properties are associated with a group. They determine its behavior from the graphic point of view. It is possible to always force a group header on a new page or in a new column and to print this band on all pages if the bands below it overflow the single page (as a page header, but at group level). It is possible to fix a minimum height required to print a group header: if it exceeds this height, the group header band will be printed on a new page (please note that a value too large for this property can create an infinite loop during printing). Group Footer The group footer band completes a group. Usually it contains fields to view subtotals or separation graphic elements, such as lines. Column Footer The column footer band appears on at the end of every column. Its dimension are not resizable at run time (not even if it contains resizable elements such as subreports or text fields with a variable number of text lines). Page Footer The page footer band appears on every page where there is a page header. Like the column footer, it is not resizable a run time. Last Page Footer If you want to make the last page footer different from the other footers, it is possible to use the special last page footer band. If the band height is 0, it is completely ignored, and the layout established for the common page will also be used for the last page. Summary The summary band allows to insert fields concerning total calculations, means, or whatever you want to insert at the end of the report. In other systems, this band is often named report footer. Background The background band was introduced after insistent requests from many users who wanted to be able to create watermarks and similar effects (such as a frame around the whole page). It can have a maximum height equal to the page height. Specifying Report Properties Now that you have seen the individual parts that comprise a report, you will proceed to creating new one. Click on the "Edit page format" button in the properties view of the report, or right click on the report itself and select "Page Format" from the contextual menu, to see the page properties. In the dialog that will appear you can change the page dimensions, that probably are the report's most important properties. A list of standard measure is presented, The unit of measurement used by Jaspersoft Studio and JasperReport is the pixel. However, it is possible to specify report dimension using units of measurement that are more common, such as centimeters, millimeters, or inches. Note that because the dimensions management is based on pixels, some rough adjustments can take place when viewing the same data using different units of measurement. If you are interested in the argument check also the Measure Units Tutorial. In the following table there is a list of the standard measures and their dimensions in pixels. Page Type Dimensions in Pixels Letter 612x792 Note 540x720 Legal 612x1008 A0 2380x3368 A1 1684x3368 A2 1190x1684 A3 842x1190 A4 595x842 A5 421x595 A6 297x421 A7 210x297 A8 148x210 A9 105X148 A10 74X105 B0 2836x4008 B1 2004x2836 B2 1418x2004 B3 1002x1418 B4 709x1002 B5 501x709 ARCH_E 2592x3456 ARCH_D 1728x2593 ARCH_C 1296x1728 ARCH_B 864x1296 ARCH_A 648x864 FLSA 612x936 FLSE 612x936 HALFLETTER 396x612 11X17 792x1224 LEDGER 1224x792 By modifying width and height, it is possible to create a report of whatever size you like. The page orientations options, Landscape or Portrait, in reality are not meaningful, because the page dimension are characterized by width and height independent of the sheet orientation. However, this property can be used by certain report exporters.The page margin dimensions are set by means of the four options on the Page Margin tab. Columns As you have seen, a report is divided into horizontal sections: bands. The page, one or more of which make up a report, presents bands that are independent from the data (such as the title or the page footers) and other bands that are printed only if there are one or more data records to print (such as the group headers and the detail band). these last sections can be divided into vertical columns in order to take advantage of the available space on the page. In this context, the concept of a column can be easily confused with that of a field. In fact, a column does not concern the record fields, but it does concern the detail band. This means that if you have record with ten fields and you desire a table view, ten columns are not needed. However, the element will have to be placed correctly to have a table effect. Ten columns will result when long records lists (that are horizontally very narrow) are printed. Now we will see how to set up columns in a report with an example. Create a new report from File->New->Jasper Report. Choose as template "Blank A4" and as name "ColumnExample" and as data adapter we can use "Sample DB - Database JBDC Connection" with the following SQL query: select * from orders. Now some fields from the database will be discovered, for our purpose we need only the "SHIPNAME", so double click on it to add to the report fields and hit "Next", another time "Next" and "Finish". Now from the outline view drag the "SHIPNAME" field in the report in the detail band, resize the detail band and remove the unused band to obtain the result in the following image: Now go to the Preview tab to see the report compiled: By default the number of columns is 1, and its width is equal to the entire page, except the margins. The space between columns is zero by default. As you can see in the previous image most of the page is unused. If multiple columns are used, this report would look better. Set from the Page Format dialog the number of columns to two, compile the report and you will see the following result: In this case, the columns field is set to two to specify the number of columns you want. Jaspersoft Studio will automatically calculate the maximum column width according to the margins and to the page width. If you want to increase the space between the columns, just increase the value of "Space" field. In the following figure there is the same report this time with three columns separated by some blank space: The restricted area is used to mark every column after the first, to show that all the elements should be placed in the first column and in the others will be replicated automatically during the compilation process. Anyway you are not forced about this, if you want you can also put elements in the other columns, but in most of cases you need only the first. So you shouldn't use parts of the report as margins and columns after the first, which have to be considered as though they were a continuation of the first. Multiple columns are commonly used for prints of very long lists (for example a phone directory). Functionally, it is important to remember that when you have more than one column, the width of the detail band and of linked bands is reduced to the width of the columns. The sum of the margins, column widths, and space between columns has to be less or equal to the page width. If this condition is not met, the compilation could result in error. The example report with three columns should appear like in the following image Advanced Options From the properties tab of the report there are many other options for the report configuration, now we will see some of this properties. First of all select the report root note from the outline view, and in the properties tab you can see: Report Name: It is a logical name, independent form the source file's name, and is used only by the JasperReports library (e.g., to name the produced java file when a report is compiled); Title on a new page: This option specifies that the title band is to be printed on a new page, which forces a page break at the end of the title band. So in the first page only no other band than the title are printed, not event the page header or page footer. However this page is still counted in the total pages numeration; Summary on a new page: This option is similar to "Title on a new page" except that the summary band is printed as the last page. Now, if you neeed to print this band on a new page, the new page will only contain the summary band; Summary with page header and footer : This option specifies if the summary band is accompanied by the page header and the page footer; Floating column footer: This option allows to force the printing of the column footer band immediately after the last detail band (or group footer) and not at the end of the column. This option is used, for example, when you want to create tables using the report elements; When no data type: When an empty data is supplied as the print number (or the SQL associated to the report give back no records), an empty file is created (ora a strem of zero byte is given back). This default behavior can be modified by specifying what to do in the case of absence of data. The possible values for this field are: NoPages: This is the default value; the final result is an empty buffer; BlankPage: This gives back an empty page; AllSectionNoDetails: This gives back a page composed of all the bands except for the detail band.

Parameters in Jaspersoft are an important aspect of how report templates are built and they can greatly improve the user experience when it comes to generating the right report for the right user and with the right information. It is a concept of the JasperReports Library so it sits right in the heart of the reporting engine within all of the Jaspersoft solutions powered by JasperReports. Some Jaspersoft users know parameters as the object required to capture the input control values entered during the report execution so that it can be injected in the query and used as a filter accordingly. Report parameters can indeed be used that way and be injected in datasource query but it can do much more than that. They are a way to: personalize the information presented in the report output (i.e. add a custom value to be used as a title or to display the server logged-in user name in the report),customize how the information is presented in the report (i.e. a boolean parameter will allow a user to define whether a section of the report should be displayed or not),provide data to be used as a source of the report (it is possible for the JasperReports library to either use the result set generated by a query as well as a full JSON object passed through a parameter to the report as a data source),enforce data governance in the report by filtering the result set of the query specifically for the logged-in user at report execution (when deployed into JasperReports Server).However you use parameters, they represent the best communication channel between the report engine and the execution environment (which is your application). What is a parameter? A parameter is defined by a ‘name’ and a ‘class’, which is a Java class type like java.lang.String or java.lang.Integer. Any Java class is valid for the parameter ‘class’. For example a parameter of type java.sql.Connection may be used to define a subreport data connection, while a java.lang.Boolean parameter may be used to show or hide an element, a group of elements of the entire section of a report. A parameter can have a default value which is defined by means of the default expression property. This expression is evaluated by JasperReports solely when a value for the parameter has not been provided by the user at run time. For example, the default value may be used during reports preview in Jaspersoft Studio. How to create and manage parameters? To create a new parameter, use the outline view. add a parameter by right-clicking on the item "Parameters" in the Outline panel,choose "Create Parameter".in the property panel, configure:Its name;Its class;Whether it should be used for the prompt or not (which will require an input control at run time if true);Optionally add a description, a default value;Since version 7 it is also possible to set the parameter evaluation time to late or early which will define whether the parameter default value should respectively be calculated before or after running the report data query. To delete a parameter from the outline view right click on it and select "Delete". The parameters with a light gray name are created by the system and can not be deleted or edited. Built-in ParametersAll reports contain a set of built-in parameters, parameters available by default that contains some key run time information. Some of the most important ones are: REPORT_CONNECTION, which holds the JDBC connection used to run the SQL query of the report (if the report is filled using a JDBC connection)REPORT_DATA_SOURCE which contains, if available, the data source used to fill the reportREPORT_LOCALE which contains the Locale used to fill the reportSome built-in parameters are specific to a specific query language, for example when using the XML query language, the report will automatically include the parameter "XML_INPUT_STREAM" which defines the records to be used in filling the report. The built-in parameters can not be modified or deleted. Using Parameters in an SQL QueryParameters can be used in SQL queries to filter records in a where condition or to add/replace pieces of raw SQL or even to pass the entire SQL string to execute. In the first case, the parameters are used as standard SQL parameters, in this example we refer to the parameter value with the syntax $P{...}: SELECT * FROM ORDERS WHERE ORDER_ID = $P{my_order_id}In this example, my_order_id is a parameter that contains the ID of the order to read. This parameter can be passed to the report from the application that is running it or by the user running the report to select a specific order. Please note that the parameter value here is directly used as a SQL parameter. This means that the query will be executed using a prepared statement like: SELECT * FROM ORDERS WHERE ORDER_ID = ?and the value of the parameter my_order_id will then be passed to the statement. Now let's consider this second case which refers to a parameter using the $!P{...} syntax (note the extra exclamation mark): SELECT * FROM ORDERS ORDER BY $P!{my_order_field}In this case, my_order_field is not directly used as a SQL parameter. JasperReports will consider this parameter like a kind of placeholder that will be replaced with the text value of the parameter (which may even be a portion of the SQL statement such as "ORDERDATE DESC"). With the same logic, a query can be fully passed using a parameter. The query string would then look like $P!{my_query}The number of parameters in a query is arbitrary. When passing a value using the $P!{} syntax, the value of the parameter is taken as is, and the user is responsible for the correctness of the passed value (SQL escaping is not performed by JasperReports in this case). When using a parameter in a query, Jaspersoft Studio requires that a default value would be set for the parameters used in the query to that it can retrieve the fields automatically. Note: You should be extremely careful when using a parameter in a query through the $P!{} syntax. If the parameter is also used for prompt then that would allow the user to inject a query and thus potentially access some unauthorised data. It is then recommended to have one or more parameters requesting specific information through input controls and then use these values in the parameter default value which will generate the appropriate portion of SQL query that you’d like to inject in the query. Parameters PromptIf a parameter is set to be used as a prompt, then when executed the report will require to enter a value for these parameters. This is true with Jaspersoft Studio, JasperReports Server, or any other solutions which use the JasperReports Library. Here is a simple example. > Create a simple report with the template "Blank A4", name it "ParameterExample" > Use the data adapter "One Empty Record - Empty Rows". > In this report, create a parameter, and using the Properties panel, name it MESSAGE,set its type to String,and set it to be used as a prompt (the property "Is For Prompting" must be checked).> Drag the parameter from the outline view into the title band which will trigger Jaspersoft Studio to create a text field displaying the parameter value. > You should have something like the following image: Now, when executing the report, using the Preview button, for example, the parameter prompt dialog appears asking for a value for the MESSAGE parameter Set a value for the parameter (i.e. Hello World!) and hit the "Play" button. The message will be printed in the title band Jaspersoft Studio provides input dialogs for parameters of type String, Date, Time, Number, and Collection.

Overview Jaspersoft@reg; Studio can handle simple tables or crosstabs. Crosstabs are advanced tables where two or more fields are tabulated one against the other, and are heavily used in survey research. The main goal of this tutorial is to show how and when to use tables and crosstabs. Prerequisites In this tutorial we will use many features of Jaspersoft Studio and JasperReports, and many of these relevant features are explained in other tutorials. To follow this tutorial, we suggest you follow the following tutorials: Creating Charts and Datasets Element Attributes and Styles Create the Report The first thing to do is create a new report. In Jaspersoft Studio, select File > New > Jasper Report, and name the new report "TablesExample" . Use the Cherry template. For the data adapter use Sample DB - Database JDBC connection that came with Jaspersoft Studio. As SQL query to discover the fields use: select * from orders Now you have a list of the discovered fields, add them to the report in this order: ORDERDATE, ORDERID, SHIPNAME, SHIPADDRESS and SHIPCITY. Don't use groups, and complete the wizard. Now you have a report containing fields. You can test it switching to the Preview tab and compiling the report. If it compiles successfully, your result should be something like this: The Tables Now we can create our first table. First, decide what the table will display and where it will be located. For the location, we can choose the report summary, because it is printed at end of the report and can be used to easily view aggregated data. For this example we'll display in the table the number of shipments made in every year. If you don't see the Summary band in your report it is probably because its size is set to zero, so select the summary from the Outline view and change its height. Then drag a table element from the palette to the Summary band and a wizard appears. On the first step, choose whether the table will use an existing dataset or if you want to create a new one. For our purposes choose to create a new one and click Next. In the next step, name the dataset "TableDataset", select to create a new dataset from a connection or a database and click Next. Now you have to choose the data adapter. Use the built-in database Sample DB - Database JDBC Connection with the SQL query: select YEAR(SHIPPEDDATE),count(*) from orders group by YEAR(SHIPPEDDATE) This query selects the year from the shipment date and the number of records grouped also by the shipdate year. Doing this we have the number of record and the year of the shipments done in that year. Then you can click Next to see the discovered fields, here you can see two fields named C1 and C2, add them to the fields of the new dataset using the button >> or by double-clicking on each one. Then you can click Next and, since we don't need groups, click Next. In the next step you can select the connection to the data source. Leave the default option, Use the same connection used to fill the master report, and click Next. At this point we can define the fields in the columns of the table. Add them all and click Next. Finally, we can choose how the table is composed. We have six types of special cells: Table Header and Table Footer: printed at the start and at the end of the table. Column Header and Column Footer: printed at start and at the end of the table on every column, underabove the table header and footer. Group Header and Group Footer: printed at start and at the end of every group, visibles only if the table is using groups For what we need leave enable only the Column Header and Column Footer and hit Finish. Now that you have created the table, arrange the layout and change the labels C1 and C2 to display Year and Number of Shipments. To change the value of these labels, or of any other table cell, you must go in the cell editor by double-clicking on the table in the main report. Now you have a fully working table, that can be enhanced by updating the following: Since the table has no column footer defined, this is where we can put the total number of shipments. Some element has no shipment date, and for this the value null is shown. We can change this to"Undefined". The color of the column header and footer cells are very different from the ones of the main report. For the first point we need a support variable that sums all the values returned from the second field of the TableDataset query. First switch into the main report, expand the dataset TableDataset, right-click on Variables and select Create Variable. A variable called "variable_1" is created. Select it from the outline and set its fields as follows: Value Class Name: set it to java.lang.Integer, since we need a numeric value; Calculation: set it to sum since we want to sum single values; Expression: use the value $F{C2}, since we want to sum every single value of the field C2; Initial value Expression: new Integer(0), since the sum start from zero. Go in the table editor by double-clicking on the table and putting a static text from the Palette into the left column footer cell. Set the text to Total, then drag and drop variable_1 from the Outline view into the right cell of the footer, and resize them to fit the cells. Now we need to change the value null with the string undefined. In the table editor select the element with the value $F{C1}. As you can see this is a text field inside the cell that as has only an expression in the field. Edit the expression of this field by double-clicking it, and set its expression to: $F{C1} == null ? "Undefined" : $F{C1} This is a simple IF expression in a compact form (condition ? case then : case else) that checks if the field is null, in which case returns the value "Undefined", otherwise it leaves the value of the field. After that the only thing to do is change the color of the cell. When a table is created in Jaspersoft Studio the cell color is not set, but other styles are created. For example: Table_TH for the table headerfooter cells Table_CH for the column headerfooter cells Table_GH for the gourp headerfooter cells And these styles are created for every table, to avoid the name clashes a progressive number is placed at the end of the name of the style until an unique name is found. So select the style "Table_CH" and from the properties change the background color to a light gray. The final result should be something like the following image: Now switch to the Preview tab to see the result: The Crosstabs Crosstabs are little more complicated than tables, because its not easy to understand how the data is "crossed". Now that we have a table that shows the number of shipments made each year. With the crosstab we can have something more informative, like the shipment done year by year, but also divided by the destination countries. So the goal is to have the countries on the rows, the years on the columns and in every cell of the table the number of shipment done for a precise country in a precise year. First, remove the old table from the report, and drag and drop a Crosstab from the palette into the designer to launch the crosstab wizard. In the first step of the wizard, you can choose to create a new dataset for the crosstab or use an existing one. For our purposes, this time we can reuse the main dataset, so select Create a crosstab using an existing dataset, select [Main Dataset] and click "Next". Now you need to choose the fields that go on the columns. For our goal we need the shipped date, but we need only the year and we have two ways to get this: Create a new dataset or change the main dataset query to have another field that contains only the year, something like "select ORDERDATE, ORDERID, SHIPNAME, SHIPADDRESS, SHIPCITY, SHIPCOUNTRY, SHIPPEDDATE, YEAR(SHIPPEDDATE) as SHIPPEDYEAR from orders", that returns all the fields we need. Using the main dataset but change manually the column element expression in the crosstab, from something like "$F{SHIPPEDDATE}" to "YEAR($F{SHIPPEDDATE})". The first way is easier and cleaner, but since we already know how to create datasets and change the main dataset query, and we have never seen how to edit an already created crosstab, let's choose the second option. Returning to the wizard add the field SHIPPEDDATE by double-clicking it and click Next. Now we need to add the country to the rows, so in the next step select the field SHIPCOUNTRY and click Next. It's time to define the detail data. Normally, the detail is the result of an aggregation function like the count of orders by country by year, or the sum of freight for the same combination (country/year). We'll choose to print the number of orders placed by adding the field ORDERID with the Count calculation (default value) and then click Finish. Now that you have your crosstab created, change its size to fit the band and compile the report by switching to the Preview tab. Here you will see two problems: Since we have used a the shipped date on the columns now we have a column for every day where there was a shipment, instead of every year; Some elements don't have a shipped date, so there is a column for them with the label null, it would be better to have the string Undefined (in a similar way to what happens with tables). For the first problem go in the crosstab editor by doubleclicking on the its element. Here you see a dedicated outline view for this element, expand the element "Crosstab" and here you will see three very important elements: "Row Groups", "Column Groups" and "Measures". Here are placed the fields choosen for row, column and detail and to use this fields and are used elements of the type "RowGroup", "ColumnGroup" and "Measure" that are someway similar to variables since they use an expression that refer a field, they have a type and a calculation time. Now select the element SHIPPEDDATE1 and from its Properties tab set the values: Expression to "YEAR($V{SHIPPEDDATE1})" because we want only the year in the columns; Value Class Name to "java.lang.Integer" because the year is seen as an integer number, instead the date has a different type. Now you can compile and you will see that the crosstab has fewer columns, since all columns are now grouped by year. At this point we need to substitute the null value with the Undefined one, and to do this we must change the expression value of the header of the column. Select the header cell of the column that represents the shipment date and you can see that the element inside the cell is a text field. In the Properties tab you'll see the properties of this text field, move to the tab Text Field and change the value of the expression from $V{SHIPPEDDATE1} to $V{SHIPPEDDATE1} ==null ? "Undefined" : $V{SHIPPEDDATE1}. This adds an if expression in the valorization of the header to return a string when the value is null. Now you can compile your report, which should produce a result like the following: Now your table shows total number of shipment year by year, and state by state, so it is much more informative than a simple table. The "Total" Element As you can see, by default in every crosstab there is a "Total" row and a "Total" column at the edges of the table. This elements are present by default because in most of cases they are really useful, but you can remove them and change their position if needed. Suppose that you want to remove the "Total" column. In the Crosstab editor, from the Outline view, select the ColumnGroup SHIPPEDDATE1. In the Properties tab, there is a field called "Total Position" that can have any of the following values: None: no total column is shown; Start: The total column is shown as first column of the table; End: The total column is shown as last column of the table. These also apply to the total row. Generally, there is a total element for every group, and you can remove that element from its group properties. Additional Information About the Wizard Process Some operations described in this tutorial can be done during the wizard process. For example, you can extract the year from the SHIPPEDDATE and remove the total column. After we add the SHIPPEDDATE field to the columns set we can configure some other properties, as shown in the following image:

OverviewWe already saw that, in some cases, a subreport is needed to print particular information of a record (see the tutorial Subreports in Jaspersoft Studio). In general we can say that, in the case where we need to print a record, and a list of information related with that record, we have two options: subreports or lists. Suppose you have an XML data source where you have the tag "Person" with the details of a person (name, surname, address...) and one or more subtags "phone", where the content of every phone tag is a telephone number of that person. The goal is to print a person and all the telephone numbers associated with him or her. Datasource ReferenceTo follow this example, we suggest using the following data source: <addressbook> <lastupdate>2009-10-31</lastupdate> <person> <name>ETHAN</name> <phone type="mobile">+1 (415) 111-1111</phone> <phone type="home">+1 (415) 111-1112</phone> <phone type="work">+1 (415) 111-1113</phone> <phone type="fax">+1 (415) 111-1114</phone> </person> <person> <name>CALEB</name> <phone type="mobile">+1 (415) 222-2222</phone> <phone type="home">+1 (415) 222-2223</phone> </person> <person> <name>WILLIAM</name> <phone type="work">+1 (415) 333-3333</phone> <phone type="mobile">+1 (415) 333-3334</phone> </person></addressbook>[/code]You can copy and paste this text into a text file and save it as "PhoneList.xml" or you can download it directly from phonelist.xml. Create the ReportStart a new report by selecting File > New > Jasper Report, use the template Tree and give it the name PhoneBook. When you are in the data source selection step of the wizard, click the button New, select XML document and click Next. Now you have to configure an XML data adapter. Use these parameters: And click Finish. You then return to the step in the wizard where you have to select the data adapter. The new adapter should be selected. Next, you have to provide a XPath query to locate the fields. Since we want to print the Person, double-click on the item person to generate to following query: /addressbook/person And click Next. In the next step, the fields are listed, but this time it is a little bit different from the previous tutorials: the field name is present but you can have two or four phone fields. The number of fields depends on the record selected in the previous step, which was used to discover the fields. The first record has four phone numbers and the other records only two. The point is that we can't directly add the phone fields to the report, becasue we don't know how many there are. This is why we need a sub-dataset and a list. For now, add only the field name to the report by double-clicking on the field name and clicking Next. In the next step, click Next and then Finish. At this point you have a report that prints only the names of the people stored in the XML. Adding the Phone NumbersIn order to display the list of numbers, we need to create a sub-dataset starting from the person node. The main dataset works on the person nodes, while the sub-dataset processes all the phone tags of a specific person node. The first step is to create the new list. So drag it from the Palette into the Detail band to launch the wizard. Here you can create a new dataset or use an existing one. In our case, since we don't have any other datasets to use, we must select the first option and then click Next. Next, provide a name for the new dataset, for example PhonesDataset. Select the option Create an empty dataset, and click Next. The idea is to use an empty dataset that is filled every time with the phone numbers of the currently printed record in the master report (we can do this using an expression). In the next step, leave the default option selected, Use the same connection to fill the master report and click Finish. Now you have created your list and its dataset, and you can see this in the Outline view. The first thing to do now is define how the dataset is filled. Select the list element from the Outline view: in the Property tab, go to the tab Dataset, select the option Use a JRDatasource expression, and then insert this expression: $P{REPORT_DATA_SOURCE}.subDataSource("/person/phone") ---->It will result errors while compiling. One has to type cast explicitely as follow: ((net.sf.jasperreports.engine.data.JRXmlDataSource)$P{REPORT_DATA_SOURCE}).subDataSource("/person/phone") This line of code is very important. The syntax $P{} is used to reference a parameter object. In this case it is, REPORT_DATA_SOURCE, which is a built-in parameter that contains the data source used to fill the main dataset. The data source in this case is an instance of JRXmlDatasource which provides two methods to work with sub-datasets: subDataSource() and dataSource(). Both are arguments in an xpath expression. In our case, the subDataSource method is what we need to explore the XML tree under the person node. In particular, the data source will use all the phone nodes that are children of the person node as the record node. Now we need to add the fields to the dataset created with the list. Expanding "PhonesDataset", you can see that the item "Fields" hasn't children. This is because, when we created the list, we have used an empty dataset, so it was not possible discover any field. For this reason we must add them manually. Right-click on the item "Fields" of "PhonesDataset" and select "Create Field". Repeat this twice. The PhonesDataset now has two fields, "Field_1" and "Field_2". But, we must define how these fields are valorized and insert them in the list. So double click on the list element in the designer and a new tab will be opened. First, we will set the valorization of the fields. From the outline view, expand "PhoneDataset" and its child "Fields" and you can see the two fields created before. Select them, one at a time, and you can see that, in the property tab, there is a field "Description" where we can put an XPath expression to extract the tag values: For the "Field_1" use as Description "@type", to extract the value of the attribute "type" of the current node.For the "Filed_2" use as Description "child::text()", to extract the text value of the current node. Now the new fields are ready to be used. Drag them from the outline into the designer. A window appears asking if you want use a calculation function. Since we don't need to, select Nothing and click Finish. Arrange the layout so it is similar to the following image, then go back to the main report. Now, arrange the list element and the detail band as in the following image: Now switch to the Preview tab to compile the report. You should see this result: note: the dataset of the list should be "((net.sf.jasperreports.engine.data.JRXmlDataSource)$P{REPORT_DATA_SOURCE}).subDataSource("/person/phone")", other than "$P{REPORT_DATA_SOURCE}.subDataSource("/person/phone")". notice the ")" before ".subDataSource..."

Overview An XML data source uses an XML file to provide the data printed to reports. The XML structure is not flat like a table. There are not rows and columns. It's more like a tree where we can have several levels of data. All data starts from a root node that can have any number of children or branches. A child can be a value or it can be another node with children. For this reason it is necessary to use an XPath query to identify which nodes of the XML document must be considered as records. The following XML is simple enough to easily explain how to do it: <addressbook> <person> <name>ETHAN</name> <phone>+1 (415) 111-1111</phone> </person> <person> <name>CALEB</name> <phone>+1 (415) 222-2222</phone> </person> <person> <name>WILLIAM</name> <phone>+1 (415) 333-3333</phone> </person></addressbook>[/code] Each record that we want to print can be identified with the XML node labeled "person". The selection of these specific XML tags is done with an XPath query like this: /addressbook/person XPath is a powerful query language to select data in an XML file. In this case, the expression selects all the nodes of type "person" that are children of "addressbook". The result from the data source is a set of three records (since the occurrences of the tag person, child of addressbook, are three). The goal is to write a report in Jaspersoft Studio with a list of all the persons in the address book, showing each person's name and phone number. Create the Example XML To use the above XML from this tutorial, open your favorite text editor and create a new file. Then copy and paste it into this file: Save the file with the name "ContactList.xml". You can also download this file from contactname.xml. Creation of the Report Now open Jaspersoft Studio AND begin creating a new report by selecting File > New > Jasper Report. Select the "Silhouette" template. As file name use "ContactXMLReport". When asked to choose the data adapter, click New, and, in the window that appears, select XML document and click Next. In the next window, insert the name of the new data adapter, XMLAdapter, then click the Browse button. Select the file ContactList.xml, then select the option: Use the report Xpath expression when filling the report to use an expression directlly inside the report. The difference between these two options is that the first uses an expression defined in the report, so every report can use its own expression to retrive the data. The second one defines an expression in the data adapter, so every report that uses the data adapter will also use its expression. When configuring an XML data source it is possible to specify in which mode the data source must operate or to use, and a Date and Number pattern that can be used to convert a text value in a more appropriate object (like a date or a number). Since we don't need this option simply click Finish. Back in the Report Creation wizard, the data adapter you just created should be selected. Insert the XPath query, like we did with the SQL query in other tutorials. In this case, JasperReports executes the XPath query to select the nodes from the XML document provided using the XML data source. Any data adapter can provide an editor to interact with the data source (the XML in this case). For example, for a JBDC data adapter we insert the SQL query, and from this adapter Jaspersoft Studio locates the necessary fields. With the XML, you can provide an XPath query, like /addressbook/person, but you can also compose it using a visual editor that shows the tree structure of the the XML. By double clicking on a node the XPath query will be automatically generated. The advantage of keeping the XPath query inside the report is that we can use parameters to make the query dynamic. Note that the query "/addressbook/person" returns all the people under the tag "addressbook", and the fields that are the child nodes of those people, such as name and phone. Click Next and notice where the fields "name" and "phone" are located. Add these to the report by clicking >> and then click Next. We don't need groups, so on the next step click Next, then click Finish. The report is created, and if you switch to Preview mode you should see this result: The Background Band The background band is a little different from other bands. It can have a maximum height equal to the page height and the elements appear behind the other bands. For example, if you put an element at the top of the background band, it is placed at the start of the page (keeping the margins in consideration) and is under any other elements in the same position. This band was introduced to provide an easy way to include watermarks or similar effects. Differences with iReport Jaspersoft Studio allows a friendlier way to define fields. In iReport, when you select the dataset you can't use an XPath query to locate fields; you first need to create the report, go in to the query designer, and only then you can write the XPath query and eventually add fields. At the end of the wizard, Jaspersoft Studio places the located fields inside the report. Because of this, Jaspersoft Studio is faster - at end of the wizard you can have a report already configured, with the fields placed and ready to be compiled, whereas with iReport you need to take additional steps before you can compile. Using a Remote XML Jaspersoft Studio provides a data adapter for the remote XML, like the RSS Feed. This means that it is possible to generate a report using not only a local XML but a remote XML provided from some external service. For this example, we will use the RSS Feed of the BBC News. Begin creating a new report by selecting File> New > Jasper Report, and select the Tree template. Use the file name "BBCReport". When asked for a data adapter, click New.In the subsequent window, select the option XML document (remote) and click Next. Call the new data adapter "BBCAdapter" and use the following values: XML URL: http://feeds.bbci.co.uk/news/rss.xml?edition=int# Date pattern: EEE, dd MMM yyyy HH:mm:ss z Then click Finish. You have now created a data adapter for an XML on the web identified by an URL. Now you have the ability to insert an XPath query as seen with the local XML. The RSS of the BBC contains all the the news into the tag item, inside the tag Channel. Expanding the Channel tag and double-clicking on Item generates the following XPath query: /rss/channel/item. Next, click Finish to retrieve the fields. Remember that double-clicking on an element Item dosen't select that precise element, but all the elements with the tag "Item" located on the same level as the selected element. From the field list double-click to select the title, description and pubDate, then click Next. Again, we don't need groups so click Next and then Finish. Now you have a report with the fields already placed, but because the description will contain more text, and is not in a good position. Enlarge the band Detail and move the description under the title, then enlarge the field description to fill the band. You should end up with something like this: Switch to the Preview tab to compile the report and you should see a result like this: So we have filled the report with a remote XML, in this case an RSS Feed. The Parameters If you open the Dataset & Query dialog (select the report from the Outline view, then from the Properties tab and click the button Edit query, filter and sort options) you can see that, as query language, you are using XPath2. The XPath2 query executer is able to download the XML file from a remote url that we set when we defined the data source, but the url can also be specified using the parameters. Optionally, GET and POST parameters can be specified as parameters for the report from the Parameters tab inside the Dataset & Query dialog. When the report is executed inside an application, the URL can be set dynamically with a parameter XML_URL. Other parameters that can be set include: XML_USERNAME and XML_PASSWORD for http authentication and XML_DATE_PATTERN and XML_NUMBER_PATTERN to set the pattern that converts dates and numbers from text. POST and GET parameters can be specified creating parameters with the prefix XML_POST_ and XML_GET_. For example, to pass a GET parameter of name id, the parameter must be called XML_GET_id. This approach is very flexible and can be used to get data from a web application like a PHP script that can create the XML data based on a set on input parameters passed from the report. contactname.xml

Overview The tutorial "Creating Charts and Subreports with Jaspersoft Studio" provided a brief introduction to the subreport element, which allows you to insert a report inside another report. This powerful too allows you to create complex layouts within a single document, using multiple data sources and reports. In this tutorial we want to create an address book lisitng each person in a company, including their names, phone numbers, and email addresses, as shown in the following image: To do this, we need a main report containing two subreports. Creation of the Data Adapter For this task, we'll need a data source more complex than the sampleDB. For this reason, we need to install JasperReports Server which contains some useful sample databases. To determine which version of Jaspersoft Server you should use with your operating system, check the tutorial Getting Started with Jaspersoft Studio, and look in the section "Software Requirements and Installation". After you have installed Jaspersoft Studio, use it to create a new Jasper Report using the template "Flower Gray" with the report name "ContactsList". When asked to select a data adapter, click New, then select Database JDBC Connection and click Next. When asked to choose a name for your new data adapter, use "ContactsDataset" and configure it with this data: JBDC Driver: org.postgresql.Driver; JDBC URL: jdbc:postgresql://localhost:5432/sugarcrm; Username : postgres Password: postgres After this, use the button "Test" to check if the connection works, and in that case hit "Finish". Creation of the Main Report Now you should be back in the Report Creation wizard, at the step where you are asked to select the data adapter. The new data adapter should be selected automatically; if it isn't, select Contacts Adapter. In the Insert an SQL query text entry box, enter select id, name, shipping_address_city from accounts. This query returns the name of a company and the city where the store is located. Then click Next. As the next step, you are asked to define groups. Because we don't need them for this tutorial, click >> to add all the fields to the report and click Next. Click Next again, then Finish. The report is created. It should be similar to the one in the image below: Creation of the First Subreport The next step is to create a subreport to display email addresses. Start a new report by selecting File > New > Jasper Report. Choose the template Blank A4, save it in the same directory of the master report, and call it "EmailReport.jrxml". When asked to choose the data adapter, select the ContactsAdapter created earlier, and use the following query: select contacts.email1 from contacts, accounts_contacts where accounts_contacts.account_id = 'placeholder' and accounts_contacts.contact_id=contacts.id In this query, a static string "placeholder" is used. As suggested by the name, this is not a real value but a placeholder that changes with a parameter described in the next steps. After entering the query, click Next. The query locates one field. Add that field to the report by clicking >>, then click Next. Skip the next step by clicking Next, then click Finish to create the report. In the Outline view, select the report root node. Then, in the Properties tab, click Edit Page Format. In the Page Format window, reduce the width of the page to 270 pixels and remove the margins, since they are not useful in a subreport, then click OK. Because we used a static value as a placeholder, this report does not list any email addresses. We need to retrieve just information for the current person in the master list. To filter the email addresses, we need to use a parameter. In the Outline view, select the report root node. Then in the Property tab, Click Edit query, filter and sort options. In the Dataset & Query Dialog window, select the Parameters tab and click the Add button. A new parameter is added with the name "Parameter_1". Change this name to "ACCOUNT_ID", and make sure the type String is applied. Next, replace the string placeholder' with the value $P{ACCOUNT_ID}. This query is influenced by a parameter that comes from the main report. Click Ok. The syntax $P{ACCOUNT_ID} allows the use of a parameter inside a query, in this case to filter the results using a "where" condition. The next step is to drag the band column header into the report. Add a Static Text element from the palette and change it to "eMail address". Drag the field email1 from the Outline view into the Detail band, then delete the unused bands (title, page header, column footer, page footer, summary) and resize the Column Header and Detail bands. You should have a layout like the one in the image below: Save the report and, if you like, you can run it to see the result. Creation of the Second Subreport The procedure to create the second subreport it is almost identical to the first one. Start a new report from File > New > Jasper Report. Choose Blank A4 for the template, save it in the same directory as the master, and call it PhoneReport.jrxml. Select "ContactsAdapter" as the data adapter, and enter the following query: select phone_work from contacts, accounts_contacts where accounts_contacts.account_id = 'placeholder' and accounts_contacts.contact_id=contacts.id Add the discovered field to the report, don't define groups and complete the wizard. When the report is created, click Edit Page Format, remove the margins, and set the width to 270 pixels. In the Edit query, filter and sort expression dialog, switch to the tab parameters and add a new parameter "ACCOUNT_ID". Use this to replace the placeholder in the query, as in the image below: Next, add a Static Text element containing the text "Telephone" in the Column Header band, and add the field "phone_work" to the Detail band. Delete the unused bands and resize these two elements and their bands until you get a report similar to the one shown below: Now, save the report and, if you want, compile it to see how it looks. Now it's time to finish the work on the main report. Completing the Main Report The two subreports have been created. Now, we need to include them in the main report. Open the report ContactList and resize the Detail band so it is large enough to include the subreports - start with 50 pixels. Next, place a subreport element from the Palette into the Detail band to launch the wizard. Choose Select an existing report (selected by default) and click the Select a report file button. A window listing all created reports appears. Select EmailReport.jrxml, click Ok, then click Next. In the next step, choose the option Use the same connection used to fill the master report (which should be selected by defaut). This ensures the database connection is passed to the subreport, so it can execute its SQL query, then click Next. Now we can set an expression for the parameter exposed by the subreport. Click Add to add a new parameter. Double-click to select on the new parameter's name, and enter "ACCOUNT_ID". Select the value field, and and click the button with three dots (the button is visible only if the value field is selected) to open the Expression Editor. In the Expression Editor, double-click to select ID from Fields, then click Finish. When you return to the parameters dialog it should look similar to the one in the image below: Now click Finish. The first subreport is added to the main report. From the Palette drag another subreport and repeat the same procedure using as report file PhoneReport.jrxml, and giving all the other fields the same values. At this point you should have the two subreports into the main report. Resize them to and resize the detail to obtain this result: Go in the Preview tab to compile. If everything is correct, you should see a result similar to the one below. (Don't worry if the emails are all the same, this is still correct - they are the same in the database we used.):

Overview You should complete the tutorial "Creating Charts and Subreports with Jaspersoft Studio" before beginning this tutorial, as it introduces the Datasets and uses them in the creation of a chart. The goal of this tutorial is to create a report with a chart in its summary, with some grouped data. Although this can be done by using a subreport, in this tutorial we will use only one report and a "dataset" element. Preliminary Steps In this tutorial, we will use the report created during the tutorial "Designing a Report with Jaspersoft Studio" which provides us a report including all the records in the table "orders", with every record including the field order id, shipment name, shipment address, shipment city, and shipment region. At the bottom of the records, in the Summary band, we want to include a chart that shows the number of shipments for every city. If you haven't followed the tutorial "Creating Charts and Subreports with Jaspersoft Studio" you need to resize the Summary band with the following procedure. The Summary band is already present in the report used as example, but it could have an height of 0. It is, however, visible from the outline view. Select the Summary band from the Outline view and change its height in the property tab to 400 pixels, as shown in the following image: The Dataset Every report has a main dataset defined during its creation. But sometimes we need fields that are not returned by a query from the main dataset, or the fields needed may be in a different data source. In the tutorial "Creating Charts and Subreports with Jaspersoft Studio" we saw a workaround where we define more reports using only the main dataset of each report, and including them in another report using the element "Subreport". Another way to do this is using a single report and the element "Dataset". The dataset element allows you to define many datasets inside the report, each one with its own fields and data source. Every dataset is independent from the others, so its fields are separated from the ones of the main dataset, and also from the ones of the other datasets To create a dataset, right-click on the report root node in the outline view and choose Create Dataset: A new wizard opens. In the first step, enter a name for the new dataset and if it uses a connection to a data source or it is simply empty. Since we want to read data from the database, select the first option and use as name "GroupData", as in the image below, then click Next. Next, we have to select the data adapters for the new dataset, and since we are using the same database as the main report , we will select Sample DB - Database JBDC Connection. We must also provide a query to retrieve the fields. Enter the query "select count(*), SHIPCITY from orders group by SHIPCITY". It returns the records grouped by the shipment city. This ensures that every record read from the database that matches this query will contain two fields: the number of element for a city and the name of the city. After that we can click Next. At this point, the fields discovered using the provided query are displayed, and we can choose which we want to add to the report. Since we need them all click the Add All button and then Next, as in the following image: On the next screen in the wizard, we can define groups. For this task, we don't need them so click the Finish button. The dataset is created and is visible from the Outline view. If you explore the element you can see that it has its own fields, variables and groups. We can now drag and drop the chart from the palette into the Summary section: After the chart is placed the, creation wizard appears. On the first screen, select a Pie Chart (to have something different from the previous tutorial), and click Next. On the next screen, find the field named Dataset, normally with the value [MainDataset]. You must change this value to GroupData, so the chart will use the new dataset, as in the image below: Now you have to configure the series of the chart. Click the button with three dots on the right of the series combo to open a new dialog: In this dialog you can define the series of the chart with an expression. Delete the default item by selecting it and clicking Delete, then press the Add button. The expression editor opens. Select, Fields and double-click on the item SHIPCITY. Finally, click "Finish" to close the expression editor: Now you will return to the dialog of the series. Click Ok to go to the chart configuration. Configure it as shown in the following image: When the chart configuration is finished, click the Finish to complete the wizard. The only thing left to do is resize the chart to take up all available space in its band. Right-click on the chart, select Size to Container, and then Fit Both. The chart fills the Summary band. Next, go in the Preview tab to compile the report, then go to the last page to see the chart:

Overview JasperReports supports a large number of built-in charts created using the popular open source library JFreeChart. Chart types include Pie, Bar, Stacked Bar, Line, Area, Bubble, Gantt, Thermometer and Meter. In this tutorial we will learn how to add a multi-series chart to a report. This tutorial uses the same example explained in Designing a Report with Jaspersoft Studio. We suggest you complete that tutorial before beginning this one. The goal is to have the same report described in the tutorial Designing a Report with Jaspersoft Studio, with a bar chart showing the number of shipments for every city. Placing the Graph The report created in the earlier tutorial is composed of multiple bands, each with different print times. For example, the detail band is printed for every record read from the data source, the page header and footer are printed at the start and at the end of every page and so on. For this tutorial we will use the Summary band that is printed at the end of the report. Note that in this report the Summary band is not visible from the designer because its height is set to 0. It is, however, visible from the outline view, so select it from there and change its height in the property tab to 400 pixels, as shown in the following image: The Subreport A subreport is an element that includes a report inside another report. The idea in this tutorial is to have a subreport containing just the graph, and a main report that includes the subreport in the summary section. For the purposes of this tutorial, we want to use two reports because in the main report we need a list of records without any aggregation so we had used the query "select * from orders" and from all the fields read we had selected the order id, the shipment name, shipment address, shipment city, shipment region. But for the graph in the subreport we don't need a list of records, just a group of them. In other words, we need the records grouped by the shipment city. For this reason we need two queries, one that returns all the records (for the main report) and one for the group (for the subreport). Because a report can have only one main query, we need to use another report for the additional query. Note that there are other ways to use more than a query on the report, but for now we choose this one to introduce the concept of subreport. Now drag the subreport element from the palette into the summary section and a wizard will appear: In the first step of the wizard we have three choices: Create a new report as subreport. Use an existing report as subreport. Put an empty report as subreport, as a placeholder. Since we are doing this from scratch select the first option, Create a new report, and click Next. Now we will seen a wizard almost identical to the one seen when we created the first report. This time, since we need only a blank paper with a graph select BlankA4 and hit Next. Now we need to choose the location and the filename of the new report, put it in the standard location MyReports and as name use "GraphReport" and click Next. Now we have to select the data adapter. Since we need to use the same data source for both reports, select the same data adapter as used in the main report. We must also provide the query to retrive the fields, so enter the query that returns the records grouped by the shipment city. Every record read from the database with this query contains two fields: the number of elements for a city and the name of the city. After that we can click Next. At this point we can see the fields included by the second query. Click the add all button or double-click on each field until they are in the right list. After that click Next. The following step in the wizard is to create groups into the report, but this is unnecessary for our goal. Click Next again. Now we have to select the connection to the database. Since we are using the same database as in the main report we can select the first option and click Next. In the following step in the wizard, we could create some parameters that can be passed from the main report to the subreport, but we don't need them so click the button Finish. Now we have a new report with all his bands, but we need only one of them. In fact, we need only a band for the graph, and the band must be printed only once, so the detail band is excluded. We can choose the Title or Summary band. If we decide to choose Title, we need to remove the other bands because otherwise they will take up space unnecessarily. So for each band except Title right-click on its element in the outline view and choose Delete. The name of a deleted band appears in light gray text in the outline view, so at the end of the process the only band with a black name must be Title. The Chart Now we can place the chart. Drag its element from the palette into the Title band to open the wizard, select the bar chart and click Next. In the next step you can configure the series of the chart, as shown in the following image: Then click Finish to create the chart. Since we need space, resize the Title band with an height of 350 pixels. Right-click on the chart, select Size to Container and then Fill Both. The chart will take all the space in the band. Now we can switch to the Preview tab and if it is all correct, save this subreport and switch to the main report as shown in the following image: Now the only thing to do is to resize the subreport element to fill the Summary band, and compile the report. On the last page you will get a result like this: More on Complex Reporting Subreports in Jaspersoft Studio

Overview In addition to generating and viewing reports, Jaspersoft Studio allows you to export reports into many formats, including PDF, XLS, HTML and others. In this tutorial we will go over the steps necessary to export a generated report using Jaspersoft Studio. We'll use the report generated during the tutorial Designing a Report with Jaspersoft Studio. Compiling the Report When you switch on the Preview tab in the designer bottom bar, Jaspersoft Studio performs a set of operations to create the final report. The first operation compiles the JRXML source file in a Jasper file. This first step can fail if the elements are not correctly positioned (for example, if an element is placed outside of a band), or if an expression in the report has errors and cannot be compiled. If the compilation runs successfully, the produced Jasper file is loaded and filled using the active connection or data source. This second operation can also lead to errors. This can happen if the referenced database is not active, an invalid query has been provided, or a null field produced an error in an expression during the filling process. If all operations complete without error, the report is displayed in the integrated viewer. Errors are shown in the Report State window, after clicking the Errors button, as shown in the following image: If errors occur during the compilation, the tab changes from Preview to Design. Preview and Exporting If the compilation completes and there are no errors in the file, the preview is shown. From there you can browse the generated report and change its visualization, change the data source or export the report. Note that after changing the data source the report is recompiled automatically. You can also change the preview format and save the report in different formats. In the image you can see that there is a green Play button. Clicking this button forces the report to be regenerated; it should be used when a subreport changes, or when you want to execute the report with different input parameters. When you set a preview format, the report is automatically regenerated in the chosen format, and the corresponding viewer application is opened - a PDF viewer or OpenOffice, for example. See Also: Introduction to Jaspersoft Studio Jaspersoft Studio Features Getting Started with Jaspersoft Studio Designing a Report with Jaspersoft Studio Jaspersoft Studio Tutorials Archive

Overview In this tutorial, we cover the basics of how to design a report. The report creation process has three main steps: Creating a data source or a database connection used to fill the report. Designing the report, including the layout of its elements and parameters to represent the data. Runing the report, which includes compiling the JRXML source file in a Jasper file and filling in the data for export or onscreen display. To keep things simple, this tutorial uses a sample database included in the installation of Jaspersoft Studio. The data to print is retrieved using an SQL query embedded in the report. Creation of the New Report The first thing to do is create a new report. To do this, open the File menu, select New, and then click Jasper Report. A new window appears, as shown in the following figure: Here you can select a template. A template defines the initial graphical layout of a report. From this dialog, in just a few clicks, you can create a very simple blank layout, or a much more complex one, with image, text, number of pages and so on. As an example, let's select a template with some elements in it. From the window displayed in the figure above, select Coffee and click Next. In the next step, select the folder in the workspace where you want to put the report, and name the new report. You can use the default folder MyReports, name the report use Example1, as shown in the following figure, then click Next. If you want to create a new project folder for the report, go to the chapter Create a Project Folder, at the end of this tutorial. Now for the most complex part of this tutorial: the selection of a data source. The data source is the location from which the data is taken to fill the report. In this step, you must select a data adapter, which is essentially a connection to a data source. Here you have three options: Selecting the data adapter "One Empty Record - Empty rows": This is default data adapter used to create a report without any data. It can be used to define the layout of the report before connecting it to a data source. In fact, a data source can be provided at a later time, after the creation of the report. Selecting the data adapter "Sample DB - Database JBDC Connection": This is a an SQL database used as an example, provided with the Jaspersoft Studio installation, for use in this tutorial. Creating a new data adapter with the "New" button: Jaspersoft Studio supports a wide variety of data sources. Using the "New" button allows you to browse and connect to an existing data source. Since this is a complex functionality, we'll address it in another tutorial. For this example, we will use the Sample DB, but this is not sufficent to create the report. A SQL database can contain many tables, with many fields, so we must specify which of these fields we will use in the report. To do this we must provide an SQL query that selects all the fields we want include in the report. To keep this tutorial simple, we will select all the fields from the table named "orders". Write the query as shown in the image below and click Next. Using this query ensures the database will be explored and all the fields found can be added to the report. In the next step of the wizard there are two lists. On the left there are all the discovered fields, and on the right the ones that will be added to the report. At first the right list is empty, but we can move one or more elements from the left list to the right one using the buttons between the two lists or by double clicking on the field. An example is shown in the figure below: After selecting the fields click Next to proceed with the wizard. In the next window you can group fields. Grouping is a function that, for now, we will not use, so click Next. The wizard is now complete. The only thing to do is click Finish. Jaspersoft Studio now builds the report layout with the selected fields already included, as shown in the following figure: Here, we can delete a field on the report by right-clicking on it and selecting delete, or adding a field from the Outline view (the tab on the bottom-left of Jaspersoft Studio). To include the value of a field in the report, drag it from the outline view to the design view. For example, drag a field into the detail band, a section of the report that is printed for each record/row in the query results. The title and the summary bands are printed just once in each report, while the page header and footer are printed once at the top and bottom of each page, respectively. In the figure below, see the example where the field SHIPREGION was removed from the report and in its place the file SHIPCOUNTRY is added. When the field object is dragged inside the detail band, Jaspersoft Studio creates a text field element and sets the text field expression for that element to $F{SHIPNAME}. This is a simple expression to print the value of the field with the name SHIPNAME (the syntax $F{}). Repeat the same operation for other fields and format the text fields element by stretching, dragging and aligning them. It is important that the text fields are all placed inside the detail band. To add other elements (such lines or labels), drag them from the palette shown in the following figure into the designer view, then resize and arrange them as desired: In this case, we add a label in the title band for the report title, we add column labels using label elements placed in the column header band, and we place a thin line just under the text fields in the detail band. Change the height of band by dragging its bottom edge. A shortcut to reduce the height of the band is to double-click on its bottom edge, which aligns it with the bottom edge of its lowest element. You can also set properties such as the height of the band in the property sheet under the palette. The property sheet lets you view and edit the properties of the currently selected element in the designer. Click on an element in the designer or in the report inspector to select it and view its properties. For bands, you can also click in an unused part of the band. To preview the report, switch to the preview mode by clicking the Preview tab at the bottom of the designer window. Then click the green arrow. The preview compiles the report in the background and fills it with data retrieved by the query through the JDBC connection. As shown in the following figure, the detail band repeats for every row in the query results, creating a simple table report: Add more Fields to the Report You may discover that you need to add more fields from the data source after the report was created. You can add fields to an existing report without creating an entirely new report. To add fields to an already created report, select the main node of the report from the outline view (in this example is named "coffee"). From the properties tab press the button Edit query, filter and sort option, as shown in the following figure: In the dialog that appears, you can specify a new query and by clicking the button Read Fields and then "OK". All the fields discovered are added as new fields in the report. Note that if the new query discovers fewer fields than the ones used in the existing report, the fields that are not included the new query will be removed from the report. An example can be seen in the following figure: As you can see, we selected only the fields ORDERID and CUSTOMERID, so any field previously added to the report that is not included in these two will be removed. This dialog is very powerful - from here, you can change the data source, add, remove and reorder the fields discovered by the new query. Create a Project Folder From JasperSoft Studio, open the menu File, select New and then Others.... In the dialog that will appear type "Jasper" in the Wizards bar, this will filter all the actions showing only the ones related to JasperSoft Studio, and from this filtered list select "JasperReports Project". Then hit Next. At this point you need only to insert the name of the folder and hit Finish. See Also: Introduction to Jaspersoft Studio Jaspersoft Studio Features Getting Started with Jaspersoft Studio Exporting reports with Jaspersoft Studio Jaspersoft Studio Tutorials Archive

Overview In this tutorial we will see what are the requirements to use Jaspersoft Studio. Requirements to Run Jaspersoft Studio Jaspersoft Studio needs a 64bit or 32bit processor and at least 500MB of Hard Disk space. The amount of the RAM is really dependent from the complexity of the reports, a value of 1GB dedicated to Jaspersoft Studio is recommended, since in your system there are many other things that require RAM it's suggested a total value of 2GB. Software Requirements and Installation As any other Java project Jaspersoft Studio require the Java Runtime Environment (JRE), but to compile the report scriptlets a full distribution of Java is required. You need to download the Java Development Kit (JDK), supported versions of Java could be found in our Platform Support Guide, please check this guide for specific version details. At the moment Jaspersoft Studio support the most common Operating systems, such as: Windows 10 and above with 64 bit; Linux with 64 bit; Debian Linux 8, 9, 10; Cent OS 6.x, 7.x MacOS 11.x, 12.x at 64 bit. The download of Jaspersoft Studio starts from HERE (community editions), a page with listed all the release of Jaspersoft Studio will appear, click the one on the top of the list (the last version) and a grid with many links will be shown. The Eclipse RCP package is available in the following formats for community and commercial versions. Commercial Versions: • TIB_js-jss_x.x.x_linux_x86_64.tgz • TIB_js-jss_x.x.x_macosx_x86_64.dmg • TIB_js-jss_x.x.x_sources.zip • TIB_js-jss_x.x.x_windows_x86_64.exe • TIB_js-jss_x.x.x_windows_x86_64.zip x.x.x represents the version number of Jaspersoft Studio. For community only, unsupported versions for the Eclipse RCP are available as a convenience for users who are in a restricted environment and can't download or install an .exe. file: • TIB_js-studiocomm_x.x.x_linux_amd64.deb • TIB_js-studiocomm_x.x.x_linux_x86_64.tgz • TIB_js-studiocomm_x.x.x_macosx_x86_64.dmg • TIB_js-studiocomm_x.x.x_windows_x86_64.exe • TIB_js-studiocomm_x.x.x_windows_x86_64.zip The community version is also available as an unsupported Eclipse plug-in, called the Jaspersoft Studio plugin. You can install it from the Eclipse Marketplace or download using the Eclipse Update Manager. See the following article on the community website for more information about working with the Jaspersoft Studio plugin. Contributing to Jaspersoft® Studio and building from sources Be sure to download and install the correct version of Java and Jaspersoft Studio for your Operating system. In most of cases the installation requires only the download of the correct file and then double-clicking on in, this will show the installation wizard and here you can follow the on screen instructions. Check the architecture of the Operating System If you are unsure on "how many" are the bits of your system follow this steps: Windows Go in the Control Panel, then click on System & Security and then on System, then in the presented Window check System Type. It will have information such as this: 64-bit operating system, x64-based processor. Linux Open the terminal and type uname -a , then you will see a response like this: x86_64 means a 64bit Operating System. MacOS Open the terminal, if you don't know how to do it open the Launchpad, type "Terminal" in the search bar and select the first result. Once the terminal is opend type uname -a , and press enter. A message like this will appear: x86_64 means a 64bit Operating System. At this time the 64 bit version it is the only provided for MacOS. Accessing the Source Code The last version of the source code is available from THIS page by clicking "Browse Source Code", in this way you will access directly the SVN repository (read only mode) where the most up-to-date version is available. You can download and compile this source code, but since it is a work in progress it can contains new still unreleased features and bugs. All the information necessary to download the Source Code, configure a develop environment on the Eclipse IDE and compilerun the source code are described in the tutorial Contributing to Jaspersoft Studio and building from sources. See Also: Introduction to Jaspersoft Studio Jaspersoft Studio Features Designing a Report with Jaspersoft Studio Exporting reports with Jaspersoft Studio Jaspersoft Studio Tutorials Archive

OverviewIn this tutorial we will see what are the requirements to use Jaspersoft Studio, how to install it front the binary and some compilation informations for the advanced users. Software requirements to Run Jaspersoft StudioAs any other Java project Jaspersoft Studio require the Java Runtime Envoirement (JRE), but to compile the report scriptlest a full distribution of Java is required. You need to download the Java Development Kit (JDK) from THIS page for your operative system. Jaspersoft Studio support the most common operative systems, such as: Windows XP/7/8 with 32 or 64 bit;Linux with 32 or 64 bit;MacOS X at 64 bit.The download of Jaspersoft Studio can start from HERE, a page with listed all the release of Jaspersoft Studio will appear, click the one on the top of the list (the last version) and a table with many link will be shown. Here select: jaspersoftstudio_x.x.x_i386.deb for the 32bit version for linux;jaspersoftstudio_x.x.x_amd64.deb for the 64bit version for linux ;jaspersoftstudio_x.x.x_windows-installer-x86_64.exe for the 64bit version of windows;jaspersoftstudio_x.x.x_windows-installer-x86.exe for the 64bit version of windows;jaspersoftstudio-1.3.1-mac-x86_64.dmg for the 64bit version of MacOS X.If your distribution of linux dosen't support the deb format there are also the tar versions. Note that first you must download and install the JDK and the download and install Jaspersoft Studio. Be sure to download and install the correct version of Java and Jaspersoft Studio for your operative system. If you have any doubt on the arichitechture (number of bits) of your Operative System read the subsection below. Check the architechture of the Operative SystemIf you are unsure on "how" are the bits of your system follow this steps: WindowsGo in the Control Panel, then click on System & Security and then on System, you will see a window like this: In this picture you can see that the version of the Operative System is 32 bit. LinuxOpen the terminal and type uname -a , then you will see a response like this: x86_64 means a 64bit Operative System, a 32bit should be listed as i386 or i686. MacOS XOpen the terminal, if you don't know how to do it open the Launchpad, type "Terminal" in the search bar and select the first result. Once the terminal is opend type uname -a , and press enter. A message like this will appear: x86_64 means a 64bit Operative System. At this time the 64 bit version it is the only provided for MacOS. Note that on a 64bit operative system you can install the 32bit version of Java and Jaspersoft studio (altought in this case the 64bit), but you can't do the opposite. It's very important to install the same version of Java and Jaspersoft Studio. For example a Java envoriment with 32bit will not work with the 64bit version of Jaspersoft Studio, you must use a 32bit version of Java with a 32bit version on Jaspersoft Studio or a 64bit version of Java with a 64bit version of Jaspersot Studio.

Introduction Jaspersoft® Studio can handle a wide variety of measure units, including pixels, centimeters, millimeters and inches. To accomplish this, we included a measure component in Jaspersoft® Studio. This component looks like a standard text box with a place to enter a measure unit to the right of the value. You can see an example of this widget in the following image: This component can handle a different measure unit for each field, if needed. Configuration You can set two preferred (default) measure units, one at the field level, the other at the report level. The report level measure is used wherever there is not a prefered field measure unit. The report's default measure unit is the pixel. To change the report level measure: Select Window > Preferences >Jaspersoft Studio >Report Designer. Find the Default Unit where you can set one of the supported measure units, as shown below: Use the drop-down menu to select one of the following measure units: Pixels Inches Millimeters Centimeters Meters Changing the Field Measure Unit There are two ways to change a specific field's measure units: You can insert a new value with the measure unit you want to use in that field. For example, in the figure below, there is an element with size "496 pixel". By inserting a new value, such as "5 cm", the new measure unit for this field will be switched to centimeter and saved for the current sections. This means that without closing the report and reopening it (or changing it manually) the measure unit for the width of that element will remain centimeters. If one value is provided without a measure unit it is assumed that it is the default measure of the field, or, if one isn't provided there, the default unit defined at report level. When a value is inserted manually into the field, no spaces are allowed in the numerical value or in the measure unit, but there can be any number of spaces between the value and the unit. You can also change the local measure unit of a field by double clicking on the measure unit. A pop-up menu appears with all the available measure units listed. Select one of them to set the field's preferred measure, as shown in the following image: Alias and Autocompletion Jaspersoft® Studio has included alias and autocompletion services for measure units. For instance, if you want to use inches, you can type "inch", "inches", or use quote marks. the table below shows the options for entering measure units: Units Accepted Values centimeter centimeter, centimeters, cm millimeter millimeter, millimeters, mm meter meter, meters, m pixel pixel, pixels, px inch inch, inches, " (double quote) In this way, it is simpler to provide a unit, and to help, an autocompletion system is provided. After the value is provided, and the first character of a measure unit is be typed, all the available units that start with that character will be suggested with a popup, and could be selected using the keyboard arrow keys or the mouse, as you can see in the image below: If a typed value, or measure, is not understood, the background of its field will appear red, and the corresponding value or measure will not changed in the report until a correct value is inserted, as you can see in the following image: For the width, in the figure above, we have an invalid number (the numerical value can have only digits and dot). The height has "cat" as an invalid measure unit. Approximations Even if Jaspersoft® Studio handled many measure units, JasperReports works only with pixels. Because of this, pixels is the only measure unit that is allowed in the project file. Jaspersoft® Studio will approximate measurement and convert them to pixels. For example, if you are using centimeters, "5 cm", it will be converted to the nearest pixels value. In this case the 5 centimeters will be converted to 139 pixels (about 4.97 cm)

IntroductionGroups allow you to organize the records of a report into a more organized structure. A group is defined by an expression containing fields and variables that define the criteria for inclusion in that group. JasperReports evaluates this expression and puts all the elements that meet those criteria into the group. Elements are added or removed from groups as needed when their data is updated. Creating a New Group To create a new group, go into the Outline view, right click on the root element (the report you have created) and select Create Group, as shown in the image below: The window to create a new group appears: From here, enter the group name and select your method for creating the new group: Create group from a report object: this is a simplified way to create a group without creating an expression in the expression editor. With this option, all the fields and variables defined in the selected report object are listed, and you can choose which to use in your group. Selecting an element from this list is equivalent to create a group where the expression include only that element. Often the "create group from a report object" option will be sufficent to do what you want, but sometimes a more complex selection is needed. When you provide an expression for the group, JasperReport will evaluate it against each record. When the expression changes in value, a new group is created. Suppose you have the file that contains the amount of money you spent each day, and a report that get the data from this file, into the field Money_Spent. Then define a group with an expression Iike $F{Money_Spent}>150. This expression returns a boolean value, doing this the consecutive records with a value greater than 150 will be grouped toghether. If you have a variable containing that expression already, you can use the simpler method of creating a group from a report object, as described above. In the previous example, we used the word "consecutive" for the grouped values. Suppose to spent $120 for two consecutive days, $200 the third day and $100 the fourth day. With these values three groups will be created: one with the first two elements, one with the third, and one with the fourth. This happens because the JasperReport: Reads the first value and evaluates the group expression: $120 is lesser than $150, so the result of the expression is "false". But since this is the first evaluation a new group is created.Reads the second value and evaluates the group expression: $120 is still lesser than $150 and the result is still false. Since it is the same value of the previous evaluation this value goes in the first group.Reads the third value and evaluates the group expression: $200 is greater than $150 and the result is true. It is different from the previous evaluation, so a new group for this value is created.Reads the fourth value and evaluates the group expression: $100 is not greater than $150 and the result is false. Even this time it is different from the previous evaluation so another group is created. This should clarify how the evaluation of the expression affects the creation of a group. Returning to the creation of the group, after we have selected the way how the group is evaluated we can click "Next" or "Finish". If we click next the following window will appear: Here, you can select if you want the header and the footer of the group in the report. The group will be evaluated even without this two bands, but without any of them there aren't visually changes between a group and another (but the group can still be used for other calculations, see for example the evaluation time, reset type and the other fields in the variable section that uses the group to do some calculations). This because the bands Header and Footer will be always created, and them are visible in the outline view, but if one of the checkbox is unchecked then the relative band will not be placed into the report (in the outline view a band not visible in the report has its name in lightgray color). If you click finish in the previous screen instead of Next both the bands of the group will be created. Editing a GroupIn the outline view are visible the bands of every group created, if the name of the band has a light gray color means that it isn't in the report. Selecting a group header band from the outline view, or directly form the design view (if the band was placed in the report), will made the group properties appear in the property tab. This is shown in the following image: In this example there is one group named "ExampleGroup", with the header visible in the report and the footer not. The header is also selected, so in the properties tab are shown all the property of the group. Among them there are: Name: the name of the group, it can be changed at anytime and all the other elements that reference that group will show the updated name; Expression: the expression evaluated to choose when a new group start ; Layout: define how the elements inside the group are disposed; Height: the height of the header band of the group; Split Type: how the band will be splitted, the possible values are:Stretch: the band is allowed to split, but never within its declared height. This means the band splits only when its content stretches.Prevent: prevents the band from splitting on first break attempt, on subsequent pages/columns, the band is allowed to split.Immediate: the band is allowed to split anywhere, as early as needed, but not before at least one element being printed on the current page/column.Min Height to Start a new page: define the minimum height of the band to start a new page; Footer Position: define the positions of the footer band, if it's visible; Start New Page: if checked a new page will be created for every group start; Start New Column: if checked a new columnwill be created for every group start. If there is only one column in the report this is equivalent to "Start New Page"; Reprint the header on each page: if the header is visible it will be printed on each page even if they contains elements of the same group; Reset Page Number: when the group change the number of page will be resetted; This are the properties of the group header band, the group footer hasn't the "Group Properties" section (that contains the attribute name and the expression). The "Group Bands Properties" section are visible but shared with the one from the same group header band. So a change in the footer of this property will be reflected also in the header. A group can even have more than one headerfooter band in the designer, for example to add an header to a group it's sufficent right click on the header element in the outline view (it dosen't matter if it has black color or lightgray because at the moment there aren't other headers) and select the option "Create Band". A new header band will be created and placed in the designer, and the addition will be reflected even into the outline view in one of these two way: If before the creation the header of the group in the outline view was light gray then it will become black because now it represents the group and also the header band in the designer of the group. If this band is deleted then the name of the group will be displayed light gray again; If before the creation the header of the group in the outline view was in black color a new header element will be added to the outline view. This element represent the new band in the designer and the original group. If the band is removed will be removed also the element added in the outline view during the creation, but not the group. Deleting the GroupOn a group we can perform two type of deleting operations: deleting of the footerheader band of the group and deleting of the entire group. These operations are really different and especially the second one could be very dangerous. This two operations can be accessed by right click on the group header or footer band in the outline view, or by right clicking on the corresponding bands in the designer if they are visible. Note that the option to delete the band is visible only if there is a band of that type on the designer. In the following image there is an example: Deleting the BandDeleting the band remove it from the report and delete all the elements inside it, anyway the group will be manteined, it will be accessible and it can be used in the expressions. A group without bands is shown, as said before, with the name in light gray color instead of black. Deleting the GroupDeleting the group will remove all the bands associated with that group and the group itself. If there are more than one band associated to a single group, selecting the option to remove the group, will also remove all the other bands related. The group will no more usable from other elements and because of this it is a dangerous operation. Infact every element that is using the group will keep a reference to it. If the group is deleted while some element use it and then the report is saved, it can't be reopened in the designer, because when the project is loaded are found references to a missing group and this return an error. Fix the error of a group was deleted while usedIf a group is deleted while used is not more possible to load the project into the designer, and only the XML code of the project is visible. There is a way to fix it by removing from the XML all the references of the deleted group. Search all the occurences of the group using the find tool (CTRL+F) with string to search the name of the deleted group. Probably you will find a string composed as follow: AnyString="Group" AnyString="GroupName", where AnyString could be any string, and GroupName is the name of the group we are searching for. To fix the problem we have to remove every occurence of this string. Let's see an example: In this case the name of the removed group is "ExampleGroup" and the search reported only two occurrences, visible in the image highlighted in red. These two strings are: evaluationTime="Group" evaluationGroup="ExampleGroup evaluationTime="Group" evaluationGroup="ExampleGroup" They match the pattern written before and after deleting this two string (pay attention to not delete something before of after) and saving project file, the report can be opened again in the design tab.

Overview ( portuguese , french ) Variables can be used to store partial results and do complex calculations with the data extracted from data source. These values can then be used in other parts of the report, including other variables. This tutorial shows how to create and configure a variable, and explains the fields that define it. Defining a New Variable or Editing an Existing One As with many other elements, all the defined variables are visible in the Outline menu under the item called "Variables". From there you can create a new variable (right click on the "Variables" item and then "Create variable") and, once selected, a variable its properties are visible on the Properties tab. There are some built-in variables on Jaspersoft Stuido, which present in every report. You can identify these variables because their name has a light gray color, instead of a black color, and the properties of these variables can not be edited. Base Properties of a Variable At a minimum, all variables must have the following defined: Name: a string used to refer to the variable, it is necessary to use this variable inside other expressions (such the valorization of a Text Field or the computation of another variable). To refer to a variable the following syntax is used: $V{variable_name}. Type: necessary because a variable is an object that probably will be used in other expressions, so it's type must be known to be manipulated correctly. Expression: the function used to define the variable value, it can be composed of more fields and variables, and could be used logic operators, math operators and so on. To easly define the expression an expression editor is provided in Jaspersoft Studio, this can be opened using the button at the right of the text Field used to write the expression. The expression is evaluated on each iteration, every time a record is readed from the datasource. If there isn't a calculation function defined (this will be explained below) the result of the expression will be assigned to the variable, so it's important that the result has a type compatible with the one in the variable. Initial Value: the value assiumed from the variable at the beginning, before the first computation of its expression. The initial value it's an expression itself, so it can be defined through the expression editor. It's not mandatory, but this depends on the expression itself and should be a good practice define an initial value. Suppose to have a variable called variable1 with the expression "new Integer(5)". At every record read will be assign to the variable the integer value 5, so the initial value it isn't important in this context. But suppose to change the expression to "$V{variable1}+5", this means that at every iteration the variable is incremented by 5. In this case an initial value it's necessary otherwise at the first iteration the variable1 is undefined and this breaks all future evaluations. So an initial value it's not mandatory, but the not initialized variables can be dangerous, so it's a good practice define it. Other Properties of a Variable The most complex property of a variable is its temporal value. Since its expression is evaluated at every iteration, it is important to understand which value has a variable, and at which time. This can be complicated, considering that a variable can use other variables inside its expression. For these reasons there are mechanisms that can be used to simplify the evaluation or the reading of the variable value during the iterations. Evaluation Time The evaluation time is not an attribute of the variable but of the elements that can use variables in their expressions (like a Text Field) and define the "time" when the value of the variable should be read. A variable can potentially change value at every iteration, so a value read at one time may be different from the one obtained during another time. So for every element that can define an expression is possible to say when evaluate it. And since in the expression could be defined one or more variables this parameter also influences also when these variables are read. The possible values are: Report: the value of the expression is evaluated at the end of the report. Page: the value of the expression is evaluated at the end of every page of the report. Column: the value of the expression is evaluated at the end of each column (if the report is composed only of a column this is equivalent to Page). Group : the value of the expression is evaluated after the break of the specified group. This option is visible only if at least one group is defined. Band: the value of the expression is evaluated after the end of the band where the element with this evaluation time is placed. This is a very particular case, introduced to wait that the other elements in the band are completely created. Typically the value of the variables are read at the start of the band, but for example suppose to have a subreport with an output parameter to print in the main report. To print this parameter it must be read when the subreport was already computed, so the value could be printed when the band is completely created, in this cases the Band evaluation time is necessary. Auto: this is used when in the expression of the element there are more variables and fields, that need to be evaluated at different times. The variables are evaluated at a time corresponding to their Reset Type (see below for more information), instead the fields are always evaluated at time -now. This type is useful when report elements have expressions that combine values evaluated at different times (e.g. percentage out of a total). Now: the value of the expression is evaluated after the read of every record, so at every iteration, this is the default behavior. Calculation Function A calculation function is an attribute of a variable that defines when the variable can be used in association with the expression to determinate the value of the variable. When using a calculation function, the value of the variable is not determined directly by its expression. Instead, it is passed to the calculation function that will use it (depending on the function) to calculate the variable value. There are many function built-in in Jaspersoft Studio: Sum: at every iteration the the value of the expression is taken it will be summed at the value of the variable. This is one of the cases where the initial value is really important. Count: at every iteration the variable value is incremented by one unit. This only if the expression is different from null, in that case the value of the variable will be left unchanged. Distinct Count: at every iteration the variable value is incremented by one unit, but only if the value of the expression was never returned before. Average: the value of the variable is the arithmetic average of all values received in input from the expression. Lowest: the variable take the value of the lowest element received from the expression. Highest: the variable take the value of the highest element received from the expression. Standard Deviation: the standard deviation of all the value received from the expression. First: the variable take the value from the first value returned by the expression. System: no calculation is done and the expression is not evaluated, the value of this variable will be the last value set on it. Useful to store partial results or the final result of a computation. Increment Type As stated above, when a calculation function is defined, the the value of the expression is passed to the function that will do the calculation for the variable. The default behavior is to do this for every record read, but sometimes a different behavior is desired. Using the increment type parameter is possible to change the "time" on which the calculation function is used. The possible values for this attribute are: Report: the Calculation Function is called only at the end of the report, passing to it the value of the expression at that moment. Page: the Calculation Function is called at the end of each page, passing to it the value of the expression at that moments. Column: the Calculation Function is called at the end of each column (if the report is composed only of a column this is equivalent to Page). Group : the Calculation Function is called at the start of every occurance of the specified group. This option is visible only if at least one group is defined. None: the Calculation Function is called after the read of every record, this is the default behavior. Remember that the expression is evaluated at every record read, independently from the increment type selected, but the calculation function will be used only when the times match those defined in the increment type. Reset Type The reset type defines when a variable should be reset to the initial value, or to null if an initial value is undefined. This is useful when the variable is used to compute a partial value, such a sum or an average of only some of the records read. The possible values for this attribute are: Report: the variable is initialized only one time at the beginning of the report creation. Page: the variable is initialized on each page. Column: the variable is initialized again in each new column (if the report is composed only of a column this is equivalent to Page). Group : the variable is initialized at the start of every occurance of the specified group. This option is visible only if at least one group is defined. None: the variable will never be initialized, so the initial value expression is ignored. Incrementer Factory Class Name The calculation functions are useful but are also generics and limited to the numeric types. You may have a case where something more specific is needed. Suppose you have a field of type String and you want to concatenate the value read. You can do this by defining a new Incrementer. An incrementer is a piece of java code that extends the interface JRIncrementerFactory, and can build a personalized calculation function to do what you need. Every calculation function receives the expression value and the variable value and returns the result of the increment, so there is everything needed to do the calculation and return the right value. The Built-In Variables These are default variables built-in into Jaspersoft Studio and that are present in every report defined. They represent very general information. These variables are: PAGE_NUMBER: At every iteration it contains the number of the pages that compose the report. If this variable is read with evaluation time "Report" it will contain the number of all the pages in the report; COLUMN_NUMER: Contains the current number of columns; REPORT_COUNT: Contains the total number of record processed; PAGE_COUNT: Contains the number of record processed in the current page; COLUMN_COUNT: contains the number of record processed during the current column creation. Tips & Tricks Pay attention to the types of the variable, many times a bad result is due to this. For example if your expression returns a number but the variable is type string (that it's also the default type) then its value will be always zero. The form of the expression is really important for the computation of a value, especially when in the expression is used the variable itself. Consider the following example with A field with name "Money_Gained", read from the datasource, that has an integer value and could be null A variable "Total1" with the expression IF(EQUALS($F{Money_Gained}, null), $V{Total1}, $V{Total1}+$F{Money_Gained}), initial value zero, and no calculation function; A variable "Total2" with the expression $V{Money_Gained} == null ? $V{Total2} : $V{Total2}+$F{Money_Gained}, initial value zero, and no calculation function; The two expressions could seem equivalent: they both sum the money gained to the variable when it is not null (remember that if there isn't a calculation function then the value of the expression is assigned to the variable). The check if the Money Gained has value null it's necessary because the sum of a number with the value null is null. So adding null to Total1 or Total2 will change the variable to null. But even with this check when Money_Gained will became null for the first time even Total1 will be null, instead Total2 will have the correct value. This happens because this two expressions have 2 different interpreters, the first is interpreted by Groovy, the second by Java. The java behavior is to evaluate the condition and then select the correct branch. Instead Groovy compute the two branches, then evaluate the expression and finally it return the correct already evaluated branch. Doing this it will add the null value to Total1 before to do the check, and this will made Total1 to became null. A trick to avoid this is to use the variable only in the main branch, for example Total1 could be rewritten like: $V{Total1} + IF(EQUALS($F{Money_Gained}, null),0,F{Money_Gained}). The syntax is still interpreted by Groovy, but now the variable is out of the IF branches, so even if they are both evaluated, the variable maintains its value.

Overview The tutorial on element attributes offered an introduction to the inheritance mechanism of elements. It's clear that there isn't a limit on how long the inheritance chain can be , and for this reason can be difficult to determine which attributes are inherited, and where they are inherited from. The Inheritance Tab Most elements have an Inheritance tab, found in the Properties tab. In the Inheritance tab you can find the attributes of the selected element that can be inherited, and the inheritance hierarchy. It also displays the attributes of the styles in the hierarchy, as well as the inheritable default attributes. Each style in the hierarchy of the selected element are displayed with the attributes that can be inherited, the values of those attributes, the values that are inherited, and those that are overridden by other attributes. Overridden attributes are displayed with a black bar on them. The hierarchy is displayed from the upper level to the lower so in the top position there are the attributes of the selected element and in the bottom position there will be the default attributes. In the Figure above there is an example of one such Property tab. This is a default report template that comes with Jaspersoft Studio, called "Cherry" or "Cherry Landscape". In this report there are five styles defined, and no defined default style. In this example the element "Cherry Title" is selected. In its Inheritance tab we can see the hierarchy. From there we can see that element inherits only one style, called "Title". From the "Title" style, the attribute inherits other attributes: "Font Name", "Font Size", "Bold" and "Forecolor". But "Bold" has a black bar on it, indicating that it is overridden by an attribute with the same name defined at an higher level. In fact, the "Bold" attribute is also defined directly by the selected element, and this instance of the attribute takes precedence over every other "Bold" attribute from a higher level. All the other attributes defined by the style "Title" are used to define the element "Cherry Title" because they aren't overridden by attributes with the same name on a higher level. At the bottom are visible the attributes inherited from the default values. The overridden attributes in this case are: Font Name, defined by the style. Bold, defined by the style and also by the element (so even if the element doesn't have a Bold attribute defined the one from the default values will be still overridden by the one in the style). Font Size, defined by the style. Forecolor, defined by the style. Vertical alignment, defined by the element. Using this tab makes it easy to see the hierarchy of an element and from which the attributes are inherited. Removing an Attribute from the Hierarchy Besides viewing the hierarchy, you can use the Inheritance tab for other things. From here, you can remove an attribute from the hierarchy. This can be done by clicking on the remove button, that appears on the left of every removable attribute when the mouse hovers over it. This is shown in the following figure. Not all the attributes can be removed. Default attributes are those values inherited when any other value in hierarchy is undefined, so they can't be removed. When you remove an attribute, it is removed from the element in which it is defined, and the value will be re-inherited from the next level down where it is defined. Particular caution is needed when an attribute is removed from a style, because this doesn't influence only the selected element, but every element that use that style. Because of this when the user try to remove an attribute from a style a confirmation message is shown, informing on the possible side effects. Anyway when an attribute is removed the undo command (with the shortcut Ctrl+Z) is available to restore it.

Overview In this tutorial, we will see how an element takes the value for its attributes even when they aren't explicitly defined. The Attributes Every element in Jaspersoft Studio has many attributes, defining its graphical appearance and its behavior. These attributes are visible on the property panel. The attributes are divided into categories. In Figure 1, above, you can see the categories of Appearance, Borders, Image, and Inheritance. Appearance and Borders are shared among many elements and contain the attributes that define the graphical appearance of the elements, such as the width of its borders, the background color, and so on. The Image category is a special one because it is present only for the elements of the type "Image." In the Properties tab, every element has a unique category. These categories are used as element types. In this tab, there are properties that define each element's behavior, and for this reason, they are specific for every type. Many times the value of an attribute is undefined, and it has a common default value. This means that the element does not have a specific behavior defined, but gets a behavior from somewhere else. For example, the default value of the attribute "background-color" is undefined in most cases, but when a non-transparent element is added to the designer, we can see that it has a white background. The value of the background color attribute is inherited from a lower level. There are many levels from where the value can be inherited, the first are the styles. The Styles Styles are not a visual element, but a collection of attributes that can be inherited from other elements. The styles can be created and selected from the Outline tab and edited using the Properties tab after the selection. In Figure 2 there are five styles defined, with the "Subtitle" style selected, and its properties displayed in the Properties tab. In Figure 1, we can see that in the Appearance tab, there is the attribute "Style". here a user can choose one of the defined styles that will be associated with that element. This means that every undefined attribute of the element will inherit its value from the analogous attribute of the style. But, because the style is an element, it can have some undefined attributes as well as a "Style" attribute that can be used to inherit values from another style. This defines a hierarchy where an element can inherit attribute values from a style, which in turn can inherit attribute values from another style, and so on until a style that doesn't define a "Style attribute is reached. In addition to this, there is the possibility to set a style as default, using the attribute "Default Style" in the Property tab of the style, in the "Style" category. Only one default style can be defined and must be created by the user if one is to be used. When there is a default style defined, even those that don't use explicitly inherit a style can inherit the attribute's value from the default style. With a such complex hierarchy, there is the possibility that an attribute value could be defined in more styles with different values, and could be confusing to think about which element will use. Because of this, it is important to follow a simple rule: If an element has an undefined attribute, its value will be taken from the nearest style in the hierarchy with that attribute defined. If it's defined also from a lower style in the hierarchy we will say that the lower value is overridden by a higher one. Another case is that an attribute is undefined in the whole hierarchy and in this case the value will be inherited from a series of default values defined at the application level. These default attributes are at the lower level of the hierarchy, and they are in the hierarchy of every element. The definition of nearest is strictly dependent on how the hierarchy is seen. At the top level there is the element itself, under it there is the style associated (if there is one), and one after another the styles in the hierarchy. After them there is the default style if it's defined and at last the default values. Let's see an example, with these elements: Styled Text with no forecolor and no transparent value defined that inherit directly from the Style 1 Style 1 defines the forecolor with the value green and that inherit from Style 2 Style 2 defines the forecolor with the value red Style 3, marked as the default style, set the transparent value to false The default values that define the forecolor to black and set the transparent value to true. Since the hierarchy is http://wiki.jaspersoft.com/download/resources/com.gliffy.integration.confluence:gliffy-macro-key/icons/gliffy-logo-20px.png In this case, the Styled Text will have the forecolor with the value green because the nearest style with a forecolor with a value is style 1, and it has the value green. So the forecolor in style 2 and in the default values are overridden. The transparent value is inherited instead from style 3 for the same reason, and the value from the default values is overridden. Conclusion The inheritance mechanics is very powerful but could be difficult to know from where an attribute is taken when the hierarchy is complex. For this reason, there is a tool that can be used for this purpose, called the inheritance tab, explained in the inheritance tab tutorial.