Jaspersoft®​​​​​​​ Studio Layouts

Overview

In this tutorial we will learn about Jaspersoft^® Studio Layouts, how they work and how to configure them. For every layout, there will be an overview of its functionality and configuration options.

About the Layouts

Jaspersoft Studio Layouts are an automatic way to arrange elements inside a container, like frames, bands, cells and pretty much any element that can contain other elements.

When a layout is set on a container, it takes care of arranging the child of the container in a way depending on the layout itself and how it is configured. Not all layouts require a configuration and a layout can also interact with elements of other containers in some complex cases.  A Layout can forbid a common operation, like resizing and/or moving the elements inside the container, because the layout is handling this operation. To set a layout, simply select a container and select the layout from 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 grows during an execution, then the layout is not used to re-arrange the content. 

Free Layout

This is the layout used by default by every container and doesn’t arrange or put constraints on the elements inside the container.

Horizontal/Vertical Layout

The horizontal layout simply disposes the element into a row where every element has the same width and height. It takes all the elements inside the container and resizes them to fit the height of the container and arranges them to take the width of the container divided by the number of elements. 

The vertical layout works in a similar way, but it disposes the elements as columns. Neither layout allows resizing or moving of elements.

Grid Layout

The grid layout is a well known layout to UI designers.  Its logic and most of its configuration options are the same.

It disposes the elements like a grid where each element is a virtual cell, a specific column or row that can span and have a weight. When using this layout on a container all its child elements will show additional configuration properties in the appearance tab of the property view, which allows configuring 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 Weight.

This layout doesn’t allow moving elements freely, but allows resizing them in some cases. Look at the property, Fixed Size, for more information.

• Row Number: this property defines 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 counts 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 big it is. This mean that no space is 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 defines the column taken by the element and can be a number or the special value, 'relative'. It works exactly like the Row Number but on columns.

• Row Span: this is an integer value greater or equal to 1 and defines how many rows the element takes.

• Column Span: this is an integer value greater or equal to 1 and defines how many columns the element takes.

• Row Weight: defines the height of the current row. Every element has a weight greater or equal to 0, and defines how much space in the container it will proportionally take.

  For example: if, in a column, there are three elements with weight 1 3 and 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: defines the width of the current column. It works exactly like Row Weight.

• Fixed Size: defines if an element should have a fixed size defined by the user instead to be resized by the layout. If set to true, a layout resize will avoid the element and move the other elements accordingly. Also, the Weight for the elements are disabled, since width and height of this element became fixed. When elements use a fixed size, it is no longer assured that they will completely fit in the container.

Spreadsheet Layout

The spreadsheet layout creates a tabular structure using elements of different bands. Essentially it creates something that looks like a table but without actually being one. This avoids using subdatasets.

The spreadsheet layout is unique because it can resize elements across all the containers and it can be set only on bands, other elements don’t support it. In this layout the elements cannot be moved and the height cannot be changed, but the width can be changed.

Also it needs some configuration to work correctly and it has some constraints like:

• To create a column, it is necessary to exactly place an element in the first detail band. This element will act as pivot for the width of the column.
• The layout cannot 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 an 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 element in that column.
• It will be very easy to move and swap columns.
• It allow to have the convenient layout of a table without having its complexity.

All the configuration is done through contextual actions on the elements. To use this layout, it first needs to be set on the detail band. Then, all the elements in the detail will fill the height of the band and will be placed one after another, keeping their original width.

These elements must be connected to one or more elements of other bands to form columns. Select all the elements 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 elements for every band are selected. When an element is placed inside a column, it cannot 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 spreadsheet layout, but that is not part of a column, can be moved and resized like if the layout were 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.