Client Script Library Reference

Web HMI provides some useful client script utilities for developers who wish to have more control over application behavior. The following objects and functions are available to use:

OPC.authenticate(string, string)

Pass in a username and password to perform a server authentication call. Once complete, all tag data requested from the server will occur within that user’s context and bound to that user’s permissions. If the user does not have access to a given tag, no value will be returned. The authentication is performed asynchronously, and will take effect when either the call completes successfully or fails. Upon completion or failure, the OPC.token value will be updated. Upon failure, the OPC.token will be set to “AUTH FAILURE” when there is a communications issue, but will be set to a GUID token for all other results. Note: the user identity and permissions are managed within the Open Automation Software Server:

OPC.get_value(string)

Pass in a tag as a string to get the current value for that tag:

OPC.set_value(string, string)

Pass in a tag as a string, and a new value and that value will be set on the server:

OPC.toggle_refresh(bool)

Temporarily disable or re-enable server polling for new tag values. If no parameters are passed in, polling will toggle, turning off when currently active, or back on when suspended. To explicitly start or stop polling, pass in a boolean true or false, respectively:

OPC.init()

Reinitialize the client script library and begin polling. Use this function if there is ever a need to update any configuration settings, for example if you ever choose to programmatically point to a different serverURL, add tags to the watch_tags array, or add elements to the screen to be parsed and managed by Web HMI behaviors:

HTML Attribute Reference

Text

Sets the text attribute of an element based on the value of a server tag. This is most useful for setting the content of elements like div or anchor. If you need to set the value of an input element (e.g. text input field) use the Value attribute.
attribute: opc-tag-txt
type: Tag
examples:
Simple example of live raw data being added to the text of an HTML element

Example of live data being added to the text of an HTML element with string formatting applied, and a default display of ‘????’ when bad data quality is detected.

Example of both string and numeric formatting applied to limit to 3 decimal places, and a default display of ‘????’ when bad data quality is detected.

Value :

Sets the value attribute of an element based on the value of a server tag. This is most useful for setting input fields like text boxes and buttons.
attribute: opc-tag-val
type: Tag
examples:
Simple example of live raw data being added to the value of an HTML input element

Background:

Sets the background style of the element according to the value and quality of one or more server Tags. This allows you to use a single HTML element to represent the state of multiple server values.
attribute: opc-tag-bkg
type: Tag Group
example:
Using a single boolean tag to set the background of a button element between Green(true) and Red(false) or Yellow(bad data)

Foreground:

Sets the foreground style of the element according to the value and quality of one or more server Tags. This allows you to use a single HTML element to represent the state of multiple server values.
attribute: opc-tag-fg
type: Tag Group
examples:
Using a single boolean tag to set the foreground of a button element between White(true) and Yellow(false) or Red(bad data)

Combining both background and foreground color settings to create a unique style

Border :

Sets the border style of the element according to the value and quality of one or more server Tags. This allows you to use a single HTML element to represent the state of multiple server values.
attribute: opc-tag-brd
type: Tag Group
examples:
Using a single boolean tag to set the border color of a button element between White(true) and Yellow(false) or Red(bad data)

Combining background, foreground, and border color settings to create a unique style

Image Source :

This attribute is designed to be used with an HTML <img> tag. It sets the src attribute of of the image according to the value and quality of one or more server Tags. This allows you to use a single HTML element to represent the state of multiple server values.
attribute: opc-tag-src
type: Tag Group
  • config:
  • relative or absolute URL of an image
examples:
Using a single boolean tag to set the image to display

Background Flash :

Causes the background of an element to change or alternate as the result of a trigger
attribute: opc-tag-bg-fl
type: Tag
examples:
Using a single boolean tag to flash a background color when true

Foreground Flash :

Causes the foreground style of an element to change or alternate as the result of a trigger
attribute: opc-tag-fg-fl
type: Tag
examples:
Using a single boolean tag to flash a background color when true

Border Flash :

