WebStudio Reference

WebStudio has both a development and a user mode. In development mode, compilations can be created using a wide variety of widgets and developer tools. The user mode allows interactive access to widgets and compilations without changing the underlying model.

This section of the documentation is primarily aimed at providing technical reference material for the development mode in WebStudio. As such, it is not designed to be read from end-to-end but provides extensive information on all of the tools and widgets that WebStudio has to offer.

With developer tools enabled for a compilation, click the DevToolsButton icon in the menu bar of WebStudio to enable access to the Widget Model Editor for all widgets. The model editor indicator is only visible when hovering over the widget.

For a more user-friendly walkthrough of how to use WebStudio and examples of compilations, refer to the "Getting Started" section instead.

Refer to the tables below to navigate to a specific reference section.

Item Description

Loading WebStudio

Load WebStudio in a browser

Index Page

Configuration for the WebStudio Index Page

Compilation Model

WebStudio compilation model.

Developer Tools

Developer tools in WebStudio.

Actions

Interaction actions.

Generic Widgets:

Advanced Form

Display an advanced form with more configurability than the basic Form.

Button

Invoke custom click-handler action pipelines.

Diagrams

Display graphics representing current state of processes and equipment.

Editor

Display rich text editor.

Form

Display entries to collect user input.

IFrame

Embed other web content.

Image

Display an image.

Markdown Viewer

Display Markdown content including Mermaid graphs.

Model Tree

Display a hierarchical node structure using object models from the system.

Plotly

Display Plotly graphics.

Table

Display and edit tabular data. Supports (multi) select.

Tabs

Displaying multiple compilations within a main compilation.

Text

Display text.

Time Period Table

Table with start and end time pickers.

Tree

Display hierarchical node structure.

Video

Display a video.

Specific Widgets:

Batch Table

Display batch (BPR) headers.

Chart

Display trend chart with multiple axis support.

Event Table

Display A&E events.

Faceplate

Display actual system object values.

File Grid

Display info and content of multiple files (GridFS).

Report Viewer

Display reports with export support.

Development Widgets:

Message Debugger

Inspecting action pipeline messages.

Transform Editor

Test transform actions.

Examples:

Example Compilations

Examples of the widgets and their interaction.

Loading WebStudio

WebStudio is shipped with the system Setup. The installation of the Web API also includes the WebStudio web app. WebStudio can be loaded into the Browser by:

PROTOCOL://HOSTNAME: PORT/apps/webstudio/

  • PROTOCOL: http or https

  • HOSTNAME: Hostname of the web server from where to load WebStudio from. Can be the Web API.

  • PORT: TCP/IP port number of the web server.

Typically with a default installation you can open the Browser, on the machine where the Web API is installed, and visit:

http://localhost:8002/apps/webstudio

By providing query parameters in the URL you can auto connect and load WebStudio compilations.

Connection parameters

  • hostname= HOSTNAME: Hostname of the Web API.

  • port= 8002: TCP/IP port number of the Web API.

  • ssl= true: Using secure connection to the Web API.

Security parameters

Adding credentials in the URL:

  • credentials: Base64 encoded 'username:password'.

  • authority= builtin: Possible values builtin(default), ad, machine

Using Integrated Windows Authentication:

  • secp= iwa:

Loading options

  • logo= false: removes the vendor logo.

  • theme= light: Set the theme to dark or light. The compilation will load with the indicated theme pre-selected. This setting overrides the user selection. The theme toggle button is hidden when this option is used. Also see compilation options.theme

Loading WebStudio compilation from the system

There are multiple ways to load a compilation from the system into WebStudio, which will be explored in this section. In all cases, the developer tools will be hidden by default. For more information, see the developer tools section.

Loading from custom Advanced Endpoint

Model can be loaded by calling an Advanced Endpoint. See Web API - Advanced Endpoint docs for more details.

  • lib=MY_LIBRARY: Lua library name. Script can return function or a Lua table.

  • func=MY_FUNCTION: Function name in case the library returns a Lua table.

  • farg=: Function argument data. Typically Base64 encoded in case of JSON data.

  • ctx=/System/Core/MyFolder: (Optional) Alternative script context.

