Skip to content

Text Component

Overview

A text component is used to add a text element to a report. Either text or textElements must be present. Text will always render from left to right and will drop down to create a new line if the text does not fit within the component width. Newline characters (\n) can be included to force a carriage return. Text components can optionally include JSONata queries in order to use Data Substitution.

Schemas

TextComponent

key type required description
type string required A string defining the component type as Text. This is required and must be the first element in the json object.
text string optional* The text to display. Data substitution can be used by including one or more JSONata queries inside a query block @() anywhere within the text. See below for an example. *Either text or textElements is required.
textElements TextElement[] optional* An array of text elements to display. This is useful when applying different styles to sections of text. See below for an example. *Either text or textElements is required.
hyperlinkUrl string optional If included, the rendered text will be a hyperlink to the URL specified. Any formatting to indicate that the text is a hyperlink must be applied explicitly.
gridRow integer optional The grid row to place the component. Only applicable when inside a GridV2 component.
gridColumn integer optional The grid column to place the component. Only applicable when inside a GridV2 component.
gridRowSpan integer optional The number of rows to span inside the grid. Only applicable when inside a GridV2 component. Default value is 1.
gridColumnSpan integer optional The number of columns to span inside the grid. Only applicable when inside a GridV2 component. Default value is 1.
rowWidth float optional A fixed width for the component inside the row. Only applicable when inside a RowV2 component.
rowRelativeWidth float optional A proportional width for the component inside the row. Only applicable when inside a RowV2 component.
sectionName string optional Marks the component, its contents, and any sub-components as a named section in the report. A section can span multiple pages. The first, last and page count of a section can be inserted into the report using tokens: e.g. $(SECTION_BEGIN_[section-name]), $(SECTION_END_[section-name]) and $(SECTION_COUNT_[section-name]).
sectionLink string optional If defined, the entire component will become a link to a named section in the report. The link will redirect the user to the beginning of the named section in the report.
debug DebugOptions optional Enables highlighting of this component in the report. Useful for debugging layout issues.
style string or Style optional Either a style identifier or a style object used to define the layout/styling options for the component. For a more detailed explanation of the style system, see Styles.
condition Conditional optional The component will not be rendered in the report if a condition is present and it evaluates to false. For more information on conditions, see Conditionals.

TextElement

key type required description
text string optional The text to display. Data substitution can be used by including one or more JSONata queries inside a query block @() anywhere within the text. See below for an example.
hyperlinkUrl string optional If included, the rendered text will be a hyperlink to the URL specified. Any formatting to indicate that the text is a hyperlink must be applied explicitly.
style string or Style optional Either a style identifier or a style object used to define the styling options for the component. For textElements, the layoutOptions of the style are ignored. For a more detailed explanation of the style system, see Styles.

Examples

Each example below shows how to use the various options for rendering text in a report. All samples include a rendered image showing how the component would appear in a report.

Basic example

An example of a simple Text component:

{
    "type": "Text",
    "text": "Sales Report"
}

The component above renders as:

!Text component example

A Text component with formatting:

{
    "type": "Text",
    "text": "2023 Sales Report",
    "style|`integer`|optional|teger`|optional|center",
            "fontSize": 14
        fontColor": "darkblue",
            "weight": "bold"
        }
    }
}

The component above renders as:

!Text component example

TextElements example

By breaking out text into the TextElements array, it is possible to apply different formatting to each portion of the displayed text. This is especially helpful when custom formatting is required.

An example text component with multiple formatting styles is shown below. Notice that there is a style applied to the base component as well as some of the individual textElements. These styles will be combined by the rendering engine so that all textElements are affected by the base component style.

{
    "type": "Text",
    "textElements": [
        {
            "text": "A single "
        },
        {
            "text": "Text Component ",
            "style|`integer`|optional|teger`|optional|bold"
                }
        },
        {
            "text": "may ",
            "style|`integer`|optional|teger`|optional|italic"
                }
        },
        {
            "text": "contain multiple text "
        },
        {
            "text": "styles",
            "style|`integer`|optional|teger`|optional|red"
                }
        },
        {
            "text": "."
        }
    ],
    "style|`integer`|optional|teger`|optional|2
        }
}

The component above renders as:

!Text component example

Data Substitution Example

A text component that uses data substitution through a JSONata query:

{
    "type": "Text",
    "text": "@(salesYear) Sales Report",
    "style|`integer`|optional|teger`|optional|center",
            "fontSize": 14
        fontColor": "darkblue",
            "weight": "bold"
        }
    }
}

If the component above was rendered with the following JSON data:

{
    "salesYear": "2023"
}

The output would be: !Text component example