How to configure tables

This guide describes how to configure tables and how to make use of the table related operations offered by the platform.

The platform has support for DITA simpletable, CALS, XHTML and other table definitions. This article describes support for DITA simpletable, CALS and XHTML. For other table definitions see our guide on how to configure custom table definitions.

DITA simpletable is part of the DITA support add-on and can therefore be used when this add-on is used in the application.

To use CALS tables, make sure to select the CALS table support add-on while creating or upgrading an application. To use XHTML tables, make sure to select the XHTML table support add-on while creating or upgrading an application.

Fonto Editor supports the use of multiple table standards in one editor instance.

Configure the schema experience

The first thing to do is to configure the schema experience for the chosen table standard(s). Every standard exposes a configureAs*TableElements function. This function takes care of configuring the elements used by the chosen table standard. Depending on the table standard chosen, the function accepts additional options

DITA Simpletable

To configure simpletable table elements, use the configureAsSimpletableTableElements function. The options object as second argument is not required. For a full list of available options, refer to the configureAsSimpletableTableElements documentation and to the DITA support add-on documentation.

A simple example of the usage of the configureAsSimpletableTableElements function:

JavaScript

configureAsSimpletableTableElements(sxModule);

CALS

To configure CALS table elements, use the configureAsCalsTableElements function. This function requires the table.localName option to be set. Therefore, the option object for this function is required. For a full list of available options, refer to the configureAsCalsTableElements documentation and the CALS table support add-on documentation.

JavaScript

configureAsCalsTableElements(sxModule, {
    table: {
        localName: 'table'
    }
});

XHTML

To configure XHTML table elements, use the configureAsXhtmlTableElements function. The options object as second argument is not required. For a full list of available options, refer to the configureAsXhtmlTableElements documentation and the XHTML table support add-on documentation.

JavaScript

configureAsXhtmlTableElements(sxModule);

Configure other element properties

Configuring tables with the configureAs*TableElements functions will only configure the absolute minimum of configuration options for the elements being configured. To configure additional properties for elements found in these tables, use the configureProperties function.

The configureProperties can configure any property for any given element. However, due to system limitations, the defaultTextContainer option is the only option which needs to be configured via the configureAs*TableElements function.

This is a short example of configuring simple tables for a DITA application:

JavaScript

configureAsSimpletableTableElements(sxModule, {
    stentry: {
        defaultTextContainer: 'p'
    }
});

configureProperties(sxModule, 'self::simpletable', {
    blockHeaderLeft: [
        createMarkupLabelWidget()
    ],
    markupLabel: 'simple table',
    tabNavigationItemSelector: 'self::stentry'
});

Configure a table masthead tab

Before a user can start inserting and editing tables, there needs to be a way to trigger the operations which perform these actions. It is recommended to group the table-related operations in a single masthead tab. A table insert can also be added to the start or insert tab. Most table-related operations also have a variant specifically meant for use in a contextual menu. These operations are prefixed with contextual-.

For more information about configuring a masthead for an application, refer to the guide on creating a masthead.

Table standard specific operations

The only operations specific to a table standard are the insert operations. The platform offers operations for inserting these specific table standards, with CALS being the only exception. This is caused by the local name of the "table" element being configurable. To insert a simpletable use the simpletable-table-insert operation. To insert an XHTML table, use the xhtml-table-insert operation.

To insert a CALS table, implement an application specific cals-table-insert operation. This should look something like this:

JSON

{
    "cals-table-insert": {
        "label": "CALS table",
        "description": "A generic CALS table",
        "icon": "table",
        "initialData": {
            "childNodeStructure": [
                "table", // <- change this value according to the used schema
                [
                    "tgroup"
                ]
            ],
            "rows": 1,
            "columns": 1
        },
        "steps": [
            {
                "type": "operation/table-insert"
            }
        ]
    }
}

Table toolbar

To configure the table toolbar, click the following link.

Table contextual menu

The table context menu is used by default, and cannot be turned off. The contextual menu features all operations that can be expected such as adding and removing row and column, merging cells and splitting cell operations. Configured contextual operations for tables or their sub-elements go in the `more` menu as below.

A screenshot of the default contextual menu for tables

Table widgets

It is possible to use tables faster and easier thanks to table widgets. Here are 4 kinds of table widgets:

  • Insertion widget: This can be used to add new rows or columns at a certain place by clicking plus icons around a table.

  • Highlighting widget: It is possible to run some table operations for each column or row in a highlight menu. A highlight menu will show up when a highlighting widget is clicked. Besides that the corner highlighting widget can be used to select the entire table.

  • Row widget: An icon widget can be added before each row by using createIconWidget. Row widgets are linked to the row elements of the table.

  • Column widget: Multiple column widgets can be added before each column. Column widgets are linked to the column specification element of the table or the cells in the first row in cases where the table definition does not support column specification elements. When a column specification element is missing or there are merged cells in the first row, the number of columns is more than the number of the context nodes of the column widgets. In this case, the column widgets will not be rendered at all. All widgets are supported, however the columnBefore widget area is limited, so not every combination or configuration will look right as a result.

A screenshot of a table row being selected, and its contextual menu

The table widgets can be configured via the configureAs*TableElements function. Please check here for more information.

Collapsible Tables

Tables can be configured to be collapsible. This is useful in cases when you either have a lot of tables or very large tables that are impacting the overall editor performance. Collapsible tables can offer a huge performance boost, as they are evaluated Just-In-Time, which means that they are only evaluated when they are not collapsed.

Tables can be configured via the configureAs*TableElements functions for example configureAsCalsTableElements. Making a table collapsible can be done using the properties isCollapsibleQuery and isInitiallyCollapsedQuery:

  • isCollapsibleQuery is an XPath expression which determines whether or not a table has the ability to be collapsed. This is optional and defaults to false().

  • isInitiallyCollapsedQuery is an XPath expression which determines whether a table that has the ability to be collapsed should start off as collapsed on initial load. This is optional, and defaults totrue(). Note: This will only come into effect when isCollapsibleQuery returns true for the configured table.

$rowCount and $columnCount are helper variables which can optionally be used in isCollapsibleQuery and isCollapsibleQuery XPath expressions. These variables make it easier to configure collapsible tables, $rowCount represents the total number of rows inside the configured table and $columnCount represents the total number of columns inside the configured table.

Examples:

This configuration enables tables with more than 5 rows or 5 columns to have the ability to be collapsed and collapses all tables by default:

JavaScript

configureAsTableElements(
	sxModule,
 	{
 		table: {
			localName: 'table'
 		},
		isCollapsibleQuery: '$rowCount > 5 or $columnCount > 5',
		isInitiallyCollapsedQuery: 'true()'
	},
	tableDefinition
);

This configuration enables tables with more than 5 rows or 5 columns to have the ability to be collapsed, however only tables with more than 10 rows or 10 columns start off initially as collapsed:

JavaScript

configureAsTableElements(
	sxModule,
 	{
 		table: {
			localName: 'table'
 		},
		isCollapsibleQuery: '$rowCount > 5 or $columnCount > 5',
		isInitiallyCollapsedQuery: '$rowCount > 10 or $columnCount > 10'
	},
	tableDefinition
);

Please note that Inclusions do not support collapsible tables