Example:

https://company.corp:8003/apps/webstudio/?hostname=company.corp&port=8002&ssl=true&secp=iwa&lib=my_librarys&func=my_function

Loading from object’s Custom Property

WebStudio compilations can be loaded from Custom Properties of objects by adding two query parameter in the URL.

  • obj: object path or id. (Note: if not provided, the Web API default context path will be used.)

  • name: name of the Custom Property.

Example:

https://company.corp:8003/apps/webstudio/?hostname=company.corp&port=8002&ssl=true&secp=iwa&obj=/System/Core/MyFolder&name=display01

Index Page

WebStudio’s index page provides access to both built-in and user-defined compilations. This section explains how to configure the index page and add links to user-defined compilations.

Configuring the Index Page

If the connected system contains a folder object called "WebStudio", an index page will be displayed when first connecting to WebStudio, provided that the current user has EXECUTE permissions on the "WebStudio" folder. This index page can be configured to include additional links to custom compilations, using Script Libraries.

New Compilation

The first option on the index page is used to start a new blank compilation. Note that the url now contains a query parameter:

    http://<hostname_webapi>:<port>/apps/webstudio/?name=new

This URL can be used to directly load a blank compilation, rather than going via the index page.

In addition to the built-in views, user-defined ones can also be exposed on the index page. This is achieved by adding a script library called webstudio-index to the WebStudio folder object under the core.

The Lua script body should return a function which will be invoked when the index page is loaded in WebStudio. The last parameter passed to the function is the "index" compilation JSON. It can be modified to add additional link items into the table widget. The function must return a valid compilation model. This can be either the modified one or an entirely new one.

Consider the example below, which adds a new "Hello world" link to the index.

  • Start by creating a simple compilation to load from the index page.

    {
        "version": "1",
        "widgets": [
            {
                "type": "text",
                "text": "Hello World",
                "captionBar": false,
                "layout": { "x": 32,"y": 2,"w": 21,"h": 6,"static": true},
                "id": "txt1"
            }
        ],
        "options": {
            "stacking": "none",
            "numberOfColumns": 96
        }
    }
  • Using DataStudio, create a new folder object in the system, say under the "WebStudio" node and call it "Hello World Compilation Holder".

    compilation holder
  • Select the new folder in the tree and in the property panel add a custom property called hello-compilation. (The name is not significant other than that it allows us to refer to the value in the script below).

    Edit Compilation Holder
  • Then click the property value field and press Shift+F2 to bring up the field editor dialog. Click the Edit button and paste in the compilation JSON above. Remember to apply the changes on the folder’s property panel

    Add compilation
  • We are finally ready to implement the webstudio-index function on the "WebStudio" folder object.

    return function(arg, req, hlp, comp)
        -- get a reference to the first widget in the compilation,
        -- which is the table containing the index entries
        local tableWidget = comp.widgets[1]
    
        -- Make sure we have the widget we expect in hand. It should be a table widget
        -- with id = "navigationTable"
        if not ( tableWidget.type == "table" and tableWidget.id == "navigationTable" ) then
            -- It is not... Just return the compilation unchanged for now...
            return comp
        end
    
        local title = "Hello World"
    
        table.insert(tableWidget.data, {
            title = title,
            icon = "∞",
    
            -- Load the compilation from a named field on an object
            subType = 'object-name',
    
            -- Path to the object to load the compilation from
            objspec = '/System/Core/WebStudio/Hello World Compilation Holder',
    
            -- Optionally set the context path (See Note in the
            -- "Automatic post processing" section below for more information)
            ctx = '/System/Core/WebStudio/Hello World Compilation Holder',
    
            -- Property containing the compilation JSON
            name = 'hello-compilation'
        })
        return comp
    end

Apart from the title and icon fields, the parameters added to the tableWidget.data correspond to those of the load-compilation action. Inspection of the index compilation reveals that it is precisely this action that gets invoked when an item is clicked, passing the configured table row data via the message.payload to the action. The mechanics of this process are explained here.

