Button

This is a generic button widget, used to trigger an action pipeline when clicked. In its simplest form, it is very similar to a text widget, but has some additional behavior to provide visual feedback when it is clicked.

Model

{
    "type": "button",
    "actions": {
        "onClick": {
            "type": "notify",
            "title": "Button was clicked"
        }
    },
    "disabled": false,
    "icon": {
        "icon": "☑️",
        "alignment": "leading"
    },
    "label": "Click me",
    "options": {
        "style": {
            "fontSize": "20px",
            "fontWeight": "bold"
        }
    },
    "toolbars": {}
}
Field Description

actions

Specify a click handler to execute when the button is interacted with. See the Actions section below for more information.

disabled

Set to true to grey out the button and ignore click actions. Default is false

icon

Optional button icon.

label

Optional label text. The label can be assigned a string value or it can be a composite property allowing the text and style to be configured. To apply label specific styling, the property value is declared as follows:

{
    "label": {
        "text": "Click me",
        "style": {
            "color": "white"
        },
        "styleByTheme": {
             "light": {
                "color": "blue"
            }
        }
    }
}

The configuration of the button icon and label follow the same logic as the dragPreview with "icon-label" type selected.

toolbars

Add, customise or hide toolbars. See the Toolbars section below

Actions

The actions property can be used to define action pipelines for specific action hooks.

Action Hooks

In addition to the generic widget actions, the button widget also supports the following action hook:

onClick

The onClick action hook is invoked when a user clicks anywhere on the button. Note that the action pipeline is executed on the release of the mouse button rather than on the "mouse-down" event. If the mouse pointer is moved outside the widget before the button is released, the onClick action is not triggered. The message payload is initialized to the label text.

Example opening a link:

{
    "type": "button",
    "label": "Click here",
    "actions": {
        "onClick": {
            "type": "openLink",
            "message": {
                "payload": {
                    "url": "https://www.lipsum.com"
                }
            }
        }
    }
}

Receive messages (Send Topics)

The button widget can receieve messages from other widgets. This widget only supports the generic topics refresh and update.

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 by the data is determined by the type field. However, if the type field does not match the widget type, then the label field is checked in the payload and merged into the model.

If these fields are not specified, then the paylaod is assigned to the label field.

The button widget implements a check to validate the work model. This check is performed to all cases where the dataSource is applied and implements the following logic to the label property once it has been assigned.

If the label property is:

  • an object:

    • if the label.text, label.style or label.styleByTheme properties have been specified, these are used as the label object

    • otherwise, the label object is 'stringified' and assigned to the label

  • a boolean: the label is assigned the string "true" or "false"

  • an array: the array is 'stringified'

  • a number of string: this value will be assigned directly to the label

Toolbars

The button widget can have one or more custom toolbars. By default, the toolbars on the button widget are hidden. To add custom toolbars, see the toolbars section in the widget documentation.

Tools

The following tools have a default implementation for the button widget:

Icon Name Description

Refresh Btn

Refresh

Refreshes the widget.

Spacer

This tool defines the spacing between the tools in the widget toolbar.