Causes the border style of an element to change or alternate as the result of a trigger
attribute: opc-tag-brd-fl
type: Tag
examples:
Using a single boolean tag to flash a border color when true

Tooltip :

Sets the tooltip text of an element based on the value of a server tag. This text is displayed when the user hovers over the element.
attribute: opc-tag-tt
type: Tag
examples:
Setting an element’s tooltip value with a tag (hover over button to see value)
NOTE:Not all browsers will display the tooltip, but the title attribute of the element will be set and could still be used for screen readers or other applications

Enable :

Enables an element based on a trigger
attribute: opc-tag-en
type: Tag
  • config:
  • trigger
  • bad_q— when false, disables the element when data quality is bad
examples:
Disables an element based on a tag value or data quality

Visible :

Shows or hides an element based on a trigger
attribute: opc-tag-vis
type: Tag
  • config:
  • trigger
  • bad_q
    — if set to false, will disable the element when data quality is bad

example:

Opacity :

Sets the element’s opacity based on the value of a server tag
attribute: opc-tag-op
type: Tag
  • config:
  • formats
    — optionally used to force a value if data quality is bad
  • gain
  • offset

example:

Width :

Sets the element’s width based on the value of a server tag
attribute: opc-tag-wd
type: Tag
  • config:
  • formats
    — optionally used to force a value if data quality is bad
  • gain
  • offset

example:

Height :

Sets the element’s height based on the value of a server tag
attribute: opc-tag-ht
type: Tag
  • config:
  • formats
    — optionally used to force a value if data quality is bad
  • gain
  • offset

example:

Scale-X :

Sets the element’s horizontal scale based on the value of a server tag. The scale is always applied to the original size of the element. For example, if the element is defined on the page as 100px wide, and a server tag value is 2.5, the width will then become 250px. If the server value then changes to 1.0, the element will return to 100px wide.
attribute: opc-tag-sx
type: Tag
  • config:
  • formats
    — optionally used to force a value if data quality is bad
  • gain
  • offset

example:

Scale-Y :

Sets the element’s vertical scale based on the value of a server tag. This is used the same way as Scale-X.
attribute: opc-tag-sy
type: Tag
  • config:
  • formats
    — optionally used to force a value if data quality is bad
  • gain
  • offset

example:

Translate-X :

Sets the element’s horizontal position based on the element’s original position. This requires that the element uses absolute positioning.
attribute: opc-tag-tx
type: Tag
  • config:
  • formats
    — optionally used to force a value if data quality is bad
  • gain
  • offset

example:

Translate-Y :

Sets the element’s vertical position based on the element’s original position. This is used the same way as Translate-X.
attribute: opc-tag-ty
type: Tag
  • config:
  • formats
    — optionally used to force a value if data quality is bad
  • gain
  • offset

example:

Set :

Binds a client-side event, and sets a value on the server for a given tag.
attribute: opc-tag-set
type: Tag

example 1 – simple boolean toggle:


example 2 – toggle with confirmation dialog:

example 3 – user input:

example 4 – customized input dialog:

example 5 – using a value from another field. Use the set_src for the value to be submitted for the tag. This should be the element id holding the new value:

Top Level Classes – JSON Type Reference


Custom Attributes each have a specific format that they are expected to follow, but all attribute configurations are one of the following forms:

Tag:

Used for binding a single server tag to a single attribute on an element.

Definition:

tag : string : a string representing the server tag to monitor for this attribute

config : Config : a detailed configuration that describes how to alter the element based on the server tag

Example:

Tag Group:

An array of Simple Tag configurations used to set up a hierarchy of behaviors. Each configuration is evaluated in order and the first tag to evaluate as boolean true will be used to modify the associated element.

Definition:

type : string : must be hard-coded as “group”

all_f : Config : optional configuration to use if all Tags in the group evaluate to false

bad_q : Config : optional configuration to use if any Tag produces bad quality data from the server

group : [Tag] : an array of Tags, evaluated in order, establishing a hierarchy of behaviors. The first Tag to evaluate as boolean true will dictate the element behavior, and no subsequent Tags in the group will be evaluated.

