Uniformance® Insight Graphics Scripting User Guide

1. Introduction

This document provides information about authoring scripts in HMIWeb Display Builder for customizing the graphics to be used in Uniformance Insight. This document also provides some example scripts for reference.

1.1 About this Document

This document provides information about authoring scripts in HMIWeb Display Builder for customizing the graphics to be used in Uniformance Insight. This document also provides some example scripts for reference.

1.2 About HMIWeb Display Builder

HMIWeb Display Builder is a specialized drawing application that enables you to create your own (custom) graphics (also called as displays). The graphics created using this application can be viewed in Uniformance Insight visualization browser.

1.3 Scripting for Graphics

HMIWeb Display Builder enables you to write scripts to customize displays that you want to view in other applications such as Uniformance Insight.

HMIWeb Display Builder exposes a script editor specifically for VBScript and JScript. JScript is Microsoft's dialect of the ECMAScript standard and is very similar to JavaScript.

2. Display Scripting

2.1 Overview

You use the Script Editor in HMIWeb Display Builder to write scripts for objects and the display itself.

The Script Editor is modeless, which means that your script is saved to memory as soon as you select another object or event. However, your changes are only saved to disk when you save the display.

2.2 Scripting for Uniformance Insight Graphics

Uniformance Insight displays are web pages designed using web technologies like Hypertext Markup Language 5 (HTML), Cascading Style Sheet (CSS), JavaScript, and so on. Display scripts use exactly the same technology as scripts used in other common standard web pages.

When authoring graphics, that are to be used in Uniformance Insight, the script must be written in JavaScript language. Hence, you must ensure that the default scripting language set for HMIWeb Display Builder is JScript (see Setting the default scripting language).

REFERENCE:

The following web sites provide useful documentation and tutorials on JavaScript:

• Mozilla's JavaScript - http://developer.mozilla.org/en-US/docs/Learn/JavaScript
• Microsoft's JavaScript Language Reference - http://msdn.microsoft.com/en-us/library/d1et7k7c(v=vs.94).aspx

2.3 Object Model

Object Model is made up of the standard Document Object Model as well as Uniformance Insight specific extensions described in the Uniformance Insight Object Model Reference chapter.

2.4 Cascading Style Sheet (CSS)

Uniformance Insight graphics and various features (like Dynamic Visualization and Error Indication) are based on HTML elements and are styled using CSS classes.

Manipulating the style of an element directly using its inline style parameter will override standard Uniformance Insight visual features and cause them to not take effect. This is because CSS rules give higher priority to inline styles than CSS classes.

When writing script that needs to change the visual appearance of elements, such as borders, background, or foreground colors, it is recommended to remove or apply CSS classes rather than using inline styles. This is especially the case for elements that retrieve data or have dynamic visualization.

ATTENTION: Scripts that manipulate inline colors or borders of data bound elements may override standard Uniformance Insight functionality.

REFERENCE:

The following web sites provide useful documentation and tutorials on CSS specificity:

• CSS Tricks Specifics on CSS Specificity - http://css-tricks.com/specifics-on-css-specificity/
• Mozilla's Specificity - http://developer.mozilla.org/en-US/docs/Web/CSS/Specificity
• Microsoft's Understanding CSS Selectors - http://msdn.microsoft.com/en-us/library/hh781510(v=vs.85).aspx

2.5 Setting the default scripting language

You must set the default scripting language to JScript before you start writing scripts for Uniformance Insight displays.

To set the default scripting language to JScript:

1. Choose Tools > Options.
2. On the General Tab, set the Default scripting language to JScript.

3. Uniformance Insight Object Model Reference

3.1 Overview

This section describes the objects that are common within the Uniformance Insight document model and their related properties and methods.

3.2 Objects

Following are the object types within Uniformance Insight model.

• Alphanumeric Object
• Indicator Object
• Shape Object
• TimeControl Object
• Vector Object
• Trend Object
• Axis Object
• HairlineCollection Object
• Hairline Object
• Legend Object
• TraceCollection Object
• Trace Object
• TraceCanvas Object

ATTENTION: Scripts that are copied and pasted from this document to the script editor may not work, as the script editor may not recognize it due to the font styles and formats (for example, quotation marks often differ between fonts).

4. Scripting Examples

4.1 Overview

This section provides examples on how to script for wide range of realistic tasks.

ATTENTION: Scripts that are copied and pasted from this document to the script editor may not work, as the script editor may not recognize it due to the font styles and formats (for example, quotation marks often differ between fonts).

4.2 Changing context text based on a numeric value

Scenario

To make displays easier to use by setting a text field based on an object's value.

Solution

Write a script to set a textbox's text property whenever the value you are interested in changes:

1. Add a textbox element called textbox001.
2. Add an alphanumeric element called alpha001 and configure it to retrieve data.
3. Add a script to the onupdate event of the alpha001 element:

