Image

This widget can be used to show one single image using a URL, Base64 encoded image or embedded icons from widgets, tools and models.

Model

The following properties can be defined for the Image widget. The table below provides more information about each of the properties.

{
    "type": "image",
    "actions": {},
    "captionBar": {},
    "dataSource": {},
    "dragSource": {},
    "dropTarget": {},
    "id": "imageWidgetID",
    "image": {},
    "layout": {},
    "name": "imageWidget",
    "options": {},
    "toolbars": {},
    "tooltip": {}
}
Field Description

type

Widget type, in this case "image"

actions

Property used to implement action pipelines for specific trigger events. See the Actions section below.

captionBar

Optional property used to configure the widget caption bar. Alternatively, set this property to false to hide the caption bar for this widget. Default is true.

dataSource

Property used to retrieve data from the system. See the DataSource section below.

dragSource

Optional property used to allow dragging from the widget. See here for more information about configuring the widget as a drag-source.

dropTarget

Optional property used to handle drops from a drag-source. For more information on configuring the widget as a drop-target, see here.

id

Widget identifier, can be customised but must be unique in the compilation. If this property is not defined, then it will be automatically assigned when the widget is created.

image

Property used to define the image configuration. See the Image section for more details.

layout

Property used to configure the size and position of the widget in the compilation.

name

Optional property used to assign a name to the widget, displayed in the widget caption bar if it is enabled.

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.

tooltip

Optional property to define a custom tooltip which will be shown when hovering over the widget.

Actions

The actions property of the Image widget model can be used to implement action pipelines for specific trigger events, defined using lifecycle and action hooks. Each of thes hooks can contain a single action or series of actions in a pipeline.

Action Hooks

In addition to the general widget lifecycle hooks, the Image widget supports the following action hook:

onClick

The onClick action hook is invoked when the widget is clicked. Note that the action hook will only be invoked if the release of the mouse click occurs within the widget.

Example opening a link:

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

DataSource

The dataSource property can be used to retrieve data from the system or to initialise the widget model. Refer to the generic widget documentation for information regarding the general principles governing the treatment of data received from a dataSource.

If the message payload in the dataSource property for the Image widget is defined as an object, then the message merged to the payload is dependent on the presence of the type field in the payload.

  • If the type field in the message payload matches the widget type, then any fields in the payload which match the model properties of the Image widget will be merged to the model.

  • If the type field does not match the widget type or is not defined in the message payload, then the image field will be checked for in the payload and will be merged to the model if defined.

  • If the type and image fields are not defined in the message payload, the no fields will be merged to the model.

If the message payload is defined as an array or a string, then no changes will be merged to the model.

image-datasource-pipeline

DataSource Examples

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

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

If the dataSource of the image widget returns the following payload, where the type defined in the object matches the widget type, any matching model properties in the payload will be merged to the model. In this example, the captionBar, options and layout fields are merged.

{
    "payload": {
        "type": "image",
        "captionBar": false,
        "options": {
            "size": "cover"
        },
        "layout": {
            "static": true,
            "h": 15,
            "w": 15,
            "x": 20,
            "y": 0
        }
    }
}

Message payload, defined as an object, where the type field is not specified but the image field is defined

In the following example, where the type property is not defined in the message payload returned by the dataSource, the image field is checked for in the payload. Since the image property is defined, it will be merged to the model whereas the other defined properties are not.

{
    "payload": {
        "captionBar": {
            "hidden": false,
            "title": "Image loaded from URL"

        },
        "image": {
            "type": "url",
            "url": "./assets/backgrounds/index_dark.jpg"
        },
        "options": {
            "size": "cover"
        },
        "layout": {
            "static": true
        }
    }
}

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

If the message payload returned by the dataSource on the image widget does not define a type property and does not contain the image field, then no fields from the payload will be merged to the model.

{
    "payload": {
        "layout": {
            "static": true,
            "x": 0,
            "y": 0,
            "w": 15,
            "h": 15
        },
        "captionBar": false
    }
}

Image

The image property is used to define the image configuration for the widget. The available fields in this property are dependent on the value assigned to the type field. The following types are supported:

Base64

{
    "image": {
        "type": "base64",
        "base64": "",
        "mimeType": ""
    }
}
Field Description

base64

Base64 encoded string.

mimeType

Defines the MIME type of the image.

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

Emoji

{
    "image": {
        "type": "emoji",
        "emoji": ""
    }
}
Field Description

emoji

Specify which emoji to display in the Image widget.

Model Class

{
    "image": {
        "type": "model-class",
        "modelClass": ""
    }
}
Field Description

modelClass

Defines which model class icon to display in the Image widget.

Tool

{
    "image": {
        "type": "tool",
        "toolSubType": "",
        "toolType": ""
    }
}
Field Description

toolSubType

Specifies which tool subtype icon to display in the Image widget. An overview of the icons for different tools can be found here

toolType

Defines the tool type.

URL

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

url

URL for a single image to be displayed in widget

Widget

{
    "image": {
        "type": "widget",
        "widgetType": ""
    }
}
Field Description

widgetType

Specifies the widget icon to be displayed in the Image widget. Each of the widgets in WebStudio have a corresponding icon.

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.

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 Tool Name Type SubType Description

Refresh Btn

Refresh

button

refresh

Used to refresh the widget.

Spacer

spacer

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

Tooltip

The tooltip property is used to define a custom tooltip which is displayed when hovering over the Image widget.

{
    "tooltip": {
        "type": "fixed",
        "text": "Custom tooltip"
    }
}
Name Description

type

This property should be set to "fixed" to display the tooltip.text when hovering over any point in the content area of the widget.

text

Defines the custom text to display in the tooltip

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 image.base64 field in the model will be updated. In case the payload is a JSON string or JSON object the values of the fields image.url, image.base64 and image.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 image.url in the model.

Receive messages (Send Topics)

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