In this tutorial we will see what are the Jaspersoft Studio Layouts, how they work and how to configure them. For every layout there will be an overview of its functionality and configuration option.
About the Layouts
Jaspersoft Studio Layouts are an automatic way to arrange elements inside a container, like frame, bands, cells and pretty much every element that can contain other elements.
When a layout is set on a container it take care of arrange the child of the container in a way depending from the layout itself and how it is configured. Not all layout require a configuration and a layout can also interact with elements of other containers in some complex cases. A Layout can forbid common operation like resizing and/or moving the elements inside the container, because the layout is handling this operations. To set a layout simply select a container and select the layout form the appearance tab inside the properties view:
Consider that a layout is used only at design time to help the user, and it is a Jaspersoft Studio feature. This means that it will never be used when a report is executed and if, for example, a container grow during the execution then the layout is not used to re-arrange the content.
This is the layout used by default by every container and doesn’t arrange or put constraints on the elements inside the container. In other way this layout does nothing and allow to dispose the elements freely.
The horizontal layout simply dispose the element into a row where every element has the same width and height. It take all the elements inside the container and resize them to fit the height of the container and arrange them to take each one the width of the container divided by the number of elements.
The vertical layout works in similar way but it dispose the elements as a column. Both this layouts doesn’t allow resize or moving of elements.
The grid layout is a well know layout to who design User Interfaces since it is still really used. In this one the logic and most of the configuration options are the same, it dispose the elements like a grid where each element take place into a virtual cell, that is into a specific column or row and that can span and have a weight. When using this layout on a container all its child elements will show an additional configuration properties in the appearance tab of the property view, which allow to configure how the element will be placed inside the layout. There properties are: Row Number, Column Number, Row Span, Column Span, Fixed Size, Row Weight and Column Wight. This layout doesn’t allow to move the elements freely but allow in some case to resize them, look at the property Fixed Size for more information.
- Row Number: this property define the row taken by the element and can be a number or the special value relative. When set to relative it uses the same row of the previous element. If it is set on the first element then it count as 0. When selecting a number it will try to place the element in that specific row, if the row number is bigger than the actual number of row the element will be placed on a new row after the last one, ignoring how bigger it is, this mean that no space are left between elements. For example if I have 4 rows and I set as row number of an element 10 then the element will be placed under the fourth row creating a fifth, but if after that another element is created with row number 7 then it will take the fifth and the previous one will take the sixth.
- Column Number: this property define the column taken by the element and can be a number or the special value relative. It works exactly like the row number but it works on the columns.
- Row Span: this is an integer value greater or equal than 1 and define how many row the element takes.
- Column Span: this is an integer value greater or equal than 1 and define how many columns the element takes.
- Row Weight: define the height of the current row. Every element has a weight greater or equal than 0, an define how much space of the container it proportionally take. For example if in a column there are three elements with weight 1,3,5 it is calculated the total weight by summing them, that’s 9. This means that the first element take 1/9 of the available height, the second 3/9 and the last one 5/9. So bigger is the weight and bigger is the element. If on the same row there are more elements with different row weight the one with the bigger value take the precedence.
- Column Weight: define the width of the current column. It works exactly like the Row Weight.
- Fixed Size: The define if an element should have a fixed size defined by the user instead to be resized by the layout. Setting this to true will avoid the layout resize the element and move the other elements accordingly. When setting this value to true the Weight for the elements are disabled since width and height of this element became fixed. When elements uses a fixed size is no more assured that the container will be completely fit.
The idea behind the spreadsheet layout is to create a tabular structure using elements of different bands. Essentially it create something that looks like a table but without using one. This was done because using a table force to use also a subdataset, which is not trivial to configure.
Spreadsheet layout is an unique kind of layout because can resize elements across all the containers and it can be set only on bands, other elements doesn’t support it. In this layout the elements can not be moved and the height can not be changed, but can be changed the width.
Also it need some configuration to work correctly and it has some constraints like:
- To create a column it is necessary exactly an element in the first detail band. This element will act as pivot for the width of the column.
- The layout can not be used on containers different from bands.
- Every column can have only an element for each band. Something similar to a span can be achieved by using a frame as element of the column and place inside something else.
- Every band which contains an element of the column must use a spreadsheet layout, otherwise the element will be ignored.
The advantages using this layout are:
- Changing a width of an element of the column will change the width of every other elements in that column.
- It will be very easy to move and swap column.
- It allow to have the conveninet layout of a table without having its complexity.
All the configuration is done trough contextual actions on the elements. To use this layout it first need to be set on the detail band, when this is done all the elements in the detail will fill the height of the band and will be placed one after another, keeping their original width.
Now this elements must be connected to one or more elements of other bands to form a columns. To do this you need to select all the element and from the contextual menu select the option “Add to Column”. This option is visible if every selected element is inside a container with a spreadsheet layout and if only element for every band is selected. When an element is placed inside a column it can’t be moved or resized except for the width, if the width is changed then the width of every element of the column is changed as well, like in a table.
Instead an element inside a container using the spredsheet layout but that is not part of a column can be moved and resized like if the layout is a Free Layout. The only exception is for the elements inside the first detail band because they are implicitly part of a column.
An element in a column can be removed from it simply with the contextual action “Remove from column”.
The elements in the detail are always disposed in their creation order, the same visible in the outline, but changing the position of an element in the detail will allow to change the position of all its entire column. You can see a sample in this video.