function alpha001_onupdate
{
// START OF SCRIPT ////////
var equipStateOrdinal = alpha001.value;
var equipState;
switch (equipStateOrdinal)
{
Case 0: equipState = “Stopped”; break;
Case 1: equipState = “Measurement”; break;
Case 2: equipState = “Completed”; break;
Case 3: equipState = “Stabilization”; break;
default: equipState = “Error”; break;
}
textbox001.value = equipState;
// END OF SCRIPT ////////
}

4.3 Creating a shape sequence

Scenario

You have a pump that has 2 states (OFF and ON), a tag that has values 0 and 1 (for OFF and ON), and want to visually show a different picture of the pump depending on its state.

Solution

Create a shape with the 2 pump states:

1. In HMIWeb Display Builder, go to File > New > Dynamic Shape.
2. Add a Custom Property with:
   
   • Name of Tagname
   • Type of Item
3. Add vector elements to represent the pump's 1st state, group them together, and call the group state001.
4. Add vector elements to represent the pump's 2nd state, group them together, and call the group state002.
5. Add an alphanumeric called shapevalue to read the value to drive the shape sequence.
6. Configure the alphanumeric:
   
   • On the Data tab, configure Item to be {%Item::Tagname%}
     
   • On the Times tab, configure Time Control to be Configured on display
7. Select all (Ctrl+A) the elements in the shape (state001, state002 and shapevalue), align them so that they are all on top of each other and then group them together.

Configure the group:

1. On the General tab, set the visibility of the entire group to be hidden.
2. Add a script to the shape for the onupdate event of the shapevalue element:

function shapevalue_onupdate
{
//////// START OF SCRIPT ////////
state001.style.visibility = "hidden";
state002.style.visibility = "hidden";
switch (shapevalue.value) {
case 0: state001.style.visibility = "visible"; break;
case 1: state002.style.visibility = "visible"; break;
}
}

Click File > Save to save the shape

Insert the shape into a display:

1. In HMIWeb Display Builder, go to File > New > Display.
2. Go to Edit > Insert Shape.
3. Browse to the shape file created above.
4. Configure the shape:
   
   • On the Custom Properties tab, configure Time Control to be the primary time control.
   • On the Custom Properties tab, configure Item to be the tag that has the pump value.

4.4 Showing/hiding an object with item values

Scenario

Show or hide the element depending on the values of several tags.

Solution

Write a script that changes the visibility property whenever the values you are interested in change.

This example is for a group of elements called “well101” to be shown or hidden when the values of "alpha001” and “alpha002” change.

1. Add a script to the onupdate event of the alpha001 element:

function alpha001_onupdate
{
// START OF SCRIPT ////////
updateWellVisibility();
// END OF SCRIPT ////////
}

2. Add a script to the onupdate event of the alpha002 element:

function alpha002_onupdate
{
// START OF SCRIPT ////////
updateWellVisibility();
// END OF SCRIPT ////////
}

3. Add a general script to the display:

// START OF SCRIPT //////// function updateWellVisibility()
{
var P101 = document.getElementById(“alpha001”);
var F101 = document.getElementById(“alpha002”);
var Well101 = document.getElementById(“well101”);
If (P101.value < 0.5) && (F101.value < 5)) {
Well101.style.visibility = “hidden";
}
Else {
Well101.style.visibility = “visible";
}
// END OF SCRIPT ////////
}

4.5 Showing a different picture on mouse click

Scenario

Create a display that needs to show a different picture when an operator requests it.

Solution

Add two images to the display, called ImageMap and ImageSatellite. Use a button (textbox element with onclick event) to toggle the visibility of the images on the display.

This script is attached to a textbox element's onclick event.

1. Add an image element called ImageMap.
2. Add an image element called ImageSatellite.
3. Add a textbox element called textbox001.
4. Add a script to the onclick event of the textbox001 element:

function textbox001 onclick
{
// START OF SCRIPT ////////
if (ImageSatellite.style.visibility == “visible” || ImageSatellite.style.visibility == "") {
ImageSatellite.style.visibility = “hidden”;
ImageMap.style.visibility = “visible”;
}
Else {
ImageSatellite.style.visibility = “visible”;
ImageMap.style.visibility = “hidden”;
}
// END OF SCRIPT ////////
}

4.6 Stepping through time

Scenario

Step backwards and forwards through time in whole day increments snapped to a day boundaries. The Workspace Time Control allows stepping but only in 1/12 of the slider time span and not snapped to day boundaries.

Solution

Add two clickable images or textboxes to the display, called Previous and Next. Add script to these elements' onclick event to move the time.

1. Add a textbox element called PreviousDay.
2. Add a textbox element called NextDay.
3. Add a general script to the display:

//////// START OF SCRIPT //////// var timeControl;
function getPrimaryTimeControl()
{
var primaryTimeControl = null;
var timeControls = document.getElementsByTagName('hn-timecontrol');
for (var i = 0; i < timeControls.length; i++) {
var timeControl = timeControls[i];
if (!primaryTimeControl) {
// Make sure we get one even if the primary attribute is not
set
primaryTimeControl = timeControl;
} else if (timeControl.getAttribute('data-isprimary') === "true")
{
primaryTimeControl = timeControl;
}
}
}
return primaryTimeControl;
// END OF SCRIPT ////////