This means that in addition to loading a static compilation from a property field as shown above, index entries can also be configured to invoke an advanced endpoint to retrieve a dynamically generated compilation.

In the example presented, the "Hello World Compilation Holder" was configured to contain a single compilation in the custom property field we added. More compilations can be added to the same object by configuring additional custom properties. In other words, each folder object can be used to hold multiple compilations.

Automatic post processing

The mechanism described above to manipulate the index page before it is returned to WebStudio can be used with our own compilations to execute post-processing logic on them. Refer to the load-compilation action documentation for more details.

Compilation

The WebStudio configuration, in which widgets along with their display attributes and dynamic behavior are defined, is collectively referred to as a compilation.

The compilation and contained widgets within are described using JSON objects. Throughout this documentation the term "model" refers to the structure of the various JSON fragments used to describe the elements within the compilation as well as the compilation as a whole.

Model

The version is for future changes to be able to support new definition of the model.

{
    "version": "1",
    "widgets: [] // List of widget objects
}

See widget doc model description for the widget model.

Options

{
    "options": {
        "background": {},
        "numberOfColumns": 96,
        "numberOfRows": 12,
        "stacking": "none",
        "showDevTools" : true,
        "padding": {
            "x": 0,
            "y": 2
        },
        "spacing": {
            "x": 2,
            "y": 2
        }
    }
}
name description

background

Used to set the compilation background color and image. These settings are actually nested within a style object. Refer to the example below to see them in action

style

style options for the background

backgroundImage

load an image as the canvas backdrop.

backgroundSize

Set the display options for the backgroundImage. The options derived from CSS styles and are:

  • auto : The loaded image native size is used and it is tiled to fill the whole canvas area. This is the default options

  • cover : The image height is stretched to that of the canvas. If it has a wider aspect ratio than that of the browser window, the image will be clipped. Also note the if the image height is larger than that of the canvas, it will be clipped at the bottom of the frame

  • contain : The image is repeated either horizontally or vertically, depending on which of its dimensions divides the most into the canvas width or height. In other words, if the background image is about the same width as the work area, but much shorter in height, it is repeated vertically and vise versa.

  • <n>% : This option behaves the same as auto except that the image is scaled by the specified percentage (For example 50% )

  • <n>px or <n>px <m>px : Sets the size of the image in pixels. If only one value is provided it is applied to the width of the image. For example 100px is equivalent to 100px auto

  • <n>.<m>em: Specify the size in EM units. 3.2em for example

backgroundColor

can be set to any valid CSS color name or RGB value

numberOfColumns

Defines the number of vertical columns the grid is divided into. The absolute column width in pixels, will scale proportionally to that of the compilation viewport. By default the numberOfColumns is set to 96 when you create a new compilation. In case you are wondering why 96 and not 100, it is because 96 has the most factors, allowing the columns to be divided into more equal width groups ( 2, 3, 4, 6 …​ etc) that 100. That said, the column count should be adjusted to suite the layout needs for your compilation.

numberOfRows

Optional property, which can be assigned one of three values:

  • auto: see numberOfRows.type = "square" below.

  • <number>: This option is deprecated and should be avoided. For the time being it is still available to provide backward compatibility. It sets the height of grid rows to a specific number of pixels. The same can be achieved by setting the numberOfRows.type field to height and assigning the pixel height to the numberOfRows.value field.

  • Nested properties: See below

If the property is omitted the auto behavior is assumed.

type

The numberOfRows.type field determines how the number of rows, and more specifically the row height for grid rows is calculated. Options are:

  • height: The height of each grid row is set to a fixed number of pixels, taken from the value property. In this configuration the grid rows don’t scale with the size of the viewport.

  • count: The row height is calculated by dividing the compilation viewport height by the number assigned to the value field, which now denotes the count of rows. In this mode, the row height scales proportionally to the viewport height. Use this option to create compilations which always fit exactly into the available compilation window.

  • square: The value field is ignored, and the row height is set equal to the calculated columns width, resulting in square grid cells. Consequently, the grid cells scale proportionally, based on the viewport width. This is the default behavior when the numberOfRows is not defined in the model.

