Styles
The report engine uses a Style system to define the layout and formatting of components. Every component includes the same style object, making it possible to reuse styles on any component. Styles can be defined once in a report and then applied to multiple components. It is also possible to define styles externally from the report and apply them at time of render. This allows for creating a single report template that can be rendered with different styles and for sharing styles between multiple report templates.
Style Types
There are 2 different types of styles: Component and Chart. Component styles can be applied to any component in a report. layoutOptions in a style will take affect on all components, while textOptions will only apply to components that include text elements.
Besides the generic Component style, there are a variety of Chart styles that can be applied to various chart types and elements. More details on these styles can be found in the corresponding chart documentation.
Applying Styles
The simplest way to apply a style to a component is by explicitly defining it in the component definition:
{
"type": "Text",
"text": "Financial Report",
"style": {
"textOptions":
{
"alignment": "center",
"fontSize": 16,
"weight": "bold"
}
}
}
This method is straightforward and easy to understand, but applying a style in this way to every component in the report can lead to a large template that is difficult to manage. The preferred approach is to use Shared Styles. This allows for a style to be defined one time and then applied to components using a style identifier.
Shared Styles
A shared style is defined in the ReportOptions of a report template, or in an external options file. All shared styles include a unique identifier that can be used to apply the corresponding style to a component in a report. It is up to the report designer to ensure that a style id is unique as this is not enforced by the rendering engine. If multiple styles with the same identifier are included in a report, the first one defined will be used and any subsequent styles will be ignored. If a style is applied to a component but not defined anywhere in the report, a warning message will be generated by the rendering engine but the report will still be created.
Defining a shared style
A shared style is defined in ReportOptions either in the report or in an external file. The following example shows how to define a shared style with an identifier named title.
"options":
{
"styles": [
{
"type": "Component",
"id": "title",
"textOptions": {
"alignment": "center",
"fontSize": 16,
"weight": "bold"
}
}
]
}
Applying a share style to a component
The example style shown above can later be applied to a text component as in this example:
{
"type": "Text",
"text": "Financial Report",
"style": "title"
}
Combining Styles
It is possible to apply multiple styles to a single component. This further extends the usefulness of shared styles and makes it easier to build a custom style system that is easy to use and understand. Consider the following two example styles:
"options":
{
"styles": [
{
"type": "Component",
"id": "bold",
"textOptions": {
"weight": "bold"
}
},
{
"type": "Component",
"id": "center",
"textOptions": {
"alignment": "center"
}
}
]
}
These two styles can be applied to a component by including them both in the style string, separated by commas. This is shown in the text component below:
{
"type": "Text",
"text": "Year End Report",
"style": "bold, center"
}
Styles with layoutOptions can also be combined in this way. Consider the example styles below:
"styles": [
{
"type": "Component",
"id": "border-background",
"layoutOptions": [
{"borders": {"all": 1}, "borderColor": "Black"},
{"background": {"color": "LightGray"}}
]
},
{
"type": "Component",
"id": "padding",
"layoutOptions": {"padding": {"all": 4}}
}
]
And the following Text component:
{
"type": "Text",
"text": "$($DATE)",
"style": "border-background, padding"
}
All layoutOptions in combined styles are applied in the order they appear in the style string. Changing the order of the style identifiers will result in a different layout. The Text component above would have the following layoutOptions applied:
"layoutOptions": [
{"borders": {"all": 1}, "borderColor": "Black"},
{"background": {"color": "LightGray"}},
{"padding": {"all": 4}}
]
Note that if conflicting textOptions settings exist in the styles applied to a component, the last one listed in the style string will take precedence. Designing a style system in this way leads to very clear and simple report templates.
Default Shared Styles
A set of default shared styles is defined within the reporting engine. These styles can be used in any report using their corresponding identifier just as any other shared style. Any shared style defined in a report template or external options file that uses the same id as a default shared style will override the default style. The default shared styles are defined as below:
{
"styles": [
{
"type": "Component",
"id": "thin",
"textOptions": { "weight": "thin" }
},
{
"type": "Component",
"id": "extraLight",
"textOptions": { "weight": "extraLight" }
},
{
"type": "Component",
"id": "light",
"textOptions": { "weight": "light" }
},
{
"type": "Component",
"id": "normal",
"textOptions": { "weight": "normal" }
},
{
"type": "Component",
"id": "medium",
"textOptions": { "weight": "medium" }
},
{
"type": "Component",
"id": "semiBold",
"textOptions": { "weight": "semiBold" }
},
{
"type": "Component",
"id": "bold",
"textOptions": { "weight": "bold" }
},
{
"type": "Component",
"id": "extraBold",
"textOptions": { "weight": "extraBold" }
},
{
"type": "Component",
"id": "black",
"textOptions": { "weight": "black" }
},
{
"type": "Component",
"id": "extraBlack",
"textOptions": { "weight": "extraBlack" }
},
{
"type": "Component",
"id": "italic",
"textOptions": { "weight": "italic" }
},
{
"type": "Component",
"id": "underline",
"textOptions": { "weight": "underline" }
},
{
"type": "Component",
"id": "subscript",
"textOptions": { "weight": "subscript" }
},
{
"type": "Component",
"id": "superscript",
"textOptions": { "weight": "superscript" }
},
{
"type": "Component",
"id": "strikeThrough",
"textOptions": { "weight": "strikeThrough" }
},
{
"type": "Component",
"id": "8",
"textOptions": { "fontSize": 8 }
},
{
"type": "Component",
"id": "center",
"textOptions": { "alignment": "center" }
},
{
"type": "Component",
"id": "left",
"textOptions": { "alignment": "left" }
},
{
"type": "Component",
"id": "right",
"textOptions": { "alignment": "right" }
},
{
"type": "Component",
"id": "top",
"textOptions": { "vAlignment": "top" }
},
{
"type": "Component",
"id": "middle",
"textOptions": { "vAlignment": "middle" }
},
{
"type": "Component",
"id": "bottom",
"textOptions": { "vAlignment": "bottom" }
},
{
"type": "Component",
"id": "showOnce",
"layoutOptions": { "showOnce": true }
},
{
"type": "Component",
"id": "skipOnce",
"layoutOptions": { "skipOnce": true }
},
{
"type": "Component",
"id": "showEntire",
"layoutOptions": { "showEntire": true }
},
{
"type": "Component",
"id": "layout-center",
"layoutOptions": { "alignment": "center" }
},
{
"type": "Component",
"id": "layout-left",
"layoutOptions": { "alignment": "left" }
},
{
"type": "Component",
"id": "layout-right",
"layoutOptions": { "alignment": "right" }
},
{
"type": "Component",
"id": "layout-top",
"layoutOptions": { "vAlignment": "top" }
},
{
"type": "Component",
"id": "layout-middle",
"layoutOptions": { "vAlignment": "middle" }
},
{
"type": "Component",
"id": "layout-bottom",
"layoutOptions": { "vAlignment": "bottom" }
}
]
}
Style Schema
| key | type | required | description |
|---|---|---|---|
| type | string |
required | Defines the type of style being defined. This must be the first element in the object and is required only when defining a shared style. Styles set explicitly on a component do not require this element. Can be one of: Component, Chart, ChartLabel, ChartAxis, PieChart, GaugeChart, BarChartSeries, or LineChartSeries. |
| id | string |
required * | Defines a unique identifier for the style. This id can be used to apply the corresponding style definition to any component. * Required only when defining a shared style. |
| textOptions | TextOptions or TextOptions[] |
optional | The text formatting options to apply to the component. Text options can be supplied as either a single object, or an array of objects. When providing an array of TextOptions objects, the first object with no conditional or the first object with a conditional that evaluates to true will be applied to the text. If the component does not include text elements (e.g. Header component), this property is ignored. |
| layoutOptions | LayoutOptionsLayoutOptions[] |
optional | The layout options to apply to the component. Layout options can be supplied as either a single object, or an array of objects. When providing an array of LayoutOptions objects, each layout will be applied to the component sequentially. For more information, see Component Layout. |