Scripts in Graphics

The Evaluation Editor allows you to create expressions based on the calculations and results of multiple data points or properties. These expressions are created when you select Script from the Type drop-down menu in the Expression area of the editor. You can also apply the calculations to the Condition field. The Script expressions use the JavaScript syntax based on the ECMA standard for JavaScript (Standard ECMA-262 5.1 Edition).

The Read, ReadCnsDescription, and Trace methods statements are specifically created to work with the system:

  • The Read method allows you to obtain the current value of the specified data point.
  • The ReadCndDescription method allows you to obtain the current description of the specified data point.
  • The Trace method lets you log a trace message to the trace channel Graphics.Scripting module. To view these graphic scripting related trace messages, you must enable the Trace module in the Trace Viewer application.

Script expressions are helpful when creating graphics that display changing values, like a sensor, or for displaying positive and negative room pressure. You can also use the Script feature to create an expression for a floor plan that changes color based on how far the zone temperature is from the setpoint. For script examples, see Script Scenario.

Local Variables and Functions Applied Globally

All graphic scripts within the same System Manager use the same script engine. This means that all local variables and functions actually have the same global scope.

Example: A graphic contains two text elements:

Text Element One - Script: var x=3; x;

Text Element Two - Script: var y=x+1; y;

A possible outcome for the value of the text element scripts are: 3 for text element one, and 4 for text element two. However, the resulting values depend on the order the scripts are executed and that cannot be determined. The next time text element two script runs, the outcome for the value could show an error stating x is not defined.

Information

NOTE:
Using variables in a script is not an issue, even when two scripts on the same graphic use the same variable name. Scripts are not interrupted by other scripts; therefore, for the execution time the variable remains untouched.

 

Basic Rules about Variables and Identifiers

A variable in programming and JavaScript acts as a storage area for a value. All variables must be identified with unique names within your script. These unique names are called identifiers.

Below are a few rules for constructing names for variables and their unique identifiers.

  • Can contain letters, digits, underscores (_), and dollar signs ($)
  • Must begin with a letter
  • Can also begin with $ and _
  • Are case sensitive
  • Cannot have spaces

 

Script Expressions Requirements
  • JavaScript objects are strings, numbers, math operators, arrays, and so on.
  • The expressions support the following operators: +, -, *, /, %, ++ and –, in addition to common operations like math.abs(),math.max(), math.min(), math.sqrt(), math.average(), and math.sum(), etc.
  • A Script expression is evaluated when a graphic is loaded, or a data point value changes.
  • You can drag a data point reference from System Browser to any space in the Script field. When you drag a data point reference, it is automatically inserted with the Read method. See the section on Read() Drag-and-Drop.
  • Do not use global data in a script without declaring and initializing the data in the same script.
  • Script syntax errors are indicated by a red frame around the Expression field and a tooltip displaying the actual error. A warning trace message is also logged.

 

Script Reference Tables

The tables below provide a brief overview of some of the expressions you can write using the Script feature. Refer to these tables when creating your own scripts.

Read Method

The Read, ReadCnsDescription, and Trace methods are three statements specifically created to work with the system. The Read method allows you to obtain the current value of the specified data point; the ReadCnsDescription allows you to obtain the current value of the specified data point; and the Trace method lets you log a trace message to the trace channel Graphics.Scripting module. To view these graphic scripting related trace messages, you must enable the Trace module in the Trace Viewer application.

Read Method

Expression

Result

Read("System1.LogicalView:Logical.Site'AS01.B.Ahu10.FanSu;")

Displays the current value of the data point.

Read("{*}")

Displays the value of the object reference.

Read("System1.LogicalView:Logical.Site'AS01.B.Ahu10.FanSu;.Value") - Read("System1.LogicalView:Logical.Site'AS01.B.Ahu10.FanSu;.SetPoint")

Displays the difference between the two properties of the data point.

