Getting Started with the Diagrams Widget

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

The examples shown in this getting stated section require some example objects to be created in the backend of the connected system. Please download either the Excel or JSON MassConfig sheet and import into the MassConfig Display of DataStudio. Click Apply to create the objects in the I/O Model. More information on importing Excel and JSON MassConfig sheets can be found here.

The Diagrams widget can be used to display the current state of processes and equipment and offers the option for the user to interact with the system directly from the widget itself. To use a Diagrams widget, open the Widget Model Editor by clicking the plus icon in the menu bar of WebStudio. In the Widget Model Editor, select the Diagrams  Empty Diagrams and click save to open an empty diagrams widget.

Empty Diagrams Widget
Figure 1. Empty Diagrams Widget

Diagrams Editor

The Diagrams Editor is the primary interface used to create diagrams, providing a rich environment to compose graphical views and configure their dynamic behaviour. It can be opened in two different ways using the buttons in the developer toolbar, accessed by hovering over the developer tools indicator in the top right-hand corner of the widget:

Open Editor Buttons
Figure 2. Open Editor Buttons
  • Within the diagrams widget: To open the diagrams editor within the widget, click the button on the left. This will replace the view currently displayed in the widget and therefore, any changes made will not be visible in the diagrams widget until the editor is closed. Clicking the Save button in the top right-hand corner will save any changes and close the editor.

  • As a floating panel: The button in the middle will open the diagrams editor in a separate window, allowing the user to view changes made to the diagrams widget in real-time including live animations and data.

Built-in functionality

The editor window integrates functionality from diagrams.net. Refer to the diagrams.net documentation for more information on the built-in functionality of the diagrams editor.

Custom functionality

In addition to the built-in features of the editor, WebStudio offers additional custom functionality. The Shape Model Editor, a tool which is specific to WebStudio, can be opened by selecting an object or group of objects and then clicking the PropertyPanelBtn button in the editor toolbar. For an individual object, the Shape Model Editor will contain a JSON for the object. For grouped objects, an additional panel is shown on the left-hand side containing a collapsible tree of all objects in the group. To save changes made in the Shape Model Editor, click Apply. A warning will be shown if the user tries to close the window without applying the changes.

Creating a Diagram

To demonstrate the functionality of the diagrams widget, in this section of the documentation, we will be creating an example configuration representing a tank and valves showing states from a system. To start, open the editor window as a floating window, allowing you to see the changes in real-time.

Firstly, we will create the shapes needed for the tank and group them together.

Adding a Tank

In the left-hand panel of the editor, open the General section and select a cylinder object to represent the tank. This will add the object to the grid in the editor.

Diagrams Widget Editor - Creating a Tank
Figure 3. Diagrams Widget Editor - Creating a Tank

Next, add a text object to the grid from the General section. This will be used to label the tank.

Diagrams Widget Editor - Tank Label
Figure 4. Diagrams Widget Editor - Tank Label

Add a rectangle object, from the General section of the left-panel, to act as the tank level indicator. Resize this object to fit inside the tank cylinder object.

Diagrams Widget Editor - Tank Level Indicator
Figure 5. Diagrams Widget Editor - Tank Level Indicator

Finally, add a label for the level indicator. This can be done by selecting an text object from the General section in the left-hand panel.

Diagrams Widget Editor - Level Label
Figure 6. Diagrams Widget Editor - Level Label

Select the objects and go to Arrange  Group to group them together. This can also be achieved by pressing Ctrl+G or by right-clicking on the selected objects and selecting Group from the context menu.

Configuring the Tank Shapes

Next, we will configure the grouped objects. Select the grouped objects and then click the PropertyPanelButton button to open the Shape Model Editor.

Diagrams Widget - Shape Model Editor for Grouped Tank Shapes
Figure 7. Diagrams Widget - Shape Model Editor for Grouped Tank Shapes

On the left-hand side, the collapsible tree can be used to navigate to the models for each of the objects in the group. At first, this may be difficult to navigate as the objects will be referenced by a string of characters; the string representing each object is its unique id. To make this easier to navigate, a name property can be added to each model and assigned a suitable value. For example, the name property for the 'group' model could be "tank". Click Apply to save the changes.

Diagrams Widget - Shape Mode Editor with `name` Property
Figure 8. Diagrams Widget - Shape Model Editor with name Property

In the collapsible tree, the objects should be listed in the order they were created so the model for the tank object should be the first object in the list under the group model. Add a name property and assign a suitable value to it, such as "tankBody".