value

The values is interpreted as either the row height or number of rows, depending the type selected.

stacking

Defines how the widgets can be positioned. Options are:

  • none : Widgets can be dragged around freely and positioned on any grid cell. Default

  • vertical : Widgets are stacked vertically starting from the top of the screen.

  • horizontal : Widgets are stacked horizontally starting at the left of the screen.

showDevTools

As the name suggests, this parameter is used to control access to developer tools in the UI, which allow compilations to be created, edited and inspected. It can be set to true for example to allow editing of compilations served from the back end, or false to prohibit editing at any time.

If the property is not provided, Webstudio enforces the following default:

  • Devtools and edit buttons are shown when creating and loading compilations locally

  • They are hidden when retrieving compilations from the back end.

Note: this setting takes precedence over the dev URL query parameter, which is to say, if the showDevTools property is set to false, this will override the query parameter and prevent the development tools from being shown.

padding

This is an optional property used to set the number of pixels between the edge of the canvas and the content. The x value sets the padding at the left and right edges of the canvas, while the y value sets the padding at the top. Since compilations can be taller that the height of the canvas, the there is no padding applied to the bottom of the view.If the property is omitted a default value of 5 is applied to the x and y properties. When a new compilation is created, the padding is explicitly set to x=0 and y=2.

spacing

This is an optional property used to set the spacing between widgets on the canvas. The x and y values determine the horizontal and vertical spacing. If the property is omitted, the widget spacing defaults to 10. When a new compilation is created, the spacing is explicitly set to x=2 and y=2.Note: The numberOfColumns property places a limit on the pixel size of each grid cell. The widget spacing is achieved by reducing the area within the grid cell occupied by the widget. This in turn means that the spacing cannot be set larger than the dimensions of one cell. A side effect of this is that the higher the numberOfColumns the smaller the maximum spacing can be between widgets.

theme

Optional parameter forcing the compilation to be shown with either the light or dark themes. When applied, the theme toggle button is removed preventing users from changing the setting at runtime. This value takes precedence over the user’s selection and the url setting.

width

To set the maximal grid width with e.g. 500.

Example to have an image as the compilation background:

{
    "options": {
        "background": {
            "style": {
                "backgroundColor": "#001b01",
                "backgroundImage": "url(\"https://transparenttextures.com/patterns/45-degree-fabric-light.png\")",
                "backgroundSize": "contain"
            }
        }
    }
}

rootOnly

This property can be used to configure properties on the WebStudio application bar, such as tools and styling. The app bar can be configured in a similar manner to the widget toolbars.

{
    "rootOnly": {
        "appBar": {
            "tools": {
                "notifyTool": {
                    "type": "button",
                    "icon": {
                        "icon": "🟢"
                    },
                    "actions": {
                        "onClick": {
                            "type": "notify",
                            "text": "Button clicked in application bar"
                        }
                    }
                }
            },
            "left": {
                "toolsOrder": [
                    "notifyTool"
                ]
            },
            "styleByTheme": {
                "light": {
                    "backgroundColor": "blueviolet"
                },
                "dark": {
                    "backgroundColor": "darkolivegreen"
                }
            }
        }
    }
}
name description

appBar

Used to define custom tools and styling for the WebStudio app bar.

center

Configure the tools to be displayed in the center of the app bar. NOTE: The tool or tool group name must appear somewhere in the toolsOrder, otherwise they will not be shown.

default

Define the configuration of the default tools. For now, this property only contains the hidden field.

hidden

If set to true, the default tools are hidden.

toolsOrder

Defines the order in which the tools are displayed in the app bar. Tools are arranged from left to right.

left

Configures the tools to be displayed on the left-hand side of the app bar. NOTE: The tool or tool group name must appear somewhere in the toolsOrder, otherwise they will not be shown.

default

Define the configuration of the default tools. Currently only contains the hidden field.

hidden

If set to true, the WebStudio logo and version number will be hidden from the app bar. Default is false.

toolsOrder

