Configuration
Oct 4 2023 at 12:00 AM
Description
This section highlights the configuration of the Digital Overlay widget and provides a guide on how to navigate the different configuration options offered in this widget. It is crucial to understand how to configure the Digital Overlay widget’s properties, link endpoints, and use features such as Conditional Formatting. The Config editor is a configuration tool within the Digital Overlay widget containing features that enable users to customise the operations and appearance of elements in their overlay designs. This section provides a guide on how to navigate and use the features available in the Config editor.
Accessing the Config editor
There are two methods for accessing the Config editor screen:
Method 1:
- Select the widget you wish to configure.
- Upon selection, the
Open config editor
icon will appear on the left navigation panel. - Click on this icon to display the ‘Config editor’ window for the selected widget, allowing for quick access to the editor’s features.
Clip 1: Config editor – Method 1
Method 2:
- Alternatively, you can access the Config editor by selecting the
Open Options
orOpen Conditional Formatting
buttons displayed on the widget. - Clicking either of these buttons will open the ‘Config editor’ window, allowing you to access its settings and configurations.
Clip 2: Config editor - Method 2
The Config editor, allows the user to access the following features:
- Properties
- Endpoint linking
- Options
- Conditional formatting
For more details about each feature, refer to the sections below.
Properties
The Properties tab acts as an interface, which enhances the user’s ability to modify widgets and elements precisely to their project’s requirements. When the user selects the Digital Overlay Widget, they attain the ability to configure this specific widget’s settings. Users can adjust parameters such as opacity, position, scale, and more. Furthermore, the Properties tab incorporates the selection of individual elements within the overlay and background layer. When a user selects an element within a layer, they unlock the access to adjust settings to that element’s characteristics. Its settings encompass a wide range of options and will be available depending on the selected element. An outline and a detailed explanation of some of the properties accessible within this tab is found below.
Shape Properties
This section is a guide on how to edit the Shape properties as illustrated in Clip 3.
Clip 3: Shape properties
Below are detailed step-by-step instructions to follow:
- Select the layer containing the shape element.
- Click on the shape element to edit it.
- Select the
Open Options
icon, and the ‘Config editor’ window will appear. - Choose the ‘Properties’ tab and expand the top menu by clicking the small arrow icon next to it.
- Input a name for the shape in the space provided. This name can be seen when users click on the ‘Toggle layer list’ .
- Adjust the size and position of the shape by expanding the ‘Position’ menu. Within this menu, users are presented with quantity input boxes for fine-tuning the dimensions (height and width) and for precise positioning of the shape.
Expand the ‘Appearance’ menu. By clicking the small arrow icon next to the menu name it allows the user to view and access settings that fall under the Appearance menu more conveniently. Here, the user can change the:
- Background colour.
- Shape’s opacity.
- Border thickness and colour.
Text Properties
This section is a guide on how to edit the ‘Text’ properties.
Clip 4: Text properties
Below are detailed step-by-step instructions to follow:
- Select the layer containing the text element.
- Click on the text element to edit it.
- Select the
Open Options
icon, and the Config editor will appear. - Select the ‘Properties’ tab and expand the ‘Name’ menu. By clicking the small arrow icon next to the menu name it allows the user to view and access settings that fall under the Name menu more conveniently.
- Enter a name for the value box in the space provided. Initially, the space displays “Text 1” as the default name. This is the name that can be seen when users click on the ‘Toggle layer list’.
- Adjust the value box’s size and/or position by expanding the ‘Position’ property menu. This is useful for users who want finer-grain positioning.
- The ‘Value’ property menu is used to hard-code a static value or output for the text element. Expand the ‘Value’ property menu and update the value box containing the default <%=VALUE%> input. If a user links an endpoint (normal/live or static) to the text element, the linked endpoint’s output will override the hard-coded static value input here, and the text element will display the value output of the endpoint instead.
- Under the same Value menu, the user has the option to select an ‘Include label’ checkbox that will include a label in the value box. Upon selecting the ‘Include label’ checkbox, the ‘Label’ field is enabled.
- Enter a label name.
Select a ‘Value format’ option (plain text, number, date). This will determine the format in which the value will appear.
- Plain text: String format (This is the default format).
Number: Five standard number formats are provided. Explore the number format options within Clip 5. Additionally, users have the flexibility to personalise the number format to align with their individual preferences.
Clip 5: Number Format
- Date: Eight date (and time) formats are provided. Explore the date format options within Clip 6. Additionally, users have the flexibility to personalise the date format to align with their individual preferences.
Clip 6: Date Format
- Expand the ‘Appearance’ properties. By clicking the small arrow icon next to the menu name it allows the user to view and access settings that fall under the Appearance menu more conveniently. Here, the user can change the:
- Background colour.
- Shape’s opacity.
- Border thickness and colour.
- Shape’s size.
Image Properties
The image elements have the following menus under the Properties tab (Refer to Clip 7):
- Name
- Position
- Media
Clip 7: Adding images
To add an image file from a device’s location for use on a specific image element within a layer, users should follow the steps below:
- Select a layer and double-click on the image element.
- Select the
Open options
button, and the ‘Config editor’ window opens. - Choose the ‘Properties’ tab at the top left of the Config editor window. These properties allow the user to change the name of the Image Element, reposition the element on the view panel, as well as select the media to be used within the Image Element.
- Expand the ‘Name’ menu to rename the Image Element in the input space provided. This name will be displayed on the layer when users click on the ‘Toggle layer list’ feature.
- Expand the ‘Position’ menu to adjust the image element’s size and position on the view panel. Within this menu, users are presented with quantity input fields for fine-tuning the positioning (x and y coordinates), dimensions (height and width), and rotation (º) of the element. The
Lock aspect ratio
icon is used to preserve the relative width and height when you resize an image or graphics shape. When locked, the original proportions of the selected shape are preserved when the height or width is changed. - Expand the ‘Media’ menu. By clicking the small arrow icon next to the menu name, it allows the user to view and access settings that fall under the Media menu more conveniently. A user can add an image inside an image element using the following options:
- Option 1: If there is an existing image, browse your device or previous uploads by selecting the
BROWSE LIBRARY
button. This will open an ‘Images’ window for the user to access any existing images under one of 3 repositories:- Library: A selection of images that have been pre-uploaded to the Commander image database.
- My Uploads: Showing all images previously uploaded with your profile within Commander.
- New: Providing the user the option to either, drag and drop an image from their device to the designated upload area, or, browse their device’s hard drive for the desired image.
- Option 2: Drag and drop an image from your device into the designated area stated.
- Option 1: If there is an existing image, browse your device or previous uploads by selecting the
- Click on the
UPLOAD
button, and the ‘Image editor’ window opens. The properties displayed on the Image editor window allow the user to:- Revert to default: Restores settings to their default values.
- Rotate the image 90 degrees to the left or right: It rotates the image 90 degrees to the right or the left.
- Flip the image vertically or horizontally: It flips the image either vertically or horizontally.
- Zoom in and out: Manipulates a display to make it smaller or larger.
- Specific rotation: The slider bar moves to rotate the image to a specific angle expressed in degrees.
- Fit: Configures and displays the image in its actual size.
- Fill: Configures and fills an image to a specified interior boundary.
- Remove image: Deletes the image on the ‘Image editor’ window.
- New Image: This
button
allows the user to browse for a new image. - Done: Saves and confirms the changes made on the image.
- Select
Done
to confirm the image selection and configuration. The image will appear in the layer, automatically adjusting to fit the shape and size of the image element. If needed, you can further edit the image within the properties of the Image Element.
Edit an image
This section is a guide on how to edit an image element within a layer.
Clip 8: Edit Image
Below are detailed step-by-step instructions to follow:
- Select the layer with the image element.
- Select the image element to edit.
- Click on the
Open Options
button to open the Config editor window. - Choose the ‘Properties’ tab.
- Expand the ‘Media’ menu. By clicking the small arrow icon next to the menu name it allows the user to view and access settings that fall under the Media menu more conveniently.
- Select the
EDIT IMAGE
button to open the ‘Image Editor’ window. In this window, users can edit the image by adjusting the settings detailed in point 8, ‘UPLOAD,’ of the ‘Image Properties’ section. - Click on the
Done
button to save and confirm the changes made on the image.
Endpoint linking
Endpoint linking enables users to link an endpoint with a particular layer and subscribe it to a visible element within the chosen layer. Here are some key characteristics:
- Each endpoint can currently be linked to only one layer at a time.
- A maximum of 100 endpoints can be linked to a single layer.
Clip 9: Endpoint Linking
Here are detailed step-by-step instructions to follow:
- Select the layer to link the endpoint by clicking in the checkbox next to the layer’s name.
- Open the ‘Config editor’ window using any of the methods highlighted above.
- Select the
Endpoint linking
icon. The user will see a list of overlay layers and any value that links to the layers. If there was no value that linked to a particular layer, the user will see a default notification message stating that “No value linked”. - Click on the
Link
button next to the layer. The ‘Subscription Type’ window will appear, displaying the ‘Endpoint’ and ‘Digital Twin - contextual’ options. - Select the ‘Endpoint’ option, and a list of all the available endpoints appear.
- Select the checkbox with the endpoint to link to the layer. If there is more than one endpoint listed, the user can select the relevant ones.
- Click on the
Done
button, and the Config editor window appears, with information indicating the link between the endpoint and the layer/specific element. - Select the element and click on the
Link
button. A window with the name of the overlay layer appears. It consists of the following sections:- Endpoints: This section displays the linked entities like functions, triggers, or endpoints.
- Navigator: This section displays the linked Navigator historic value or Navigator aggregate endpoints (supported by certain widgets).
- Template properties: This section displays the linked Digital twin entities like functions, triggers, or endpoints.
- Drag and drop the link icon that appears next to the endpoint onto the element on the layer. A message will appear at the bottom left corner of the screen, highlighting the successful subscription of the element as shown in Figure 1.
Figure 1 - Successful Subscription Nofitication
Endpoint linking does not work on an image element. If the user attempts to link an endpoint to an image element, the notification shown below in Figure 2 will appear. Endpoint linking is successful when it is applied on either a shape or value box. |
Figure 2 - Endpoint Linking Error
Options
When users access the ‘Options’ tab within the ‘Config editor,’ they will encounter a series of screens, as illustrated in Clips 8 and 9. This feature allows users to select from a variety of element options to include into their chosen layer. It is important to note that the availability of certain features on this tab depends on the type of layer the user has selected.
- For the ‘Background’ layer, only the ‘Image’ element option is accessible.
- In the case of an ‘Overlay’ layer, users have access to all available element options.
Clip 10: Options Tab – Overlay layers
These properties are only available when a layer is selected. |
When a user selects the Background layer tab, the option to add shapes and text are unavailable. However, the user can add an image to this layer in the form of the background of the widget.
Clip 11: Options Tab – Background layer
Conditional Formatting
Conditional formatting is a Config editor feature applied to each overlay layer to customise the appearance of an element (shapes and/or value boxes) based on specific conditions. By using endpoint values as criteria, users can adjust the formatting to suit their specific needs. Here are the key features of Conditional Formatting:
- Layer-Specific Rules: Users can configure rules for conditional formatting per layer, tailoring the behaviour of elements within each layer.
- Sequential Rule Processing: The rules are processed in a specific order.
- Endpoint Linkage Requirement: To utilise conditional formatting, at least one endpoint must be linked to the layer, and there should be at least one element present on that layer.
Conditional formatting that is based on an endpoint can be applied to the following elements:
- Images
- Text
- Background styles
- Opacity
To configure conditional formatting in this widget there should be:
- At least one endpoint.
- A layer subscribed to the endpoints.
Applying Conditional Formatting
This section is a guide on how to apply conditional formatting in the Digital Overlay widget.
Clip 12: Conditional Formatting
Below are detailed step-by-step instructions to follow:
- Open the ‘Config editor’ window using any of the methods highlighted above.
- Select the
Conditional Formatting
icon. The user will see a list of overlay layers within the widget. - Select a layer by expanding the ‘Edit overlay rules’ arrow. Here, the user can view the formatting rules. The conditional formatting is applied per layer, and if a user has more than one layer, they must click on the specific layer where they want to add the formatting rules.
- To add a new rule, click the add icon,
+
. An ‘Edit rule’ window opens, displaying all the fields used to apply formatting rules. - Enter a Rule Name. This is a required field where the name of the rule is entered.
Add a name that is descriptive and fitting to the purpose of the rule. |
- Select an endpoint from the ‘If’ dropdown list provided. The selection in the dropdown will be the entire list of endpoints that have already been linked to the selected layer (see rules above on linking endpoints to a layer). To link this endpoint to a layer, drag and drop the endpoint onto an element within that layer.
- Select an operator from the ‘Is’ dropdown list provided. The operator selected determines the number of values required to input in the ‘Value’ field provided below. For instance, if the operator selected is between, it requires the user to specify a minimum and maximum value.
- Specify a value in the Value field provided. The Condition menus can be expanded.
A user can add more than one condition by clicking on the Add Condition button, and repeating Steps 8 and 9. This additional condition is an AND condition, therefore for the rule to apply, both the first AND second condition must be met. The first Condition menu cannot be removed. |
The Format menu offers users the ability to apply multiple formats. Initially, this list defaults to the first available option. For the remaining widget elements, users can add additional Format menus. The ADD FORMAT
button becomes disabled when there are no more element options to add. It is important to note that the first Format menu cannot be removed.
- To format a selected element within a layer, expand the ‘Format’ menu and choose the desired element from the ‘Then set the’ drop-down list.
- Click on the
background colour picker
icon and choose a colour for the background by clicking inside the colour palette window. Thereafter, click outside the window to save the setting. The color picker enables you to clear or deselect a color. - Click on the
border colour picker
icon and choose a colour for the border by clicking inside the colour palette window. Thereafter, click outside the window to save the setting. - Select and adjust the opacity percentage of the element.
- Select one of the ‘Visibility’ dropdown options:
- Show: Displays the configured element, provided the formatting rule has been met.
- Hide: Stops displaying the configured element, provided the formatting rule has been met.
- Press
DONE
to save the changes and go back to the rule list.
Duplicating a formatting rule
This is a guide on how to duplicate/copy a formatting rule in the Digital Overlay widget.
Clip 13: Duplicating a formatting rule
Below are detailed step-by-step instructions to follow:
- After selecting the
Conditional Formatting
icon. The user will see a list of overlay layers within the widget. - Select a layer by expanding the ‘Edit overlay rules’ arrow. Here, you can view all the formatting rules in that layer.
- To copy a specific formatting rule from the list, hover the cursor over the rule. A
Duplicate rule
icon will appear on the right. - Select the
Duplicate rule
icon and a copy of the rule will appear on the list.
Removing a formatting rule
This section is a guide on how to remove a formatting rule in the Digital Overlay widget.
Clip 14: Removing a formatting rule
Below are detailed step-by-step instructions to follow:
- After selecting the
Conditional Formatting
icon. The user will see a list of overlay layers within the widget. - Select a layer by expanding the ‘Edit overlay rules’ arrow. Here, you can view all the formatting rules in that layer.
- To remove a specific formatting rule from the list, hover the cursor over the rule. A ‘Remove rule’ icon
x
will appear on the right. - Select the ‘Remove rule’ icon
x
and a confirmation message to remove the rule will appear. - Select the
Remove
button and delete the rule from the list.