Diagrams Widget - Shape Model Editor for `tankBody`
Figure 9. Diagrams Widget - Shape Model Editor for tankBody

For the model of the tank label, set the name field to an appropriate value, such as "label".

Display Text Animation

To read the name of the tank from the system, a displayText animation is used.

  • All animations require a dataSource to be specified. In this case, the type should be set to "read" and the path should point to the ObjectName of the tank in the system. A key should also be specified as this will associate the value read from the system with a specific field in the payload.

    {
        "dataSource": [
            {
                "type": "read",
                "key": "objname",
                "path": "/System/Core/Simulation/Process Diagram/Tank01.ObjectName"
            }
        ]
    }
  • An animations array is also required. The type should be set to "displayText". For this animation type, a text field is used to associate with the key value from the dataSource. Finally, a rule of the type "match" should be defined.

    {
        "animations": [
            {
                "type": "displayText",
                "text": {
                    "field": "objname"
                },
                "rules": [
                    {
                        "type": "match",
                        "match": {
                            "objname": {
                                "$ne": ""
                            }
                        }
                    }
                ]
            }
        ]
    }
Diagrams Widget - Shape Model Editor for `label`
Figure 10. Diagrams Widget - Shape Model Editor for label

Similarly, on the model for the level indicator, set the name to an appropriate value, such as "levelIndicator".

Level Animation

To show the level in the tank, a level animation is used.

  • Since all animations require a dataSource the first step is to add one to keep track of tank level. The type should be set to "subscribe" and the path set to relevant tag in the system IO-model.

    {
        "dataSource": {
            "type": "subscribe",
            "path": "/System/Core/Simulation/Process Diagram/Tank01/Level"
        }
    }
  • Next, the animations array must be created containing one element for each animation type to be applied to the shape. Start by adding an object element to the array and set the type field to "level". A min and max value should be specified to define the bounds of the level fill. All that remains is to add one or more rules which get evaluated each time the tag value updates. In this case two are defined. The first causes the fill color to be blue up to 80% full, after which the fill color will be red.

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

The resulting model should now look similar to the example below.

Diagrams Widget - Shape Model Editor for `levelIndicator`
Figure 11. Diagrams Widget - Shape Model Editor for levelIndicator

Numeric Level Indication

We would also like to see the level shown as a value next to the fill bar. This can be done using the displayText animation type.

  • Add a dataSource property of type "subscribe" to "levelDisplay" shape. In addition to the level value, we also want to get the engineering units and the number of decimal places from the system. The key properties are added to the data source definitions to allow us to reference the values in the animation definition

    {
        "dataSource": [
            {
                "type": "subscribe",
                "key": "level",
                "message": {
                    "payload": {}
                },
                "path": "/System/Core/Simulation/Process Diagram/Tank01/Level"
            },
            {
                "type": "read",
                "path": "/System/Core/Simulation/Process Diagram/Tank01/Level.OpcEngUnit",
                "key": "unit"
            },
            {
                "type": "read",
                "path": "/System/Core/Simulation/Process Diagram/Tank01/Level.DecimalPlaces",
                "key": "decimals"
            }
        ]
    }
  • An animations property of type displayText is required to change label text to the value from the system. The engUnit and numberOfDecimals are now also tied to the values read in the dataSource. Realizing that the animation only updates the text if a rule is matched, we use a "dummy" rule which always evaluates to true. Also notice the name field used in the rule to indicate where to read the input from

    {
        "animations": [
            {
                "type": "displayText",
                "text": {
                    "field": "level"
                },
                "engUnit": {
                    "field": "unit"
                },
                "numberOfDecimals": {
                    "field": "decimals"
                },
                "rules": [
                    {
                        "type": "range",
                        "range": {
                            "from": 0
                        },
                        "name": "level"
                    }
                ]
            }
        ]
    }

As a result, the model for the levelDisplay should look similar to the example below:

Diagrams Widget - Shape Model Editor for `levelDisplay`
Figure 12. Diagrams Widget - Shape Model Editor for levelDisplay

Press Apply to save the changes and close the Shape Model Editor to return to the diagrams editor.

In the editor, the grouped objects can be dragged into the Scratchpad in the left-hand panel, making them easily accessible for repeated use if necessary.

Diagrams Widget Editor - Scratchpad with Tank Objects
Figure 13. Diagrams Widget Editor - Scratchpad with Tank Objects

In the next section, we will create an inflow valve which can be switched on or off. We will also add animations and define click-handler actions.

Adding an Inflow Valve

