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 property. When the type field in the payload matches the widget type, any matching model properties defined in the payload will be merged to the model. However, if the type property does not match the widget type, then the label property is checked for in the payload and merged into the model.

If the label property is not defined, then the whole payload is assigned to the label property.

DataSource Pipeline

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 or string: this value will be assigned directly to the label

DataSource Examples

The sections below demonstrate examples of the merge behavior of the message payload returned by the dataSource on the Button widget.

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

Consider the following example containing the message payload returned by the dataSource on a button widget. As the type property matches the widget type, any matching model properties from the payload will be merged to the model. In this example, the label and captionBar fields will be merged into the work model.

{
    "payload": {
        "type": "button",
        "label": {
            "text": "Click Button Here",
            "style": {
                "color": "red",
                "fontSize": "14px"
            }
        },
        "captionBar": {
            "hidden": false,
            "title": "Button Widget"
        }
    }
}

Message payload defined as an object where the type field does not match the widget type but the label field is specified

If the dataSource returns the following message payload, where the type does not match the widget type, then only the label property will be merged with the model.

{
    "payload": {
        "type": "text",
        "label": "Click Button",
        "captionBar": false,
        "options": {
            "color": "yellow",
            "fontSize": "30px"
        }
    }
}

Message payload defined as an object where the type and label fields are not included

If the dataSource on the button widget returns the following message payload, where neither the type or label fields are defined, the whole payload is assigned to the label property in the model.

{
    "payload": {
        "captionBar": false,
        "options": {
            "color": "yellow",
            "fontSize": "30px"
        }
    }
}

Similarly, if the message payload is a string or array, then the whole payload is merged to the label property in the work model.

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.