Diagrams

The diagrams functionality is currently in preview and some of the model and feature descriptions may change.

This widget is used to show graphics, typically representing processes for which inmation is ingesting data. These are composed of static and animated shapes. Animations are driven by values received from the system. Actions, such as click-handlers, can be triggered from within diagrams to update system values or interact with other widgets in the compilation.

The diagrams widget is quite different from most others in WebStudio, which are defined by directly entering JSON model configuration. A dedicated vector graphics editor is provided for creating diagram models. Refer to the Getting Started with Diagrams section for an introduction on how to use it.

Model

{
    "type": "diagrams",
    "actions": {},
    "dataSource": {},
    "diagramsData": "data:image/svg+xml;base64, ...",
    "diagramsOptions": {},
    "diagramsTheme": "dark",
    "pages": [
        {
            "name": "Page-1",
            "id": "APtCaXEjoOY_D9RLUr6H",
            "items": {},
            "pageData": "PHN2ZyB4bWxucz0ia..."
        },
        {
            "name": "Page-2"
        }
    ],
    "state": {
        "activePageID": "APtCaXEjoOY_D9RLUr6H"
    },
    "toolbars": {}
}
Field Description

actions

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

dataSource

Optional property, used to load the content of the widget from the system. See the Data Sources section below for more details.

diagramsData

Base64 encoded static graphics data generated using the diagrams editor. This field should not be edited manually.

diagramsOptions

Optional additional configuration properties for the diagrams editor. See the Diagrams Options section below for more information.

diagramsTheme

Set the theme of the diagrams editor. Options are dark (default) and kennedy.

pages

Array of one or more pages within the diagram. Refer to the pages section for more details.

state

Keeps track of the selected page in the widget. This field is typically not manually edited.

activePageID

unique id of the currently selected page.

toolbars

Add, hide or customise toolbars on the diagrams widget. See the toolbars section below.

Pages

Each diagram instance can contain one or more pages, the contents of which are defined using the diagram editor. It should therefore rarely be necessary to directly edit the content of the pages property. The animations, rules and actions for each page are defined in the elements of the pages list.

Refer to the Multiple Pages and Navigation section for a brief overview of page handling. Only one page is ever displayed at a time; the selected one is tracked in the state.activePageID property.

The active page can be changed/set from the outside of the widget by using a send action or from within the diagram page using a setActiveDiagramsPage action in an onClick action pipeline, for example.

{
    "pages": [
        {
            "id": "y5_xIqt3Bibsnob3wonx",   // auto-generated unique page ID
            "name": "Page-1",               // Page name
            "items": {                      // List of shapes and groups with their data sources and animations
                "fuJ-W_87pS2UvVLAmsRe2": {  // auto-generated unique group ID
                    "type": "group",        // Item type
                    "name": "valve",        // Item alias
                    "animations": [         // Animations to apply to the group
                        {
                            "type": "fill", // Animation type
                            "rules": [      // Match rules
                                {
                                    "color": "green",   // Match output (set the fill to green)
                                    "type": "equal",    // Rule type (check if data source equals value)
                                    "value": 2          // comparison value
                                }
                            ],
                            "shapes": [     // List of shapes in the group to apply the animation to
                                "leftTriangle", // Aliases of target shapes
                                "rightTriangle"
                            ]
                        }
                    ],
                    "dataSource": {         // Data source for the animation
                        "path": "/System/Core/Simulation/Process Diagram/Valve02/Status",
                        "type": "subscribe"
                    }
                },
                "fuJ-W_87pS2UvVLAmsRe3": { // Auto-generated shape id
                    "type": "shape",
                    "name": "closeButton",
                    "actions": {
                        "onClick": {       // Action to apply when the shape is "clicked"
                            "item": {
                                "p": "/System/Core/Simulation/Process Diagram/Valve02/Control",
                                "v": 1
                            },
                            "type": "write"  // Perform write action to set the target object value
                        }
                    }
                } // ...
            },
            "viewData": "PHN2ZyB4bWxucz0iaHR0cDov... " // View specific graphics data
        }
    ],
}
Field Description

id

Unique ID for the page, generated by the graphics editor.

name

Pages are assigned default names of the form "Page-n" by the diagram editor but these can and are recommended to be changed to names that reflect the purpose of the page.

items

The items object maintains a list, keyed on unique IDs assigned by the diagram editor. Each entry defines dataSources, animations, and actions that apply to the item, which correspond to atomic shapes or groups of shapes on the page.

actions

Currently only the onClick action can be configured. Named actions at widget and compilation level can be invoked from the onClick pipeline, but named actions cannot at present be defined at shape level.