Example:

Config:

Never used on its own, the Config is applied to several other attributes to define specific behaviors. All Config attributes are optional as they may or may not apply to the Custom Attribute in question.

Definition:

formats : Formats : used for formatting data values, used with the opc-tag-txt and opc-tag-val attributes

style : string : an inline CSS style string to apply directly to the element when the tag value evaluates to TRUE

cls : string : a CSS class name to apply to the element when the tag value evaluates to TRUE

color : string : a foreground color to apply to an element, either a color name or hex value (e.g. #ffcc00) when the tag value evaluates to TRUE

img : string : an image path to be applied to the element (e.g. when used with the opc-tag-bg)

img-pos : string : a position string to be applied to the background image, in the form “offset-x offset-y”, for example: “20px 5px”

rate : integer : used in conjunction with repeat, the interval in milliseconds between changes, defaults to 200 if omitted

repeat : integer : the number of times to toggle a change, primarily used with flashing attributes

bad_q : bool : indicates that the configuration is to be used when the server tag data quality is bad

trigger : string : when to trigger a change to the element. Valid values are:

on_true : when the server tag evaluates to TRUE

on_false : when the server tag evaluates to FALSE

trans : when the server value changes

trans_true : when the server value changes to TRUE from FALSE

trans_false : when the server value changes from FALSE to TRUE

fn : string : the name of a function to execute when the trigger condition is met

gain : decimal : a multiplier applied to a server tag value before being applied to an element. For example if a server value fluctuates between 0.0 and 1.0, but you wish to transform this to a range between 0.0 and 100.0, set the gain to 100. This may be combined with offset for finer control.

offset : decimal : a value added to a server tag value before being applied to an element. For example if a server value fluctuates between 0.0 and 50.0, but you wish to transform this to a range between 10.0 and 60.0, set the offset to 10. This may be combined with gain for finer control.

set : string : used only with opc-tag-set, the method used to set a tag value on the server. Valid values are:

toggle : negate the current server boolean value so TRUE becomes FALSE, and FALSE becomes TRUE

input : display an input dialog allowing users to manually enter the value sent to the server

value : send either the element’s value to the server (default), a fixed value defined by the set_value configuration, or the value of element with an id defined in theset_src configuration

set_src : string : used only with a set of value, the client id of the element to provide a value, for example a separate text input field on the page.

set_value : string : used only with a set of value, a hard-coded value to always send to the server, for example FALSE when creating an explicit “off” button.

evt : string : used only with set, the client-side event on the element to trigger a server value being set. Valid values are:

click : clicking the element

dbl-click : double-clicking an element

change : when an element’s value changes, for example when a text input box value is changed by a user

set_confirm_buttons : string : used only with a set value if input, this determines the text values on the dialog buttons.

ok : OK/Cancel (default if omitted)

yesno : YES/NO

set_confirm_msg : string : used only with a set value if input, a message displayed in the input dialog.

set_confirm_title : string : used only with a set value if input, a title displayed in the header of the input dialog.

ignore_prefix : bool : used only if a tag_prefix is being used on the main config, and the current tag should not use the prefix.

Formats:

Used for formatting data values for display

Definition:

bad_q : string : the string to display when the server tag yields bad data

str : string : a format string that replaces a “{0}” string with the server tag value. For example if you use the string “The value is {0}”, and the server tag value is 27.3, the resultant string will be “The value is 27.3”

bool_f : string : the string to display when the server tag evaluates to boolean false. For example “No”, or “F”

bool_t : string : the string to display when the server tag evaluates to boolean true. For example “Yes”, or “T”

int : string : a numeric formatting string for integer values, Formatting syntax is identical to float but decimal separator is ignored

float : string : a numeric formatting string for decimal/float values. Formatting syntax can be found here (https://code.google.com/p/jquery-numberformatter/)

locale : string : a localization string which influences how separators and decimals are represented. Default is “us” for United States if no locale is included in the main config.

Marking up HTML Elements

Marking up element tags with specialized attributes

The simplest and most direct method of binding HTML elements to server Tags is to mark up the element tag with one or more specialized attributes. Each attribute represents a behavior added to the HTML element, tied to the value and state of a Tag or set of tags. For example, if you wish to display the current value for the Ramp.Value tag within a text box, you would use the opc-tag-val attribute:

Web HMI Wizard

To learn how to use each of the markup attributes, you can use the interactive Web HMI Wizard to generate working example code.

Values are valid JSON

The value of the opc-tag-val attribute, like all opc-tag- attributes must be valid JSON. Each attribute requires a specific JSON structure for defining the element behavior, but the JSON structures consist of specific types and sub-types. For example, a simple opc-tag-value attribute expects JSON in the format:

For this attribute the config is optional, and would contain settings used to format the server Tag value for display. If you want to apply formatting to the server Tag value, you would use the formats setting in the Config:

Tying it all together

Tying this all together, if the server tag Pump.Value is a boolean, and you want “YES” and “NO” to be displayed in a text box instead of True or False, the full HTML markup would be:

Other Configuration Options

The Javascript OPC_config variable contains several options for determining the behavior of the Script Library. This variable is a standard JSON construct. The full definition with defaults displayed is:

debug: bool

Display debug logging messages within a browser debug console. You can hook into this logging mechanism as well, by calling OPC.log(obj).

debug_refresh: bool

Display verbose log messages on each ajax callback to the Open Automation Software Server. This can be useful during development when you want to see the raw data being returned by the server.

interval: int

The number of milliseconds between each refresh callback to the server to get new data.

auto_start: bool

When set to true refresh callbacks will begin immediately after authentication with the token or when OPC.authenticate() is called successfully. If you would like to defer refreshes, set this to false and call OPC.toggle_refresh(true) to begin receiving new data.

token: string

The authentication token sent to the server on each refresh callback

serverURL: string

The location of the Open Automation Software Server

locale: string

An optional string indicating the default locale to use when formatting numeric values. The default is ‘us’ for United States. Other options are:

  • Arab Emirates: “ae”
  • Australia: “au”
  • Austria: “at”
  • Brazil: “br”
  • Canada: “ca”
  • China: “cn”
  • Czech: “cz”
  • Denmark: “dk”
  • Egypt: “eg”
  • France: “fr”
  • Finland: “fi”
  • Germany: “de”
  • Greece: “gr”
  • Great Britain: “gb”
  • Hong Kong: “hk”
  • India: “in”
  • Israel: “il”
  • Japan: “jp”
  • Russia: “ru”
  • South Korea: “kr”
  • Spain: “es”
  • Sweden: “se”
  • Switzerland: “ch”
  • Taiwan: “tw”
  • Thailand: “th”
  • Vietnam: “vn”

trend_bindings: object

See Web HMI Trend documentation for more details

alarm_bindings: object

See Web HMI Alarm documentation for more details

refresh_callback: function(data)

An optional callback that will be fired on every successful refresh call to the server for data. The data passed into the callback will represent all monitored server tags for the current configuration.

tag_prefix: string

An optional prefix for all server tags. This allows you to use a truncated tag name with inline configurations if the tags all share the same prefix. For example, if your tags are similar to:

You can set the tag_prefix to “MyCompany.Server3.DataValues.” and simply use “Tag1.Value”, “Tag2.Value”, and “Tag3.Value” in the inline configurations.

If you want to include one or more tags that do not follow the same pattern or do not have the same prefix, you must add the ignore_prefix:true setting on that attribute’s config.

max_tags_per_msg: number

An optional value to be used in cases where a firewall or network configuration may limit HTTP request sizes. By default, each call to the server includes a request for data on every monitored server tag.

If the page has a large number of tags, this could result in a rejection by a firewall. Setting the max_tags_per_msg value will split calls to the server, resulting in multiple calls. This will reduce application performance since it will effectively multiply the number of executions by the number of calls needed to cover all server tags.

For example, if your page is monitoring 20 tags, and your max_tags_per_msg is set to 4, your page will be executing 5 calls to the server on each interval.

watch_tags: array of strings

In some cases, you may prefer to read and write tag values programmatically and do not want or need to add opc-tag-xxx attributes to elements inline. This is particularly useful if you need to perform some additional logic or formatting of data within your custom scripts.

If this is the case, then you will need to enumerate the tags to “watch” in a string array. This informs the Web HMI library that it should poll the server for these tag values, making them available to use in custom scripts. This is especially useful when used in conjunction with the refresh_callback, as you’ll be able to programmatically update elements as soon as data is refreshed from the server.

Authentication

To ensure that all requests for server data be performed by an authorized user, the OAS Web HMI Script Library attaches an authentication token to each request. This token is generated by the Open Automation Software Server when provided a valid credential.

The token will expire after a period of disuse, or when the Open Automation Software Server is restarted, so it should be generated dynamically when a page is initially accessed. Options for generating the token are:

  • ASP.NET
  • Other Web Technologies
  • Client-Side Authentication
  • Java Script Authentication

ASP.NET

When a page is initially rendered, a call can be made to the OPC Library to create the token, which can then be embedded in the page header.

VB.NET

C#

The credential used could be taken directly from the user’s login within your application, or it could be a standard credential established on the server for all users.

Other Web Technologies

Similar to ASP.NET, it is recommended that the authentication token be generated on the server so that credentials are not passed from client to server, and are only exchanged in server-to-server communication.

For non-.NET technologies, you can use the REST API to make an authentication call to the Open Automation Software Server.

Client-Side Authentication

If you are operating within a secure network, and are not concerned about passing credentials between clients and the Open Automation Software Server, you can perform the authentication from within client script.

The following Javascript code will perform the server authentication and then begin refreshing the page with server data:

Java Script Authentication

In javascript, code can kick off an authentication by just calling the following:

OPC.authenticate(username,password);

What happens

In context, the steps would be as follows:

  1. Collect some credentials on the client, this can be from a form, or from any other client script
  2. Call OPC.authenticate() using those credentials
  3. The OAS Service will validate the credential and return a token, which will then be applied and used for all subsequent callbacks from the client library.
  4. If you wish to cache this token on the client, you can get it from the OPC.token property, and then use it on other screens in the OPC_config settings so there’s no need to call OPC.authenticate again when switching pages or screens.

Example

Here’s an example in javascript which does all of this. The do_authentication function would be called on a login form that contains username and password fields.

Programming Reference – Web HMI

Overview and Features – Web HMI

The OAS Web HMI provides a flexible, platform-independent way to integrate with Open Automation Software Servers.

  • “Controls” themselves are simply existing HTML elements marked up with attributes that are parsed at runtime, so you are free to use any web technology that you prefer, including (but not limited to) ASP.NET, JSP, PHP, Ruby on Rails, or even static HTML with JavaScript.
  • Easily integrates with existing web applications
  • Based on ubiquitous standard technologies including JavascriptjQueryJSONHTML, and CSS

Requirements

OAS Web HMI requires the following:

  • an instance of an Open Automation Software Server accessible over an internal or external network
  • working knowledge of HTML
  • working knowledge of Javascript

More:

Installation and Configuration

For installing and configuring the Open Automation Software Server, please refer to the product documentation. To configure a web page to communicate with the server, you must include:

  • jQuery v1.8.3 or later, found at jquery.com and is also distributed with the OAS Web HMI product
  • The OAS Web HMI Script Library
  • The OAS Web HMI Stylesheet, which is used for styling modal dialogs and can be modified to fit your web design
  • A small block of Javascript containing an authentication token and URL location of the Open Automation Software Server – configuration options will be detailed below

The following is an example of a properly configured, minimal HTML page:

Of course, this example does not contain any bindings to OPC Server Tags, but contains all elements necessary to connect to a server located at http://localhost:58725 using an authentication token of7e61b230-481d-4551-b24b-ba9046e3d8f2.