4. Add a script to the onclick event of the PreviousDay element:

function PreviousDay_onclick
{
/// START OF SCRIPT //////// if (timeControl === null || typeof timeControl === "undefined") {
timeControl = getPrimaryTimeControl();
}
// Get the current end time
var end = new Date(timeControl.endTime);
// Calculate midnight on the previous day
end.setDate(end.getDate() - 1);
end.setHours(0, 0, 0, 0);
// Calculate the start date 24hrs earlier
var start = new Date(end);
start.setDate(end.getDate() - 1);
start.setHours(0, 0, 0, 0);
// Set times on the time control
timeControl.setTimeWindow(start, end);
//////// END OF SCRIPT ////////
}

5. Add a script to the onclick event of the NextDay element:

function NextDay_onclick
{
//////// START OF SCRIPT //////// if (timeControl === null || typeof timeControl === "undefined") {
timeControl = getPrimaryTimeControl();
}
// Get the current end time
var end = new Date(timeControl.endTime);
// Calculate midnight on the next day
end.setDate(end.getDate() + 1);
end.setHours(0, 0, 0, 0);
// Jump back a day if it's a future date
if (Date.now() < end.getTime()) {
end.setDate(end.getDate() - 1);
}
// Calculate the start date 24hrs earlier
var start = new Date(end);
start.setDate(end.getDate() - 1);
start.setHours(0, 0, 0, 0);
// Set times on the time control
timeControl.setTimeWindow(start, end);
//// END OF SCRIPT ////////
}

5. Scripting Performance

5.1 Overview

This section covers some tips for authoring scripts to improve the performance of displays.

5.2 Using general section functions in a display

Sometimes you may need to repeat the same functionality for many elements in a display. It can be easy to use copy and paste to replicate the same script across multiple elements in a display.

However, this is not an ideal solution. It makes the display harder to maintain and larger in size than necessary, making the display slower to call up.

You can improve the maintainability and performance by using general section functions in the display to provide the required common functionality, and calling those functions with scripts from the event scripts for the relevant objects.

The performance improvements are particularly significant if there are multiple instances of the script in a display.

Example

Before

You have 10 alphanumerics that execute standard flow calculations. You copy and paste the script for each alphanumeric so that there are 10 copies of the same script in each alphanumeric's onupdate event.

function alpha001_onupdate
{
Do standard flow calculations based on alpha001.value (eg. 10
lines of script)
Update UI of alpha001 based on the result
}

function alpha010_onupdate
{
Do standard flow calculations based on alpha010.value (eg. 10
lines of script)
Update UI of alpha010 based on the result
}

After

To improve the performance of the display, you write the following general section function called “standardFlowCalculations”.

function standardFlowCalculations(inputvalue) {
Do standard flow calculations based on inputValue (eg. 10 lines of
script)
Return result
}

You then update the script in each alphanumeric's onupdate event to call the general
section function.

function alpha001_onupdate
{
var result = standardFlowCalculations(alpha001.value); // only 1
line
Update UI of alpha001 based on the result
}

function alpha010_onupdate
{
var result = standardFlowCalculations(alpha010.value); // only 1
line
Update UI of alpha010 based on the result
}

5.3 Using script holder shapes

Shapes provide the ability to create a “custom object" that can be easily re-used within a display and across displays. When a shape is inserted into a display, the visual elements as well as the scripts are added to the parent display.

If a particular shape is inserted multiple times to a display, this will result in the same scripts being added to the display multiple times. This makes the display larger in size than necessary making the display slower to call up.

You can improve the performance by using general section functions in a separate shape that is not repeated in the display. General section functions in the display and from any inserted shape and can be called from any of the elements or shape elements in the display.

The performance improvements are particularly significant if there are multiple instances of the shape in a display.

Example

Before

You have a shape “flowmeter.sha” that represents a flowmeter. You insert this shape 10 times into the display. The "flowmeter.sha” shape has script in both the alphanumeric's onupdate event and general section.

function standardFlowCalculations(inputvalue) {
Do standard flow calculations based on inputValue (eg. 10 lines of
script)
Return result
}

After

To improve the performance of the display, you create a new shape called "scriptholdershape.sha" and write the following general section function called "updateFlowMeterElement” in the shape. You insert a single instance of the "scriptholdershape.sha" into the display.

function updateFlowMeterElement(inputElement) {
Do standard flow calculations based on inputElement.value (eg. 10
lines of script)
Update UI of inputElement based on the result
}

You then update the onupdate event script in “flowmeter.sha” to reference the general script function in the other shape.

function alpha001_onupdate
{
updateFlowMeterElement(this);
}

function alpha010_onupdate
{
updateFlowMeterElement(this);
}