animations

List of one of more animations to apply to a shape or multiple shapes in a group. Animations are triggered whenever data, subscribed to in the dataSource, is updated. When a source value is updated, the animation rules are evaluated and target fields are set for the first matching rule encountered.

The animation fields are typically set inside a matching rule. Some also allow defaults to be provided at animation level. This default animation will be applied if no rules are defined or none of the defined rules are matched.

type

Several animation types are supported, each of which require their own parameters to be configured. The list below highlights the supported animation types:

rules

List of rules evaluated in sequence until one returns "true". At this point the execution stops and the animation attributes in that rule are applied to the shape. Rules are triggered whenever the value of a subscribe dataSource changes. The rule types are the same as those provided in table and tree widgets.

With the exception of match rules, all rules have a single input which is supplied by the dataSource. If there are multiple values defined in the data source, the key fields must be defined to name them in the message payload. In the rule, the name parameter must also be set to indicate which of the available values to use as the rule input. Refer to the dataSource property below to see this in action.

shapes

This property only applies to grouped shapes and is set at the group level. It should contain the names of all the shapes within the group to which the animation needs to be applied. For example:

{
    "type": "group",
    "name": "valve",
    "animations": [
        {
            "type": "fill",
            "shapes": [
                "leftTriangle",
                "rightTriangle"
            ],
            "rules": [
                {
                    "color": "green",
                    "type": "equal",
                    "value": 2
                }
            ]
        }
    ],
    "dataSource": {
        "path": "/System/Core/Simulation/Process Diagram/Valve02/Status",
        "type": "subscribe"
    }
}

dataSource

Each item in the items array can define a dataSource used to set shape attributes and trigger animations with information from the system. A single read or subscribe actions or an array of actions in a pipeline can be defined. In the latter case, actions must specify a key field allowing the values to be individually referenced.

Consider the example below in which a displayText animation is used to update a shape’s text value to show a tag value and units of measure configured in the system.

{
    "type": "shape",
    "name": "levelDisplay",
    "dataSource": [
        {
            "type": "subscribe",
            "key": "level", // Assign the value to the payload field called "level"
            "path": "/System/Core/Simulation/Process Diagram/Tank01/Level"
        },
        {
            "type": "read",
            "key": "uom", // Assign the units to the payload field called "uom"
            "path": "/System/Core/Simulation/Process Diagram/Tank01/Level.OpcEngUnit"
        }
    ],
    "animations": [
        {
            "type": "displayText",
            "text": {
                "field": "level" // Read the text from the level field in the payload
            },
            "engUnit": {
                "field": "uom"
            },
            "numberOfDecimals": 1, // The decimals are explicitly set
            "rules": [
                {
                    "type": "range",
                    "range": {
                        "from": 0
                    },
                    "name": "level" // Tell the rule which field to get its input from.
                }
            ]
        }
    ]
}

Some things to observe from this example:

  • Use of key fields: Data source output from the read and subscribe actions are assigned to payload fields called "level" and "uom" respectively, due to the presence of respective key fields.

  • Animation property field assignments: The animation input fields like text and engUnit are not assigned a value directly, but instead are "redirected" to get their values from fields in the dataSource message payload

  • Combine with direct assignments: In the example, the numberOfDecimals could also be read from the system by adding another read action to the dataSource, but the example shows that a combination of both is possible.

  • Rule name field: Since the message payload sent to the rules now contains an object with fields, the rule needs to be told where to get the rule value from. The name property is used to tell the rule where to source the comparison value from.

name

Items can be given names so they don’t need to be referenced using the assigned shape IDs

type

The type is automatically assigned in the graphics editor. This will typically be either "shape" or "group".

viewData

Base64 encoded SVG for the page. This is generated by the diagram editor and should not be manually changed.

Animations

The animations property can be defined for individual objects or a group of multiple objects. This property implements specific behavior, related to defined rules, triggered when the data retrieved from the dataSource updates. When the source value changes, the animation rules are evaluated and the target fields will be updated using the first matching rule.

{
    "animations": [
        {
            "type": "<ANIMATION_TYPE>",
            "rules": [
                {
                    "type": "equal",
                    "value": 0,
                    ...
                },
                {
                    "type": "equal",
                    "value": 1,
                    ...
                }
            ]
        }
    ]
}

Be sure to take a look at the item dataSource property for an explanation on how to source multiple input values from the system when configuring animations.

Some animation fields need to be assigned static values, while others may be read from the system by using a dataSource.

Animation properties that can be dynamically assigned from a data source value are indicated below using a 🔗 superscript.

The animations property supports several animation types, each of which requires their own set of configurable parameters. We will explore each of these animation types in the sections below.

