Table Component

Overview

A table is used to display data in a typical column/row format. Data for a table can be added in the table definition directly, or by using JSONata queries to retrieve data from the JSON data file. Each table is composed of 3 sections: the header, main content, and the footer. Each section is optional and can contain one or more rows. Styles and formatting can be applied to each section independently. A table also contains one or more columns.

Columns

Each table component must define one or more Columns. The column optionally defines the width, data and style of the column in the table. Each of these items can be controlled for each section of the table independently.

Rows

A Row must be defined for each desired section of the report: header, main content and footer. Each defined row can contain either a JSONata query to retrieve row data from the json data file, or static data. Each row can also contain a Style object for controlling the text format and layout options for the row section.

Styles

Tables use the style system just as any other component, but with additional options to define different styles for each section of a report. The style system for Table components is applied in the following order, with each later style overriding the settings of a previous style:

default style -> table style -> row style -> column style

See examples for more details on how to use table styles.

Default Styles

A report template may optionally define default style settings for all tables in a report. This helps to reduce duplicate code and apply the same Styles system to every table component in all your reports.

{
    ...
    "options": {
         "defaultTableOptions": {
            "style": "table_layout",
            "headerStyle": "table_header",
            "rowStyle": "table_rows",
            "footerStyle": "table_footer"
        }
    }
}

Schemas

The schemas below show all settings available for defining tables and related objects.

Table

key	type	required	description
type	string	required	A string defining the component type as a Table.
columns	TableColumn[]	required	An array of TableColumn objects that describe the columns of the table.
headerRows	TableRow[]	optional	An array of TableRows describing the header rows to display in the table. This value is ignored if headerRowComponents is defined.
headerRowComponents	Component[]	optional	An Array of components to display in the table header.
rows	TableRow[]	optional	An array of TableRows describing the content rows to display in the table. This value is ignored if rowComponents is defined.
rowComponents	Component[]	optional	An Array of components to display in the main section of the table.
footerRows	TableRow[]	optional	An array of TableRows describing the footer rows to display in the table. This value is ignored if footerRowComponents is defined.
footerRowComponents	Component[]	optional	An Array of components to display in the table footer.
columnRepeatCount	integer	optional	The number of times to repeat columns horizontally. Default is 1.
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.
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.

TableRow

key	type	required	description
dataQuery	string	optional	A JSONata query used to extract data for populating the relevant rows of the table. The query should return an array of objects.
data	string[][]	optional	An array of string arrays to include as rows in the table. If dataQuery is defined, rowData will be ignored.
style	string or Style	optional	Either a style identifier or a style object used to define the layout/styling options for the rows. For a more detailed explanation of the style system, see Styles.

TableColumn

key	type	required	description
width	number	optional	A fixed width for the column. Not allowed if relativeWidth is present.
relativeWidth	number	optional	A relative width for the column. Not allowed if width is present.
headerDataQuery	string	optional	A JSONata query used to extract data for the header rows of this column. The query should return a string. If headerData is defined, it takes precedence over the data returned from this query.
headerData	string[]	optional	An array of strings to use as the data for the header rows of this column. Each string in the array will be added as a header row item in this column.
rowDataQuery	string	optional	A JSONata query used to extract data for the rows of this column. The query should return a string. If rowData is defined, it takes precedence over the data returned from this query.
rowData	string[]	optional	An array of strings to use as the data for the rows of this column. Each string in the array will be added as a row item in this column.
footerDataQuery	string	optional	A JSONata query used to extract data for the footer rows of this column. The query should return a string. If footerData is defined, it takes precedence over the data returned from this query.
footerData	string[]	optional	An array of strings to use as the data for the footer rows of this column. Each string in the array will be added as a footer row item in this column.
headerStyle	string or Style	optional	Either a style identifier or a style object used to define the layout/styling options for the header column. For a more detailed explanation of the style system, see Styles.
rowStyle	string or Style	optional	Either a style identifier or a style object used to define the layout/styling options for the row column. For a more detailed explanation of the style system, see Styles.
footerStyle	string or Style	optional	Either a style identifier or a style object used to define the layout/styling options for the footer column. For a more detailed explanation of the style system, see Styles.
headerColumnSpan	int	optional	The number of columns this header column should span. Default value is 1.
rowColumnSpan	int	optional	The number of columns this row column should span. Default value is 1.
footerColumnSpan	int	optional	The number of columns this footer column should span. Default value is 1.

DefaultTableOptions

key	type	required	description
style	string or Style	optional	Either a style identifier or a style object used to define the layout/styling options for the table. For a more detailed explanation of the style system, see Styles.
headerStyle	string or Style	optional	Either a style identifier or a style object used to define the layout/styling options for the header column. For a more detailed explanation of the style system, see Styles.
rowStyle	string or Style	optional	Either a style identifier or a style object used to define the layout/styling options for the row column. For a more detailed explanation of the style system, see Styles.
footerStyle	string or Style	optional	Either a style identifier or a style object used to define the layout/styling options for the footer column. For a more detailed explanation of the style system, see Styles.