First, add two triangles from the General section of the left-hand panel. These should face each other so change the orientation of one of the triangles by selecting the object and then go to Arrange  Direction  Flip Horizontal. Add a rectangle above the triangles from the General section and connect it to the triangles using a vertical line from the Misc section of the left-hand panel.

Diagrams Widget Editor - Valve
Figure 14. Diagrams Widget Editor - Valve

Next, add a label above the rectangle; this can be achieved by selecting the text shape from the General section of the left-hand panel. Double-click on the object to change the text. Finally, add two rounded rectangles from the General section as these will act as the Open and Close buttons for the valve. To add text, double-click on each of the shapes; set one as "OPEN" and the other as "CLOSE".

Diagrams Widget Editor - Complete Valve
Figure 15. Diagrams Widget Editor - Complete Valve

Similarly to the tank object, these objects should be grouped together. Select all of the valve objects and press Ctrl+G or right-click the objects and select Group from the context menu.

Configuring Inflow Valve Shapes

In the Shape Model Editor, the name property for each object should indicate what the object is or what it represents in the group. It is important to set the name property for grouped objects as it makes them easier to reference if necessary.

Diagrams Widget - Shape Model Editor for Valve
Figure 16. Diagrams Widget - Shape Model Editor for Valve

Fill Animation

To show when the inflow valve is switched on, a "fill" animation is used.

In the group model:

  • add a dataSource property with the type set to "subscribe" and the path pointing to a relevant object in the system

    {
        "dataSource": {
            "path": "/System/Core/Simulation/Process Diagram/Valve02/Status",
            "type": "subscribe"
        }
    }
  • an animations array is added to change the colour of the two triangles depending on the state of the system. The type field should be set to "fill". As this animations array is defined at the group level, the shapes that will be changed by the animations property must also be specified.

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

The resulting model should now look similar to the example below:

Diagrams Widget - Shape Model Editor for Valve Model
Figure 17. Diagrams Widget - Shape Model Editor for Valve Model

onClick Actions

For the openButton model, an actions property containing an onClick action should be added. This onClick action should have the type property set to "write" and should contain an item field, with the path p and value v specified.

Diagrams Widget - Shape Model Editor for `openButton`
Figure 18. Diagrams Widget - Shape Model Editor for openButton

Similarly, for the closeButton model, an actions property containing an onClick action should be added. This onClick action should have the type property set to "write" and should contain an item field, with the path p and value v specified.

Diagrams Widget - Shape Model Editor for `closeButton`
Figure 19. Diagrams Widget - Shape Model Editor for closeButton

Click Apply to save the changes and close the Shape Model Editor. Drag the inflow valve grouped object to the Scratchpad to make it easily accessible for repeated use later.

Diagrams Widget Editor - Scratchpad with Valve Objects
Figure 20. Diagrams Widget Editor - Scratchpad with Valve Objects

Now that we have created both the tank and the inflow valve, we will create and configure a line object to connect the inflow valve to the tank in the next section. This line object may also be referred to as a pipe.

Connecting Inflow Valve to Tank

From the General section of the left-hand panel, select the line shape to add it to the grid. To connect the valve to the tank, drag one end of the pipe to join to the 'rightTriangle' and drag the other end to the tank. To ensure that the pipe is connected to both objects, a green circle will be shown when dragging each end of the pipe to the desired object.

Diagrams Editor - Inflow Valve Connected to Tank
Figure 21. Diagrams Editor - Inflow Valve Connected to Tank

Flow Animation for Inflow Valve

Now, select the line object and open the Shape Model Editor. Then:

  • Assign a suitable name and add a datasource property. This will be used to "subscribe" to changes from the system.

    {
        "dataSource": {
            "type": "subscribe",
            "path": "/System/Core/Simulation/Process Diagram/Valve02/Status"
        }
    }
  • An animations property can also be added which will be used indicate the flow between the valve and the tank. The type should be set to "flow" and a set of rules must be specified.

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

The resulting model should now look similar to the example below:

Diagrams Widget - Shape Model Editor for Pipe between Inflow Valve and Tank
Figure 22. Diagrams Widget - Shape Model Editor for Pipe between Inflow Valve and Tank

In addition to the pipe between the valve and the tank, a pipe can be used to represent the flow into the valve. This can be done by selecting the line object in the General section of the left-hand panel and connecting the line to the 'leftTriangle' object.

Diagrams Editor - Inflow Valve and Tank
Figure 23. Diagrams Editor - Inflow Valve and Tank

In the Shape Model Editor, the model can be copied from the line between the valve and the tank. In this case, the name should be updated and the path should be changed to associate with the appropriate object in the system.