The "blink" animation can be used to oscillate the shape stroke and/or fill colors between two values. This animation supports the following animation fields:

  • strokeColor and altStrokeColor: These parameters are used to configure line/stroke colors to use for the blink on/off cycles.

  • fillColor and altFillColor: Used to set the fill colors to use for the blink on/off cycles.

  • interval: This is the interval between the on and off cycles in milliseconds. The minimum value is 200 milliseconds.

{
    "animations": [
        {
            "type": "blink",
            "rules": [
                {
                    "type": "range",
                    "range": {
                        "from": 80,
                        "to": 100
                    },
                    "strokeColor": "red",
                    "altStrokeColor": "green",
                    "fillColor": "transparent",
                    "altFillColor": "darkGrey",
                    "interval": 2000
                }
            ]
        }
    ]
}

If the rules property is not defined, then default behavior for the strokeColor, altStrokeColor, fillColor and altFillColor parameters can be defined at the animation level and will always be applied.

"displayText"

The "displayText" animation is used to assign the output to the text content of a shape. It supports the following animation fields:

  • text🔗: Defines the text to be displayed. This parameter is almost always tied to a dataSource value. Styling properties for the displayed text can also be configured when this field is defined as an object.

  • engUnit🔗: This parameter is used to configure the engineering units to append to the text. These units are typically assigned at animation level but can be overwritten in matching rules.

  • numberOfDecimals🔗: Defines the number of decimals to include in the value displayed. This parameter only applies if the text input is a number but will be ignored otherwise.

{
    "animations": [
        {
            "type": "displayText",
            "engUnit": " %",
            "rules": [
                {
                    "type": "range",
                    "range": {
                        "from": 0
                    }
                }
            ]
        }
    ]
}

If the rules property is not defined, then a default text value can be specified at the animation level and will always be displayed.

Whilst all shapes can contain text, they do not have a placeholder for it in the output, unless a default text value is assigned in the diagram editor. This is achieved by double-clicking on the shape. Currently, the placeholder MUST be created before applying the displayText animation for the configured parameters to be applied.

Implementing Style Properties:

The text field, defined as an object, can be used to configure styling properties for the displayed text. Consider the following example:

{
    "dataSource": [
        {
            "type": "passthrough",
            "message": {
                "payload": {
                    "textField": "Hello World"
                }
            }
        }
    ],
    "animations": [
        {
            "type": "displayText",
            "text": {
                "field": "textField",
                "styleByTheme": {
                    "dark": {
                        "color": "lightyellow"
                    },
                    "light": {
                        "color": "darkblue"
                    }
                }
            }
        }
    ]
}

Styling properties can also be defined in the dataSource and are implemented in the animations property for the displayText type using styleBindings. If defined, the styleBindings property will take precedence over both of the style and styleByTheme properties.

{
    "dataSource": [
        {
            "type": "passthrough",
            "message": {
                "payload": {
                    "textField": "Hello World",
                    "colorField": "green"
                }
            }
        }
    ],
    "animations": [
        {
            "type": "displayText",
            "text": {
                "field": "textField",
                "styleBindings": {
                    "color": "colorField"
                }
            }
        }
    ]
}

It is important to note that in the above example the animation fields text.field and text.styleBindings are not directly assigned a value, but instead are "redirected" to retrieve their value from fields defined in the message payload of the dataSource.

"fill"

The "fill" animation is used to configure the fill color of a closed shape. This animation supports the following parameters:

  • color: This parameter defines the fill color to apply to the shape when the rule condition is met.

{
    "animations": [
        {
            "type": "fill",
            "rules": [
                {
                    "type": "equal",
                    "value": 2,
                    "color": "green"
                }
            ]
        }
    ]
}

"flow"

The "flow" animation is used to generate a "marching ants" effect which indicate fluid flow. The animation applies to the stroke property of the shape it is defined on. This animation supports the following parameters:

  • flowColor and altFlowColor: This parameter defines the stroke colors used to animate the flow.

  • mode: This property can be used to configure the flow direction, which can be "normal", "reverse" or "stop"

{
    "animations": [
        {
            "type": "flow",
            "rules": [
                {
                    "type": "equal",
                    "value": 1,
                    "flowColor": "grey",
                    "altFlowColor": "darkGrey",
                    "mode": "stop"
                },
                {
                    "type": "equal",
                    "value": 2,
                    "flowColor": "lightBlue",
                    "altFlowColor": "darkBlue",
                    "mode": "normal"
                }
            ]
        }
    ]
}

"level"