Examples

Basic Table

An example of a Table:

{
    "type": "Table",
    "headerRows": {
        "data": [ [ "Date", "Merchant", "Amount" ] ],
        "style": "bold"
    },
    "rows": {
        "dataQuery": "transactions",
        "style": {
            "textOptions": [
                { "backgroundColor": "LightGray" },
                { "backgroundColor": "White" }
            ]
        }
    },
    "columns": [
        {
            "rowDataQuery": "date"
        },
        {
            "rowDataQuery": "merchant"
        },
        {
            "rowDataQuery": "amount",
            "rowStyle": "currency, right",
            "headerStyle": "right"
        }
    ]
}

Applying Styles

To best understand the Table component style system, it is helpful to study the report below which illustrates the various ways styles can be applied and overridden in a report. The code below can be copied directly into a new file, or you can get the full tables sample (Template and Data) from git Template | Data.

{
    "id": "TABLE_LAYOUT",
    "name": "Table Layout",
    "description": "Examples of how table layout works.",
    "creator": "Aaron Watson",
    "version": "1.0",
    "options": {
        "margins": {
            "left": 24,
            "top": 24,
            "right": 24,
            "bottom": 24
        },
        "styles": [
            {
                "type": "Component",
                "id": "header",
                "textOptions": {"fontSize": 24, "alignment": "center"}
            },
            {
                "type": "Component",
                "id": "text",
                "layoutOptions": [                    
                    {"alignment": "center", "showEntire": true},
                    {"width": 400},
                    {"padding": {"top": 20, "bottom": 8}}
                ]
            },
            {
                "type": "Component",
                "id": "table_layout",
                "layoutOptions": [
                    {"alignment": "center"},
                    {"width": 400},
                    {"borders": {"all": 1}, "borderColor": "Black"}
                ]
            },
            {
                "type": "Component",
                "id": "table_header",
                "layoutOptions": {
                    "padding": {"all": 2}
                },
                "textOptions": { 
                    "backgroundColor": "#1E3D7A",
                    "fontColor": "White",
                    "weight": "bold",
                    "fontSize": 10
                }
            },
            {
                "type": "Component",
                "id": "table_rows",
                "layoutOptions": {
                    "padding": {"all": 2}
                },
                "textOptions": [
                    { "backgroundColor": "LightGray" },
                    { "backgroundColor": "White" }
                ]
            },
            {
                "type": "Component",
                "id": "table_footer",
                "layoutOptions": {
                    "padding": {"all": 2}
                },
                "textOptions": { 
                    "backgroundColor": "DarkGray",
                    "weight": "bold"
                }
            }
        ], 
        "defaultTableOptions": {
            "style": "table_layout",
            "headerStyle": "table_header",
            "rowStyle": "table_rows",
            "footerStyle": "table_footer"
        }
    },
    "components": [
        {
            "type": "Text",
            "text": "Table Samples",
            "style": "header"
        },
        {
            "type": "Text",
            "text": "This table uses all the default styles as defined in Report.DefaultTableOptions.",
            "style": "text"
        },
        {
            "type": "Table",
            "columns": [{}, {}, {}, {}],
            "headerRows": {
                "dataQuery": "headerData"
            },
            "rows": {
                "dataQuery": "rowData"
            },
            "footerRows": {
                "dataQuery": "footerData"
            }
        },
        {
            "type": "Text",
            "text": "This table shows how table layout options defined in report options can be overridden. Any values defined in layoutOptions at the table level will override all default settings.",
            "style": "text"
        },
        {
            "type": "Table",
            "style": {"layoutOptions": {}},
            "columns": [{}, {}, {}, {}],
            "headerRows": {
                "dataQuery": "headerData"
            },
            "rows": {
                "dataQuery": "rowData"
            },
            "footerRows": {
                "dataQuery": "footerData"
            }
        },
        {
            "type": "Text",
            "text": "This table shows how text options defined in report options can be overridden. Notice that textOptions are accumulative. In order to completely change text styles, all default values must be overridden. The footer uses some values from the table defaults, while the header replaces all values.",
            "style": "text"
        },
        {
            "type": "Table",
            "columns": [{}, {}, {}, {}],
            "headerRows": {
                "dataQuery": "headerData",
                "style": {"textOptions":{"fontName": "Courier New", "weight": "italic", "backgroundColor": "DarkGray", "fontColor": "Black", "fontSize": 12}}
            },
            "rows": {
                "dataQuery": "rowData"
            },
            "footerRows": {
                "dataQuery": "footerData",
                "style": {"textOptions": {"fontName": "Courier New"}}
            }
        },
        {
            "type": "Text",
            "text": "This table shows how to change text formatting at the column level. Text formatting at the column level will inherit from either the report level default options or the table default.",
            "style": "text"
        },
        {
            "type": "Table",
            "columns": [
                {}, {}, {}, 
                {
                    "headerStyle": {"textOptions": { "alignment": "right", "fontColor": "Orange", "backgroundColor": "Gray" }},
                    "rowStyle": { "textOptions": { "alignment": "right"}},
                    "footerStyle": {"textOptions": { "alignment": "right"}}
                }
            ],
            "headerRows": {
                "dataQuery": "headerData",
                "style": {"textOptions": { "fontColor": "Red", "weight": "italic" }}
            },
            "rows": {
                "dataQuery": "rowData"
            },
            "footerRows": {
                "dataQuery": "footerData"
            }
        },
        {
            "type": "Text",
            "text": "This table shows additional examples of how to change layout options in a table. Notice that every instance of layoutOptions will always override any previous layout settings.",
            "style": "text"
        },
        {
            "type": "Table",
            "style": {"layoutOptions": {"width": 300}},
            "columns": [
                {}, {}, {}, 
                {
                    "rowStyle": {
                        "layoutOptions": {
                            "borders": {"left": 1},
                            "borderColor": "Black",
                            "padding": {"all": 2}
                        }
                    },
                    "footerStyle": {
                        "layoutOptions": {
                            "borders": {"left": 1},
                            "borderColor": "Black",
                            "padding": {"all": 2}
                        }
                    }
                }
            ],
            "headerRows": {
                "dataQuery": "headerData",
                "style": {
                    "layoutOptions": {
                        "borders": {"bottom": 1, "top": 1},
                        "borderColor": "Red",
                        "padding": {"all": 2}
                    }
                }
            },
            "rows": {
                "dataQuery": "rowData"
            },
            "footerRows": {
                "dataQuery": "footerData"
            }
        },
        {
            "type": "Text",
            "text": "This table shows how to change row colors. An array of 'backgroundColors' can be specified and each color will be repeated in the rows.",
            "style": "text"
        },
        {
            "type": "Table",
            "columns": [{}, {}, {}, {}],
            "headerRows": {
                "dataQuery": "headerData"
            },
            "rows": {
                "dataQuery": "rowData",
                "style": {
                    "textOptions": [
                        {"backgroundColor": "LightSalmon"},
                        {"backgroundColor": "LightBlue"},
                        {"backgroundColor": "LightSlateGray"}
                    ]
                }
            },
            "footerRows": {
                "dataQuery": "footerData"
            }
        },
        {
            "type": "Text",
            "text": "This table shows how to set multiple header and footer rows.",
            "style": "text"
        },
        {
            "type": "Table",
            "columns": [{}, {}, {}, {}],
            "headerRows": [
                {
                    "dataQuery": "headerData"
                },
                {
                    "data": [["Column1.1", "Column2.1", "Column3.1", "Column4.1"]]
                }
            ],
            "rows": {
                "dataQuery": "rowData"
            },
            "footerRows": [
                {
                    "data": [["Footer1.1", "Footer2.1", "Footer3.1", "Footer4.1"]]
                },
                {
                    "data": [["Footer1.2", "Footer2.2", "Footer3.2", "Footer4.2"]]
                },
                {
                    "dataQuery": "footerData"
                }
            ]
        },
        {
            "type": "Text",
            "text": "This table shows how to combine two tables into one. This is useful when you want to include a different number of columns between header and table rows. Notice that the inner table has overridden the default layoutOptions in order to prevent drawing borders.",
            "style": "text"
        },
        {
            "type": "Table",
            "columns": [{}, {}],
            "headerRows": {
                "dataQuery": "headerData"
            },
            "components": [
                {
                    "type": "Table",
                    "columns": [{}, {}, {}, {}],
                    "style": {"layoutOptions": {}},
                    "rows": {
                        "dataQuery": "rowData"
                    }
                }
            ],
            "footerRows": {
                "dataQuery": "footerData"
            }
        },
        {
            "type": "Text",
            "text": "This table shows how to override column data for a row and header. Setting the data at the column level will override any data found in the referenced data element. This is useful when the first column in a report always contains the same data.",
            "style": "text"
        },
        {
            "type": "Table",
            "columns": [
                {
                    "headerData": ["New Column 1"],
                    "rowData": ["New Item", "New Item", "New Item"],
                    "footerData": ["New Footer 1"]
                }, 
                {}, {}, {}
            ],
            "headerRows": {
                "dataQuery": "headerData"
            },
            "rows": {
                "dataQuery": "rowData"
            },
            "footerRows": {
                "dataQuery": "footerData"
            }
        }
    ]
}