(Read("System1.LogicalView:Logical.Site'AS01.A;.Value") +
Read("System1.LogicalView:Logical.Site'AS01.B;.Value")/ 2

Displays the average value between the two properties.

Read() Drag-and-Drop Support

You can drag a data point reference from System Browser to anywhere in the multiline Script field. It is automatically inserted with the Read()-method, unless you press the SHIFT key.

The figure below displays dragging a data point reference into the Evaluation Editor Expression field for a script evaluation.

Resulting in the read method directly applied to the dropped data point:

? Operator in the Read Method

In the Read method, the question mark operator (?) can be used as part of the data point designation. If at least one designation ends with a question mark - then the element is hidden if a data point referenced by the current Read method does not exist. See the last example in the table below.

? in the Read Method

Expression

Result

Read("System1.LogicalView:Logical.Site'AS01.B.Ahu10.FanSu;?-1")

The current value of the data point, if it exists.

1 - This displays if the data point does not exist.

Read("System1.LogicalView:Logical.Site'AS01.B.Ahu10.FanSu;?")

The current value of the data point, if it exists.

The element on the canvas is hidden, if the data point does not exist.

Read("{*dp1}?{*dp2}?99")

Expression in a symbol: Returns the value of data point 1 or data point 2

99. This displays if neither data point nor property exists.

Read("xyz?dp1") + Read("xyz?abc?4")

The value of data point 1 + 4

Read("dp1?") + Read("xyz")

Null. The element is hidden, even if data point 2 exists.

 

ReadCnsDescription Method

The ReadCnsDescription method returns the current description of the specified data point when the data point path is enclosed in parentheses. In this case the specified data point is a string. In Expressions, all strings must be enclosed in quotation marks (“ “). It is important to use quotation marks because data point designations can already contain single quotes (’).
NOTE: In the Text Properties view, the Text type property must be set to: Raw Value. The data point must be online. If the data point is offline (#COM) the data point is not processed in the script.

The description is dynamically updated based on the view the data point is located in. Therefore, the description returned for a data point may vary.

ReadCnsDescription Method

Expression

Result

ReadCnsDescription("System1.LogicalView:Logical.Site'AS01.B.Ahu10.FanSu;")

Displays the current description of the data point.

ReadCnsDescription("{*}")

Displays the description of the object reference.

ReadCnsDescription ("System1.LogicalView:Logical.Site'AS01.B.Ahu10.FanSu;.Value") + ReadCnsDescription ("System1.LogicalView:Logical.Site'AS01.B.Ahu10.FanSu;.SetPoint")

Displays the concatenation of the two or more properties of the data point.

NOTE: You can only add (+) strings together; you cannot use the (-) subtraction operator.


? Operator in the ReadCnsDescription Method

In the ReadCnsDescription method, the question mark operator (?) can be used as part of the data point designation. If at least one designation ends with a question mark - then the element is hidden if a data point referenced by the current ReadCndDescription method does not exist. See the last example in the table below.

? in the ReadCnsDescription Method

Expression

Method Result

ReadCnsDescription("System1.LogicalView:Logical.Site'AS01.B.Ahu10.FanSu;?-1")

The current description of the data point, if it exists.

1 - This displays if the data point does not exist.

ReadCnsDescription ("System1.LogicalView:Logical.Site'AS01.B.Ahu10.FanSu;?")

The current description of the data point, if it exists.

The element on the canvas is hidden, if the data point does not exist.

ReadCnsDescription ("{*dp1}?{*dp2}?99")

Expression in a symbol: Returns the description of data point 1 or data point 2

99 displays if neither data point nor property exists.

ReadCnsDescription("xyz?dp1") + Read("xyz?abc?4")

The description of data point 1 concatenated with the Read result.

ReadCnsDescription("dp1?") + Read("xyz")

Null. The element is hidden, even if data point 2 exists.

 

Trace Method

The Graphic.Scripting channel must be enabled in the Trace Viewer application for the Trace method to work. Refer to the Help section of the Trace Viewer for more information on enabling a trace channel.

Trace Method

Expression

Result

var x = 1 +2;

Trace("Value is " + x);

3 and the string Value is 3 is logged under Message Text in the Trace Viewer

Common JavaScript Examples

The table below provides you with common JavaScript examples. Note that the "//" is not a part of the syntax. In JavaScript "//" indicates a comment.

Common JavaScript Examples:

Expression

Result

math.abs(3.4) // absolute

3

math.average (10, 20) // average

15

math.max (1.5, 2) // maximum

2

math.min(1.5,2) // minimum

1.5

math.sum (1,2,3) // sum

6

12%5 // % (modulus)

2

math.sqrt(9) // square root

3

var str = "Hello";

str.indexOf("el");

1

var value = ["A", "B", "C"];

value[1] + "." + values.length

"B.3"

Type Conversion

The Type Conversion

Expression

Result

7 > 2 * 3

True. Same as: 7 > (2*3)

(7 > 2) * 3

3, because True is converted to 1

Braces and Substitutions

Braces are reserved for substitutions and the substitutions are resolved prior to the Script evaluation. Therefore, when a brace is part of the Script, two braces are used.

Curly Brackets\Substitutions

Expression

Result

var result = 1;

if (true)

{{

   var x = 2;

   result += x;

}}

result;

3

var f1 = function()

{{

   var result="a";

   if (false)

   return "x";

   return result + "b";

}}

f1();

Ab

var result = 1;

try

{{

   throw("my error");

   result = 2;

}}

   catch (e)

{{

   Trace(e);

   result = 3;

}}

result;

3 and the message my error is logged.


Graphics Editor - Script vs. Reference

Executing a script is generally slower than evaluating a Reference expression. Try to limit the usage of script when possible.

The following are recommendations for librarians:

  • Use scripts for symbol in a graphic. However, do not use a script if the symbol is displayed in a graphic more than 5 times, this number includes all nested symbols.
  • Use scripts to remove elements from a symbol.
  • Use scripts to reduce the number of substitutions, evaluations or conditions.
  • Limit the number of Read() calls.
  • Limit the number of if or while statements. Scripts should not be complex.
  • If a task can be done with a Reference expression, use that before writing a script expression. See the Reference versus Script example.

Script vs. Reference Example

In this example, the objective is to hide the element on the graphic if the value of a given data point (dp1) is larger than the value of 25. The element property Visible receives the evaluation of the expression and depending on the value of the data point, the element is either visible on the graphic or not.

The first example illustrates a Script expression for this scenario.

And, below, is the same evaluation, however, a straightforward Reference expression is used instead.

In this example, the Reference expression is more efficient than a Script expression.

 

Graphics Editor - Script Timeout

All scripts within the same System Manager are executed sequentially and can slow down other graphics that also contain scripts. In order to avoid script delays or scripts blocked by scripts in other graphics, every script has a maximum running time of 4 seconds. After that, the script is stopped and returns a null, as follows:

  • Text element displays: #COM
  • Trace displays: WARNING

 

Scripting Scenario: Changing Floor Plan Color

You can create areas of a floor plan that change color based on how far the zone temperature is from the setpoint. This is typically done by drawing a polygon, rectangle, or path element on a floor plan graphic. The Fill property color of the element is used to determine the color of the "room" based on the temperature. The Fill color changes represent a gradient blue (too cold), to white (just right), to red (too hot), depending on how it compares to the setpoint.

The following examples illustrate how you can use the Script feature in the Evaluation Editor, to create a color-changing floor plan according to the actual temperature. Multiple examples are provided to illustrate the scope of using Script with property evaluations. Example 1, the simplest evaluation of the three, is the recommended method for using script for this scenario.

The following examples illustrate how you can use the Script feature in the Evaluation Editor, to create a color-changing floor plan according to the actual temperature. Multiple examples are provided to illustrate the scope of using Script with property evaluations. Example 1, the simplest evaluation of the three, is the recommended method for using script for this scenario.

Script Example 1 (Recommended)

This is the most straightforward and simplest form of using script in an evaluation to represent a changing Fill color of an element. A Discrete type of evaluation with conditions is used. And, a script using two Read() methods is used. The script reads the actual temperature object reference and subtracts the value of the setpoint object reference. The value is examined by the evaluation, and depending on the value, the appropriate condition is chosen and the Fill color is changed.

 

 

Script Example 2

This example also uses a Discrete type of evaluation with conditions. However, the script declares and uses substitution variables in the script to determine which condition is applied to the Fill color.

 

 

 

 

 

/* The variables used in the script must first be declared. The first two variables are ActualTemp and SetPointTemp.*/

var ActualTemp = Read("{*}");

 

/*Substitution reads default Object Reference by looking at the value derived from the property of a data point.*/

var SetPointTemp = Read("{SetPoint}");

 

/*The value is derived by looking at whatever value was entered for the substitution.*/

var TemperatureDifference = ActualTemp - SetPointTemp;

 

/*Declares the variable TemperatureDifference which is equal to the value of the ActualTemp minus the value of the SetPointTemp.*/

var ColorValue = 0;

 

/*Declares the variable ColorValue, which will represent the condition chosen in the evaluation. If the ColorValue is = "0" then the Fill is transparent.*/

if(TemperatureDifference >= 6)

{{

    ColorValue = 1;

}}

 

/*This scope block states, that if the TemperatureDifference value is greater than or equal to 6, then, the ColorValue is set to "1", which in the section of the evaluation conditions is equal to the color #FFCB1737.*/

else if(TemperatureDifference >= 4)

{{

    ColorValue = 2;

}}

 

/*This scope block states, that if the TemperatureDifference value is greater than or equal to "4", then, the ColorValue is set to"2", which in the section of the evaluation conditions is equal to the color #FFFF0000.*/

else if (TemperatureDifference >= 2)

{{

    ColorValue = 3;

}}

 

/*This scope block states, that if the TemperatureDifference value is greater than or equal to 2, then, the ColorValue is set to "3", which in the section of the evaluation conditions is equal to the color #FFFFC0CB.*/

else if (TemperatureDifference <= -6)

{{

ColorValue = 4;

}}

 

/*This scope block states, that if the TemperatureDifference value is greater than or equal to -6, then, the ColorValue is set to "4", which in the section of the evaluation conditions is equal to the color #FFADD8E0.*/

else if (TemperatureDifference <= -4)

{{

    ColorValue = 5;

}}

 

/*This scope block states, that if the TemperatureDifference value is less than or equal to -4, then, the ColorValue is set to "5", which in the section of the evaluation conditions is equal to the color #FF0000FF. */

else if (TemperatureDifference <= -2)

{{

    ColorValue = 6; /*really cold */

}}

 

/*This scope block states, that if the TemperatureDifference value is less than or equal to -2, then, the ColorValue is set to "6", which in the section of the evaluation conditions is equal to the color #FF000080.*/

ColorValue;

 

/*This indicates the result of the script, which determines which value is used and which condition will be used to determine the color of the Fill property in the evaluation.*/

Script Example 3

This example, is a more complicated use of Script for the original scenario. In this example, a Simple evaluation type is used. Therefore, unlike the Script Examples 1 and 2, this example does not use the Condition fields. Instead, the script is used to create the hexadecimal color value for the Fill color depending on the temperature difference of the room.

 

 

 

 

/*The variables for the evaluations are declared.*/

var ActualTemp = Read("{*}");

 

/*Substitution reads default Object Reference by looking at the value from the property of a data point.*/

var SetPointTemp = Read("{SetPoint}");

 

/*Reads value declared for the substitution.*/

var Range = Read("RangeValue)");

 

/*RangeValue substitution value defines a threshold range ratio. Provides backdrop for the opacity range to apply depending on the difference from the Setpoint and the actual temperature.*/

var TemperatureDifference = AcutalTemp - SetPointTemp;

 

/*Establishes the temperature difference.*/

var ColorValue = "#" + "00";

/*Declare the initial value of the color with the Alpha Channel initialized and "0" opacity in hexadecimal notation.*/

 

/*The evaluations begin.*/

if(TemperatureDifference >3)

 

/*If the temperature difference is greater than "3". Now determining an opacity for the color "red"*/

{{

var OpacityValue = math.abs(255*ActualTemp)/Range);

 

/*absolute value established to obtain an opacity value.*/

 

OpacityValue = math.round(OpacityValue);

 

/*Value rounded to a whole number - no decimal is hexadecimal color references.*/

 

if (OpacityValue > 255)

       OpacityValue = 255;

 

/*OpacityValue is capped at 255. Hexadecimal values are between 1-255*/

 

 

 

/*Construction of the hexadecimal color reference starts, now that all variables declared*/

 

var OpacityHexValue = OpacityValue.toString(16);

    ColorValue = "#" + OpacityHexValue + "FF0000"; //red

 

/*OpacityValue converted to a hexadecimal value. The hexadecimal notation is supplied and the value of the opacity value is added for the color "FF0000" (red)*/

}}

 

 

/*Constructing the evaluation if the temperature is less than 3 - we are covering the other end of the spectrum - in our case to represent a cooler temperature difference with the color blue.*/

if(TemperatureDifference < 3)

{{

    var OpacityValue = Math.abs((255 * (Range - ActualTemp)) / Range);

           OpacityValue = Math.round(OpacityValue);

    if (OpacityValue > 255)

           OpacityValue = 255;

    var OpacityHexValue = OpacityValue.toString(16);

    ColorValue = "#" + OpacityHexValue + "0000FF"; //blue

}}

result = ColorValue;

 

/*Color value is now set. Returns value that sets the Fill property.*/

 

Related Topics

For workspace overview, Evaluation Editor View.

For related procedures, see Defining Evaluations

For an alternate workflow for changing the floor plan color, see Changing the Color of Elements Based on Event Conditions