The "level" animation is used to show the magnitude of a value as the fill height in a closed shape (at this stage, only vertical indicators are supported). This animation type supports the following fields:

  • min🔗: This is the level at which no fill is displayed in the shape.

  • max🔗: This is the level at which the shape is completely filled.

  • fill: This parameter defines the fill color assigned in the matching rule.

{
    "animations": [
        {
            "type": "level",
            "max": 100,
            "min": 0,
            "rules": [
                {
                    "type": "range",
                    "range": {
                        "to": 80
                    },
                    "fill": "darkBlue"
                },
                {
                    "type": "range",
                    "range": {
                        "from": 80
                    },
                    "fill": "red"
                }
            ]
        }
    ]
}

The fill property can also be defined at animation level; in the event that the rules property is not defined, the behavior defined at this level, will be implemented as the default.

"rotate"

The "rotate" animation can be used to set an object rotating. This animation supports the following animation fields:

  • mode: This field defines the direction of rotation for the shape. Supported values are "clockwise", "anti-clockwise" and "stop".

  • rpm: This is the number of revolutions per minute. Default value is 30.

{
    "animations": [
        {
            "type": "rotate",
            "rules": [
                {
                    "type": "equal",
                    "value": 1,
                    "mode": "clockwise"
                },
                {
                    "type": "equal",
                    "value": 2,
                    "mode": "anti-clockwise"
                }
            ]
        }
    ]
}

The rpm and mode properties can be defined at the animation level and will be implemented as the default behavior if the rules property is not defined.

"stroke"

The "stroke" animation is similar to the "fill" animation, except in this case, the stroke color is affected rather than the fill color. This animation supports the following animation types:

  • color: This parameter defines the stroke color to apply to the shape when the rule is matched.

{
    "animations": [
        {
            "type": "stroke",
            "rules": [
                {
                    "type": "equal",
                    "value": 1,
                    "color": "red"
                }
            ]
        }
    ]
}

The color property can also be defined at animation level. If the rules property is not defined, then the color will be implemented on the shape as the default.

Data Sources

The diagrams widget supports a dataSource allowing its content to be loaded from the system using an advanced endpoint for example. The return from the data source must be a valid model containing the following fields:

  • type: The type field must be set to "diagrams"

  • diagramsData and pages: Use the diagrams editor to create these.

The widget dataSource is not to be confused with page item data sources described above.

If the dataSource property is defined as an object, the content of the returned message payload which is merged to the model, is determined by whether the type field matches the widget type. If the type defined in the payload matches the widget type, then any matching model properties in the payload will be merged to the model. However, if the type field does not match the widget type, then the pages and diagramsData fields are checked for in the payload and merged into the widget model. In this case, the diagramsData must be a string.

However, if none of these fields are defined or the payload is an array, then the payload is assigned to the pages property.

DataSource Pipeline

DataSource Examples

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

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

Suppose that the dataSource on a diagrams widget returns the following message payload, where the type defined in the payload matches the widget type. In this case, any matching model properties from the payload will be merged to the model. In the following example, the captionBar, diagramsTheme and diagramsOptions fields will be merged to the model.

{
    "payload": {
        "captionBar": {
            "title": "Diagrams with DataSource",
            "hidden": false
        },
        "diagramsTheme": "kennedy",
        "diagramsOptions": {
            "zoomWheel": true
        }
    }
}

Message payload defined as an object where the type field is not included but the pages and/or diagramsData field is specified

Suppose that the dataSource on the Diagrams widget returns the following payload. In this case, the type field is not defined and so, the pages and diagramsData fields will be checked for in the payload and if defined, will be merged to the model. In the following example, only the pages field is defined and so this will be the only field from the payload merged to the model.

