Component Layout

Component layout is controlled through the report style system. Each style can contain one or more LayoutOptions that is applied to the component in the order it appears within the style's layoutOptions array. Each LayoutOptions can define settings that apply different options to control the size, shape, and position of the component as well as various visual appearance elements such as borders and backgrounds.

How Layout Works

Layout is applied to a component in a layered approach as certain layout options will affect how other options are rendered. Because of this, the order of layout options in your report template is very important. For example, consider the component below:

{
    "type": "Text",
    "text": "Layout example",
    "style": {
        "layoutOptions": [
            {
                "minimalBox": true
            },
            {
                "padding": {"all": 10}
            },
            {
                "borders": {"all": 1},
                "borderColor": "Black"
            }
        ]
    }
}

This component applies 3 different layout options. First, minimalBox is specified so that the component is sized to fit its contents. Next, padding is applied around the component. Finally, a border is drawn resulting in a rendered text element as shown below.

If we change the order of the padding and border settings in the layoutOptions array, we get a very different result.

{
    "type": "Text",
    "text": "Layout example",
    "style": {
        "layoutOptions": [
            {
                "minimalBox": true
            },
            {
                "borders": {"all": 1},
                "borderColor": "Black"
            },
            {
                "padding": {"all": 10}
            }
        ]
    }
}

With this small change, the borders around the component are drawn before the padding is applied resulting in the following output:

It is possible to apply certain layout options more than one time. Consider this example:

{
    "type": "Text",
    "text": "Layout example",
    "style": {
        "layoutOptions": [
            {
                "minimalBox": true
            },
            {
                "background": {
                    "color": "LightGray"
                }
            },
            {
                "borders": {"all": 1},
                "borderColor": "Black"
            },
            {
                "padding": {"all": 8}
            },
            {
                "borders": {"all": 1},
                "borderColor": "Black"
            },
            {
                "background": {
                    "color": "LightGoldenrodYellow"
                }
            },
            {
                "padding": {"all": 4}
            }
        ]
    }
}

Rendered output:

By applying background colors, borders and padding multiple times in a specific order, unique styling can be applied to any component. It is not possible to describe all possible ways to combine different layoutOptions, so experimentation is encouraged to achieve the output you desire.

LayoutOptions Schema

key	type	required	description
width	float	optional	The width of the component in pixels. If undefined, the component will be sized to fit the contents. If the contents do not fit in the width specified, a layout exception will occur.
minWidth	float	optional	The minimum width of the component in pixels. This allows for specifying a minimum width while allowing the component to expand to fit contents.
maxWidth	float	optional	The maximum width of the component in pixels. If the contents do fit within the width specified, a layout exception will occur.
height	float	optional	The height of the component in pixels. If undefined, the component will be sized to fit the contents. If the contents do not fit in the height specified, a layout exception will occur.
minHeight	float	optional	The minimum height of the component in pixels. This allows for specifying a minimum height while allowing the component to expand to fit contents.
maxHeight	float	optional	The maximum height of the component in pixels. If the contents do fit within the height specified, a layout exception will occur.
padding	Padding	optional	An object describing the amount of space in pixels to add around the component.
translate	Translate	optional	An object containing x, y coordinates which will shift the end position of the component on the page. This allows for very precise positioning of a component in a report. The adjusted position will also apply to the component's children. Allows for components to ignore position constraints inherited from the parent.
alignment	string	optional	The horizontal alignment to use when positioning the component relative to its parent. Valid values are left, right and center. Default is left.
vAlignment	string	optional	The vertical alignment to use when positioning the component relative to its parent. Valid values are top, middle and bottom. Default is top.
minimalBox	bool	optional	If true, the component will ignore constraints inherited from its parent and force the size to the minimum required to fit its contents.
extendVertical	bool	optional	If true, the component will extend vertically to take all available space.
extendHorizontal	bool	optional	If true, the component will extend horizontally to take all available space.
rotate	integer	optional	Rotates the component be the amount specified in degrees. Other size and space constraints will still apply.
showOnce	bool	optional	If true, the component will be rendered only once. This is useful for headers that should only appear on the first page of a report.
skipOnce	bool	optional	If true, the component will not be rendered on the first page on which it would normally appear. This is useful for headers that should only appear after the first page of a report.
showEntire	bool	optional	If true, the component will not be split across multiple pages. Instead, a new page will be created to show the entire component. If the component is too large to fit on a single page, a layout exception will occur.
unconstrained	bool	optional	If true, the component will not take any space on the page. Instead, it will be rendered above or below other components.
borders	Borders	optional	An object describing the borders to draw around the component.
borderColor	string	optional	A string the defines the color used to draw borders. Colors can be well-defined color names, or RGB values (e.g. "#1E3D7A").
background	Background	optional	An object that describes the background to draw behind the component.
condition	Conditional	optional	If present, the layoutOptions specified will be applied only if the condition evaluates to true.

Padding

The Padding object allows for adding empty space around a component.

Schema

key	type	required	description
all	float	optional	The amount of padding, in pixels, to add to all sides of the component. If this element is defined, all other elements are ignored.
left	float	optional	The amount of padding, in pixels, to add to the left side of the component.
top	float	optional	The amount of padding, in pixels, to add to the top of the component.
right	float	optional	The amount of padding, in pixels, to add to the right side of the component.
bottom	float	optional	The amount of padding, in pixels, to add to the bottom of the component.

Translate

The Translate object allows for adjusting the position of a component.

Schema

key	type	required	description
x	float	optional	The number of pixels to adjust the component position horizontally. A negative number will move the component to the left and a positive number will move it to the right.
y	float	optional	The number of pixels to adjust the component position vertically. A negative number will move the component up and a positive number will move it down.

Borders

The Borders object allows for adding borders around a component.

Schema

key	type	required	description
all	float	optional	The size of the border, in pixels, to apply to all sides of the component. If this element is defined, all other elements are ignored.
left	float	optional	The size of the border, in pixels, to apply to the left side of the component.
top	float	optional	The size of the border, in pixels, to apply to the top of the component.
right	float	optional	The size of the border, in pixels, to apply to the right side of the component.
bottom	float	optional	The size of the border, in pixels, to apply to the bottom of the component.

Background

The Background object specifies the design of the background of a component. A color or gradient may be applied, as well as a corner radius to draw rounded objects. An example of all of these options is below:

{
    "type": "Text",
    "text": "Layout example",
    "style": {
        "layoutOptions": [
            {
                "minimalBox": true
            },
            {
                "background": {
                    "gradient": {
                        "type": "Linear",
                        "colors": ["HotPink", "Aqua"],
                        "direction": "TopLeftToBottomRight"
                    },
                    "radius": 5
                }
            },
            {
                "padding": {"all": 8}
            },
            {
                "borders": {"all": 1},
                "borderColor": "Black"
            },
            {
                "background": {
                    "color": "White",
                    "opacity": 0.6
                }
            },
            {
                "padding": {"all": 4}
            }
        ]
    }
}

Rendered output of the background options above:

Background Schema

key	type	required	description
color	string	optional	A string that defines the color used to draw the background. Colors can be well-defined color names, or RGB values (e.g. "#1E3D7A").
opacity	float	optional	The opacity of the background color. A value of 1 indicates a fully opaque color and 0 is fully transparent. Ignored if color is not defined.
gradient	Gradient	optional	A gradient to use as the background of the component.
radius	float	optional	The radius of the background corners.