Time Period Table

Contains Table and Time Period Pickers

Model

{
    "type": "timeperiodtable",
    "actions": {},
    "dataSource": {
        "type": "function",
        "lib": "LibName"
    },
    "endtime": "2020-10-01T00:00:00.000Z",
    "maxDuration": "1h2m",
    "starttime": "2020-10-01T00:00:00.000Z",
    "table": {},
    "toolbars": {}
}
Field Description

actions

Optional property, used to implement action pipelines for selected trigger events. See the actions section in the widget documentation and see here for additional actions for the time period table.

dataSource

Optional data source in which the data and model for the widget can be loaded from.

endtime

Optional end time can be assigned to initialize the Time Pickers.

maxDuration

This property can be used to configure the maximum length of the time period in which data can be collected.

The duration value uses the same syntax as the offset part of relative time expressions

starttime

Optional start time can be assigned to initialize the Time Pickers

table

This can be used to directly access the table widget that is contained within the time period table widget. See the Table widget for details.

toolbars

Optional property to add, customise and hide toolbars

Actions

The actions property for the time period table can be defined on both the widget level and within the table property. It is used to invoke action pipelines for specific trigger events.

Action Hooks

In addition to the general action hooks for all widgets, the time period table widget also supports the following action hooks:

onClick

The onClick action hook is invoked when a cell in the time period table is clicked. This action hook must be defined in the table.schema property.

{
    "table": {
        "schema": [
            {
                "name": "firstname",
                "title": "First Name",
                "actions" : {
                    "onClick": {
                        "type": "notify"
                    }
                }
            }
        ]
    }
}

onSave

The onSave action hook is invoked when the 'Save' button is clicked. If the 'Save' button has not already been added to the widget toolbar, then defining an onSave action will display the button automatically.

When the onSave action hook is invoked, all rows of the time period table will be included in the message payload, unlike the payload for the onSumbit action hook which only contains the selected table rows.

{
    "actions": {
        "onSave": {
            ...
        }
    }
}

onSelect

The onSelect action hook is invoked when a row in the time period table is selected. The message payload of this action hook will contain all of the information from the selected row. If options.multi is set to true, then only the most recent row selection will be shown in the message payload.

{
    "table": {
        "actions": {
            "onSelect": []
        }
    }
}

onSelectionChanged

The onSelectionChanged action hook is invoked every time that the selected rows are changed. If options.multi is set to true, then all of the selected rows are added to the message payload.

{
    "actions": {
        "onSelectionChanged":
    }
}

onSubmit

The onSubmit action hook is invoked when clicking the 'Submit' button. If an onSubmit action hook is defined, the 'Submit' button will be added to bottom toolbar of the widget automatically. Clicking the 'Submit' button will only send the selected rows of the time period table to the message payload. This is unlike the payload of the onSave action hook which contains information for all of the rows in the time period table.

{
    "actions": {
        "onSubmit": {
            ...
        }
    }
}

Receive messages (Send Topics)

The time period table can receive messages from other widgets. This widget only supports the general refresh and update topics.

DataSource

Refer to the generic widget page for a description of the general principles governing the treatment of data retrieved from a dataSource.

If the dataSource property is defined as an object, the message returned from the data is usually determined by whether the type field matches the widget type. For further information, see the DataSource section in the widget documentation. If the type field in the dataSource does not match the widget type, then the starttime and endtime fields are checked in the payload and merged into the model. If the message topic is not "selectRows" then the data field in the payload is also checked for in the payload and if defined, will be merged to the model.

If the type, starttime and endtime fields are not defined, then no fields from the payload are merged to the model. This merging behavior is also observed if the message payload is defined as a string.

DataSource Pipeline

DataSource Examples

The following sections provide examples of the message payload returned by the dataSource on the Time Period Table widget and define the expected merge behavior when applied to the model.

Message payload defined as an object where the type matches the widget type

Consider an example where the dataSource on a time period table widget returns the following message payload. In this example, the type defined in the payload, matches the widget type and so, any matching model properties from the payload will be merged to the model. For this example, the options, starttime and endtime fields will be merged to the model.

{
    "payload": {
        "type": "timeperiodtable",
        "options": {
            "multi": false,
            "pagination": true,
            "pageSize": 20
        },
        "starttime": "*-1d",
        "endtime": "*-12h"
    }
}

Message payload is defined as an object where the type field is not specified but the data, starttime or endtime field is included in the payload

In the following examples, there is no type defined in the payload and so the content of the returned message payload is determined by whether the data, starttime and endtime fields are defined. There are two cases to consider here:

  • In the first case, the starttime, endtime and data fields are all defined in the message payload. The message topic is defined as "setTimeSpan" and so, all three of the fields will be merged to the model. The data field in the payload is merged to the table.data property in the model.

    {
        "topic": "setTimeSpan",
        "payload": {
            "starttime": "*-12h",
            "endtime": "*",
            "data": [
                {
                    "firstname": "Louwrens",
                    "lastname": "Wagenaar"
                },
                {
                    "firstname": "Evert-Jan",
                    "lastname": "Tijhof"
                },
                {
                    "firstname": "Remco",
                    "lastname": "Bokhoven"
                }
            ]
        }
    }
  • In the second case, although the data, starttime and endtime fields are all defined in the message payload, the message topic is set to "selectRows" and so, only the starttime and endtime fields will be merged to the model.

    {
        "topic": "selectRows",
        "payload": {
            "starttime": "*-12h",
            "endtime": "*",
            "data": [
                {
                    "firstname": "Louwrens",
                    "lastname": "Wagenaar"
                },
                {
                    "firstname": "Evert-Jan",
                    "lastname": "Tijhof"
                },
                {
                    "firstname": "Remco",
                    "lastname": "Bokhoven"
                }
            ]
        }
    }

Message payload defined as an object but the type, starttime and endtime fields are not specified

If the type field as well as the data, starttime and endtime fields are not defined in the message payload, then no fields from the payload are merged into the model.

{
    "payload": {
        "captionBar": false,
        "actions": {
            "onSelect": {
                "type": "send",
                "to": "debugger"
            }
        }
    }
}

Toolbars

By default, the time period table widget has mutiple toolbars configured. This widget also supports custom toolbars. For information on configuring custom toolbars, see the toolbars section in the widget documentation.

Tools

The following tools have a default implementation in the time period table widget:

Icon Name Description

Filter Btn

Filter

Shows/hides the filter field in each column of the time period table.

Page Control

Page Control

This tool can be used to navigate between pages and to change the number of rows in the time period table.

Refresh Btn

Refresh

Refreshes the widget

Save Btn

Save

Writes the data from the time period table to the system. See the onSave action hook.

Search Btn

Search

Shows/hides the search input box. Used to search for table entries.

Selected Rows Indicator

Selected Rows Indicator

When the options.multi property is set to true, this indicates the number of rows selected.

Spacer

This tool is used to specify the spacing between tools in the widget toolbar. It can be customised using the style and styleByTheme fields.

Submit Btn

Submit

Writes data from selected rows to the system. See the onSubmit action hook in the action section above.

Time Period Btn

Time Period

Configuration for the time period to retrieve data to populate the time period table.

Visible Rows Indicator

Visible Rows Indicator

Indicates the number of rows visible in the time period table.