Image

This widget can be used to show one single image based on a URL or Base64 encoded image and mimeType. The url in the model is leading.

Model

{
    "type": "image",
    "actions": {},
    "base64": "",
    "dataSource": {},
    "mimeType": "",
    "options": {},
    "toolbars": {},
    "url": ""
}
Field Description

actions

In addition to the default lifecycle actions, the image widget supports additional action hooks.

base64

Base64 encoded image file. If using this property, the url property is not required. Used in conjunction with the mimeType property.

dataSource

Optional property used to retrieve data from the system

mimeType

Configure the MIME type of the image. See the suitable MIME types below. Used in conjunction with the base64 property.

options

Property used to configure the widget options. See the options section below for more information.

toolbars

Add, hide or customise toolbars. See the Toolbars section for more details.

url

URL for a single image to be displayed in widget. If the url property is defined, the base64 property is not required.

Model using URL

{
    "type": "image",
    "url": ""
}

Model using Base64 encoded image

{
    "type": "image",
    "mimeType": "image/png",
    "base64": ""
}

The following MIME types are considered safe for use on web pages and supported by modern web browsers:

File format MIME type File extension(s)

Animated Portable Network Graphics

image/apng

.apng

Bitmap file

image/bmp

.bmp

Graphics Interchange Format

image/gif

.gif

Microsoft Icon

image/x-icon

.ico, .cur

Joint Photographic Expert Group image

image/jpeg

.jpg, .jpeg, .jfif, .pjpeg, .pjp

Portable Network Graphics

image/png

.png

Scalable Vector Graphics

image/svg+xml

.svg

Options

In addition to the generic options, the image widget supports the following options:

{
    "options": {
        "size": "contain"
    }
}

Possible values for size:

value description

contain

Auto size with aspect ratio. (default)

100px

Width 100 pixels and auto height with aspect ratio.

100px 50px

Width of 100 pixels and height of 50 pixels.

100% 50%

Width of 100 percentage and height of 50 percentage.

cover

Fit with aspect ratio.

Update Behavior

The update logic of the widget accepts a payload which is a string or a JSON object. In case the payload is a string the widget checks whether the string is a JSON string or base64 string. In case the string is base64 encoded, the base64 field in the model will be updated. In case the payload is a JSON string or JSON object the values of the fields url, base64 and mimeType will be used to change the fields in the model accordingly. In case the payload input is neither a base64 encoded or JSON string the value will be used to update the url in the model.

Actions

Supported action hooks:

  • onClick: when user clicks on the image.

Example opening a link:

{
    "type": "image",
    "name": "Random Image",
    "url": "https://source.unsplash.com/random",
    "actions": {
        "onClick": {
            "type": "notify",
            "text": "Image clicked!"
        }
    }
}

DataSource

If the dataSource property is defined as an object, the message returned by the data is usually determined by the type field as explained here. If the type field does not match the widget type, then the mimeType, base64 and url fields are checked in the payload and merged into the widget model.

Toolbars

The image widget supports multiple custom toolbars. For information on configuring custom toolbars, see the toolbars section in the widget documentation.

Tools

The following tools have a default implementation on the image widget:

Icon Name Description

Refresh Btn

Refresh

Used to refresh the widget.

Spacer

This defines the spacing between tools on the widget toolbar. It can be customised using the style and styleByTheme properties.