{
    "payload": {
        "pages": [
            {
                "id": "4oqqBT_8pbjiyZ514Z1l",
                "items": {
                    "9OMquJDDEAuckUJ0HrWc2": {
                        "type": "shape",
                        "dataSource": {
                            "path": "/System/Core/Simulation/Process Diagram/Valve02/Status",
                            "type": "subscribe"
                        },
                        "animations": [
                            {
                                "type": "rotate",
                                "rpm": 10,
                                "mode": "clockwise",
                                "rules": [
                                    {
                                        "type": "equal",
                                        "value": 2
                                    }
                                ]
                            }
                        ]
                    }
                },
                "name": "Page-1",
                "pageData": "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHhtbG5zOnhsaW5rPSJodHRwOi8vd3d3L              nczLm9yZy8xOTk5L3hsaW5rIiB2ZXJzaW9uPSIxLjEiIHdpZHRoPSIyMDFweCIgaGVpZ2h0PSIyMDFweCIgdmlld0JveD0iLTA                uNSAtMC41IDIwMSAyMDEiIHRoZW1lPSJkYXJrIj48ZGVmcy8+PGc+PGcgaWQ9ImNlbGwtOU9NcXVKRERFQXVja1VKMEhyV2MyI                j48ZWxsaXBzZSBjeD0iMTAwIiBjeT0iMTAwIiByeD0iMTAwIiByeT0iMTAwIiBmaWxsPSJyZ2IoMTgsIDE4LCAxOCkiIHN0cm9                rZT0icmdiKDI0MCwgMjQwLCAyNDApIiBwb2ludGVyLWV2ZW50cz0iYWxsIi8PHBhdGggZD0iTSAyOSAyOSBMIDE3MSAxNzEiIG                ZpbGw9Im5vbmUiIHN0cm9rZT0icmdiKDI0MCwgMjQwLCAyNDApIiBzdHJva2UtbWl0ZXJsaW1pdD0iMTAiIHBvaW50ZXItZXZl                bnRzPSJhbGwiLz48cGF0aCBkPSJNIDE3MSAyOSBMIDI5IDE3MSIgZmlsbD0ibm9uZSIgc3Ryb2tlPSJyZ2IoMjQwLCAyNDAsID                I0MCkiIHN0cm9rZS1taXRlcmxpbWl0PSIxMCIgcG9pbnRlci1ldmVudHM9ImFsbCIvPjwvZz48L2c+PC9zdmc+"
            }
        ]
    }
}

Message payload defined as an object where the type, pages and diagramsData fields are not specified

Suppose that the payload returned by the dataSource does not contain a type, pages or diagramsData fields, as seen in the example below, then no fields from the payload will be merged to the model.

{
    "payload": {
        "captionBar": {
            "title": "Diagram with DataSource",
            "hidden": false
        },
        "diagramsTheme": "kennedy"
    }
}

Diagrams Options

The diagramsOptions property can be used to implement draw.io options in the widget model editor. All of the available options can be found here.

{
    "diagramsOptions": {
        "colorNames": {
            "000000": "Black",
            "FFFFFF": "White"
        },
        "darkColor": "#DAE8FC",
        "defaultColors": [
            "none",
            "000000",
            "FFFFFF",
            "E6E6E6",
            "333333"
        ],
        "defaultEdgeLength": 80,
        "defaultFonts": [
            "Times New Roman",
            "Garamond",
            "Lucida Console"
        ],
        "defaultGridEnabled": true,
        "lightColor": "#B5739D",
        "presetColors": [
            "E6D0DE",
            "CDA2BE",
            "C3ABD0"
        ],
        "sidebarTitles": true,
        "sidebarTitleSize": 15,
        "sidebarWidth": 400,
        "thumbHeight": 25,
        "thumbWidth": 25
    }
}

Receive messages (Send Topics)

The diagrams widget can receive messages from other widgets. In addition to the generic message topics, the diagrams widget also supports the following topic:

setActiveDiagramsPage

A send action with the topic set to "setActiveDiagramsPage" can be used to activate a specific page. This works both from within a diagram and when sent from another widget in the compilation.

{
    "type": "send",
    "to": "diagram1", // Id of the target diagrams widget
    "message": {
        "topic": "setActiveDiagramsPage",
        "payload": {
            "name": "Page-2" // Name of the page to activate
        }
    }
}

The generated unique page id, as shown in the pages array of the diagram model, can be used instead of the name. This is however discouraged, since it makes the configuration harder to read and maintain.

Actions

The actions property of the diagrams widget is used to implement action pipelines for specific trigger events.

Action Hooks

In the widget model, only the general action hooks are supported. However, in the shape configuration, an additional action hook can be implemented.

onClick

The onClick action hook is defined at the shape level. It can be used to implement action pipelines that are invoked when clicking on the shape in the diagrams widget.

Set Active Diagrams Page

From within a diagrams page, the dedicated setActiveDiagramsPage action can be used for inter-page navigation. The example shows it being called from an onClick handler of a page shape.

{
    "type": "shape",
    "actions": {
        "onClick": {
            "type": "setActiveDiagramsPage",
            "name": "Page-1"
        }
    }
}

As is the case with the send action, the page id can be used instead of the name

Toolbars

The diagrams widget supports custom toolbars. To do this, see the toolbars section in the widget documentation.

Tools

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

Icon Name Description

Open IFrame Btn

Open IFrame

Open the Diagram Editor within the diagrams widget

Open New Window Btn

Open New Window

Open the Diagram Editor in a separate browser window.

Refresh Btn

Refresh

Refreshes the widget

Spacer

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