Defines the order in which the tools are displayed in the app bar. Tools are arranged from left to right.

right

Configure the tools to be displayed on the right-hand side of the app bar. NOTE: The tool or tool group name must appear somewhere in the toolsOrder, otherwise they will not be shown.

toolsOrder

Defines the order in which the tools are displayed in the app bar. Tools are arranged from right to left.

style

The app bar can be styled by setting the style object. This property accepts a wide range of CSS styles.

styleByTheme

Define styling for the app bar based on the WebStudio theme. Styles can be specified for both light and dark themes but it is not mandatory.

tools

Defines the "named" tools to be added to the app bar. Similarly to the toolbars on widgets, the app bar supports both default and custom tools.

toolGroups

Contains the "named" tool groups to be added to the app bar. The name of the groups is used to set the display order in the toolsOrder field. Can be used to group multiple "named" tools.

<groupName>

Define the appearance for a tool group. The name should reflect its purpose.

disabled

This property can be used to disable the tools in a tool group. The tools are displayed but will be greyed out and cannot be interacted with.

hidden

Setting this property to true will hide the tools in this tool group. Default is false.

toolsOrder

Define the order in which the tools are drawn within the group. This order will be the same for left, center and right configurations.

Terminology

name description

system

Refers to the backend system and/or the Web API.

objspec

Object’s path or the object ID.

Read other parts of the docs to get familiar with the system capabilities.

Developer Tools

Developer tools can be used to add widgets, edit compilations and access the floating tools overlay feature. When enabled, the development toolbar is located next to the version number in the main WebStudio app bar.

The Development Tools are:

  • Add widget

  • Import compilation

  • Export compilation

  • Edit compilation model

  • Edit widget compilation

The way a compilation is loaded in WebStudio will determine how to enable these tools. The visibility of the developer tools relies on both the dev parameter in the base URL and the showDevTools property in the model.

Loading WebStudio without an index page:

WebStudio, when loaded without the index page configured, will have the developer tools enabled by default.

Loading a compilation from the index page:

On the index page, the developer tools are disabled by default. To enable these, add the parameter dev=1 to the base URL.

http://<hostname>:<port>/apps/webstudio/?dev=1
If the developer tools are enabled whilst on the Index Page, any further compilations loaded from this page, will also have the developer tools enabled.
  • When creating a new compilation from the index page, the blank compilation will have the developer tools enabled by default.

  • The other compilations listed on the index page are retrieved from the back-end. These compilations will have the developer tools disabled by default. To enable the developer tools, add the parameter dev=1 to the base URL.

The showDevTools property overrides the dev parameter in the URL. Therefore, if the dev parameter is specified in the URL but the showDevTools property is set to false, then the developer tools will be disabled.

If the developer tools are not shown when dev=1 is added to the URL, then the showDevTools property has been set to false for the compilation, restricting users from making changes to the underlying model.

Floating Developer Toolbars

Tools can be accessed in the Floating Developer Toolbar for each widget. To access this toolbar, developer tools must be enabled. With these enabled, hovering over the widget will display the model editor indicator provided that the icon DevToolsBtn has been selected in the WebStudio menu bar.

  • If the caption bar is displayed, this indicator will be shown on the right-hand side of the bar.

  • If the caption bar is hidden, the indicator will appear in the top-right hand corner of the widget.

Hovering over this indicator will display the floating developer toolbar. This toolbar contains the name property of the widget and any widget specific tools.

Developer Tools in Tabs Widgets

As well as being configurable on a compilation level, the developer tools can also be configured in individual tabs compilations in the tabs widget. If showDevTools is set to false in a specific tab, the developer tool indicator will be hidden on all widgets in that tab. However, the widget models can still be accessed through the model editor of the parent tabs widget if showDevTools is set to true for the parent widget.

For nested tabs widgets, the showDevTools property can be set for each level. If the showDevTools property is set to 'true' on the inner tabs compilation but is false on the top level tabs widget compilation, then the developer tools indicator will still be shown on widgets in the nested tabs compilation.

For more information, see the showDevTools section of the Tabs widget documentation.