Diagrams Widget - Shape Model Editor for Inflow Pipe
Figure 24. Diagrams Widget - Shape Model Editor for Inflow Pipe

In the following section, we will be creating an outflow valve using the template created for the inflow valve and configuring the behaviour to represent the respective valve in the system. We will also connect the tank to the outflow valve and add "flow" animations.

Adding an Outflow Valve and Connections

To create the outflow valve, the grouped valve object can be taken from the Scratchpad. For the diagram to work as anticipated, the model of the grouped shapes will need to be edited. Open the Shape Model Editor to view the model for the grouped objects. In each of the models containing a path property, the path should be adjusted to associate with the appropriate valve data from the system.

Diagrams Widget - Outflow Valve in Editor
Figure 25. Diagrams Widget - Outflow Valve in Editor

Flow Animation for Outflow Valve

A line object can also be used to connect the tank to the outflow valve, similarly to the connection between the inflow valve and the tank. In the Shape Model Editor:

  • Assign a suitable name and add a dataSource property. This will be used to "subscribe" to changes from the system.

    {
        "dataSource": {
            "type": "subscribe",
            "path": "/System/Core/Simulation/Process Diagram/Valve01/Status"
        }
    }
  • An animations property can be added to represent the flow between the tank and the valve. The type should be set to "flow" and a set of rules must be specified.

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

The resulting model should now look similar to the example shown below:

Diagrams Widget - Shape Model Editor for Pipe between Tank and Outflow Valve
Figure 26. Diagrams Widget - Shape Model Editor for Pipe between Tank and Outflow Valve

Similarly, a pipe should be added to represent the flow out of the valve. To do this, select the line object from the General section of the left-hand panel of the editor. Connect one end of the pipe to the 'rightTriangle' of the second valve. In the Shape Model Editor, the model can be copied from the line between the tank and the outflow valve. In this case, the name should be updated and the path should be changed to associate with the appropriate object in the system.

Diagrams Widget - Shape Model Editor for Outflow Pipe
Figure 27. Diagrams Widget - Shape Model Editor for Outflow Pipe

Click Apply to save the changes and close the Shape Model Editor. The objects in the editor should now look like this:

Diagrams Widget - Complete Diagram in Editor
Figure 28. Diagrams Widget - Complete Diagram in Editor

In the diagrams widget in WebStudio, the completed diagram should also be visible.

Diagrams Widget - Complete Diagram in Widget
Figure 29. Diagrams Widget - Complete Diagram in Widget

Multiple Pages and Navigation

The editor offers multi-page support so to complete this example, let’s add an additional page to the widget. This can be done by clicking the '+' icon next to the current page at the bottom of the editor, which will open a blank grid. In the left-panel, select a chevron arrow from the Arrows section. The orientation of the shape can be changed by selecting Arrange  Direction  Flip Horizontal from the menu bar of the editor. To add text, double-click on the shape.

Diagrams Widget - Navigation Button in Editor
Figure 30. Diagrams Widget - Navigation Button in Editor

Select the object and open the Shape Model Editor. In this window, take note of the page id as this is required to navigate between pages. Close this window for now as we will return to it later.

Diagrams Widget - Shape Model Editor `page id`
Figure 31. Diagrams Widget - Shape Model Editor page id

Return to the page containing the diagram created earlier and add a chevron arrow to the grid, detached from the existing diagram. Select the new object and open the Shape Model Editor. Add an actions property, containing an onClick action. In this case, the type should be set to "setActiveDiagramsPage" and the id should be the page id taken from the Chevron Arrow on the other page.

Take note of the 'Page' id in this window as it will be required to navigate back to the current page. Click Apply to save the changes and close the Shape Model Editor.

Go back to the new page then select the chevron arrow shape and open the Shape Model Editor. Similarly to the example above, an actions property should be added, with an onClick action. The type is "setActiveDiagramsPage" and the id should be the page id taken from the chevron arrow on the first page.

Diagrams Widget - Shape Model Editors for Navigation Buttons
Figure 32. Diagrams Widget - Shape Model Editors for Navigation Buttons

Click Apply to save the changes and close the Shape Model Editor.

To check that the navigation functionality works as expected, return to the diagrams widget in WebStudio and click the arrow on the current page. This should switch the page and by clicking on the arrow on this new page, the page should switch back.

The completed diagram should now look like this:

Diagrams Widget - Complete Diagram with Navigation Buttons
Figure 33. Diagrams Widget - Complete Diagram with Navigation Buttons

The complete compilation for this example can be found here.