Category: Web HMI

The following is a list of markup attributes that can be added to any HTML element. Each attribute adds a behavior, tied to one or more OAS server Tags. You can combine attributes to generate the behavior you desire. If you prefer more control over behavior and would like to write your own logic, see the Client Script Library Reference.

<div id="txt_ex1" oas-tag-txt='{"tag":"Sine.Value"}'></div>

<div id="txt_ex2" oas-tag-txt='{"tag" : "Sine.Value", 
      "config" : {"formats" : {
        "bad_q":"????",
        "string" : "Sine = {0}"}
      }
  }'></div>

<div id="txt_ex3" oas-tag-txt='{"tag" : "Sine.Value", 
      "config" : {"formats" : {
        "bad_q":"????",
        "string":"Sine = {0}", 
        "float":"0.000"}
      }
  }'></div>

<input id="val_ex1" type="text" oas-tag-val='{"tag":"Sine.Value"}'/>

<button id="bkg_ex1" oas-tag-bkg='{
    "type": "group",
    "all_f": {
      "color": "#f00"
    },
    "bad_q": {
      "color": "#fc0"
    },
    "group": [
      {
        "tag": "RandBool.Value",
        "config": {"color": "#0f0"}
      }
    ]
  }'>BUTTON</button>       

<button id="fg_ex1" oas-tag-fg='{
    "type": "group",
    "all_f": {
      "color": "#fc0"
    },
    "bad_q": {
      "color": "#f00"
    },
    "group": [
      {
        "tag": "RandBool.Value",
        "config": { "color": "#fff"}
      }
    ]
}'>BUTTON</button>

<button id="fg_ex2" oas-tag-bkg='{
    "type": "group",
    "all_f": {"color": "#f00"},
    "bad_q": {"color": "#fc0"},
    "group": [
      {
        "tag": "RandBool.Value",
        "config": {"color": "#0f0"}
      }
    ]
  }' oas-tag-fg='{
    "type": "group",
    "all_f": {"color": "#fc0"},
    "bad_q": {"color": "#f00"},
    "group": [
      {
        "tag": "RandBool.Value",
        "config": { "color": "#fff"}
      }
    ]
}'>BUTTON</button>

<button id="brd_ex1" style="border-width: 2px;" oas-tag-brd='{
    "type": "group",
    "all_f": {"color": "#fc0"},
    "bad_q": {"color": "#f00"},
    "group": [
      {
        "tag": "RandBool.Value",
        "config": { "color": "#fff"}
      }
    ]
}'>BUTTON</button>

<button id="brd_ex2" style="border-width: 2px;" oas-tag-bkg='{
    "type": "group",
    "all_f": {"color": "#f00"},
    "bad_q": {"color": "#fc0"},
    "group": [
      {
        "tag": "RandBool.Value",
        "config": {"color": "#0f0"}
      }
    ]
  }' oas-tag-fg='{
    "type": "group",
    "all_f": {"color": "#fc0"},
    "bad_q": {"color": "#f00"},
    "group": [
      {
        "tag": "RandBool.Value",
        "config": { "color": "#fff"}
      }
    ]
  }' oas-tag-brd='{
    "type": "group",
    "all_f": {"color": "#fc0"},
    "bad_q": {"color": "#f00"},
    "group": [
      {
        "tag": "RandBool.Value",
        "config": { "color": "#fff"}
      }
    ]
}'>BUTTON</button>

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: oas-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

<img id="src_ex1" style="width: 55px;" src="https://openautomationsoftware.com/wp-content/uploads/2022/05/Pump-Yellow-Front.png" oas-tag-src='{
    "type": "group",
    "all_f": "https://openautomationsoftware.com/wp-content/uploads/2022/05/Pump-Red-Front.png",
    "bad_q": "https://openautomationsoftware.com/wp-content/uploads/2022/05/Pump-Yellow-Front.png",
    "group": [
      {
        "tag": "RandBool.Value",
        "config": "https://openautomationsoftware.com/wp-content/uploads/2022/05/Pump-Green-Front.png"
      }
    ]
}'/>

<button id="bkg_fl" style="border-width: 2px;" oas-tag-bkg-fl='{
    "tag": "RandBool.Value",
    "config": {
      "color": "#f00",
      "trigger": "on_true"
    }
}'>BUTTON</button>

<button id="fg_fl" style="border-width: 2px;" oas-tag-fg-fl='{
    "tag": "RandBool.Value",
    "config": {
      "color": "#f00",
      "trigger": "on_true"
    }
}'>BUTTON</button>

<button id="brd_fl" style="border-width: 2px;" oas-tag-brd-fl='{
    "tag": "RandBool.Value",
    "config": {
      "color": "#f00",
      "trigger": "on_true"
    }
}'>BUTTON</button>

<button id="tt_ex" style="border-width: 2px;" oas-tag-tt='{"tag": "Sine.Value"}'>BUTTON</button>

<button id="en_ex" oas-tag-txt='{
  "tag": "RandBool.Value",
  "config": {
    "formats": {
      "bool_f": "Enabled",
      "bool_t": "Disabled"
    }
  }
}' oas-tag-en='{
  "tag": "RandBool.Value",
  "config": {
    "trigger": "on_false"
  }
}'>BUTTON</button>

<button id="vis_ex" oas-tag-vis='{
  "tag": "RandBool.Value",
  "config": {
    "bad_q" : false,
    "trigger": "on_true"
  }
}'>BUTTON</button>

<button id="op_ex" oas-tag-op='{
  "tag": "Ramp2.Value",
  "config": {
    "formats" : {
      "bad_q" : 0.25
    },
    "gain" : 2.0
  }
}'>BUTTON</button>

<button id="wd_ex" oas-tag-wd='{
  "tag": "Random.Value",
  "config": {
    "formats" : {
      "bad_q" : 200
    },
    "gain" : 1.0,
    "offset" : 100
  }
}'>BUTTON</button>

<button id="ht_ex" oas-tag-ht='{
  "tag": "Random.Value",
  "config": {
    "formats" : {
      "bad_q" : 50
    },
    "gain" : 1.0,
    "offset" : 50
  }
}'>BUTTON</button>

<button id="sx_ex" oas-tag-sx='{
  "tag": "Ramp2.Value",
  "config": {
    "formats" : {
      "bad_q" : 1.0
    },
    "gain" : 5.0
  }
}'>BUTTON</button>

<button id="sy_ex" oas-tag-sy='{
  "tag": "Ramp2.Value",
  "config": {
    "formats" : {
      "bad_q" : 1.0
    },
    "gain" : 5.0
  }
}'>BUTTON</button>

<div id="tx_ex" style='width:15px;height:15px;background-color:#c33;' oas-tag-tx='{
  "tag":"Ramp2.Value",
  "config":{
    "formats":{
      "bad_q":10
    },
    "gain":100,
    "offset":10
  }
}'></div>

<div id="tx_ex" style='width:15px;height:15px;background-color:#c33;' oas-tag-ty='{
  "tag":"Ramp2.Value",
  "config":{
    "formats":{
      "bad_q":10
    },
    "gain":100,
    "offset":10
  }
}'></div>

{
  "tag":"Pump.Value",
  "config":{
    "evt":"click",
    "set":"toggle"
  }
}

{ 
  "tag" : "Pump.Value",
  "config" : {
      "evt" : "click",
      "set" : "toggle",
      "set_confirm" : true
  }
}

{ 
        "tag" : "Pump.Value",
        "config" : {
            "evt" : "click",
            "set" : "input"
        }
}

{ 
        "tag" : "Pump.Value",
        "config" : {
            "evt" : "click",
            "set" : "input", 
            "set_confirm_msg" : "Please enter a value that will be set for the Pump.Value server tag.", 
            "set_confirm_title" : "Set Pump.Value"
        }
}

{ 
        "tag" : "Pump.Value",
        "config" : {
            "evt" : "click",
            "set" : "value", 
            "set_src" : "element_id" 
        }
}

Tag:

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

Definition:

{
    "tag" : <string>,
    "config" : <Config>
}

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" : "Pump.Value",
    "config" : {
        "color" : "#f00",
        "trigger":"on_true"
    }
}

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" : "group",
    "all_f" : <Config>,
    "bad_q" : <Config>,
    "group" : [<Tag>,..]
}

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:

{
    "type" : "group",
    "all_f" : {"color":"#F00"},
    "bad_q" : {"color":"#FC0"},
    "group" : [
        {
            "tag" : "Pump.Value",
            "config" : {"color":"#00F"}
        },
        {
            "tag" : "Pump2.Value",
            "config" : {"color":"#080"}
        }
    ]
}

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>,
    "style" : <string>,
    "cls" : <string>,
    "color" : <string>,
    "img" : <string>,
    "img_pos" : <string>,
    "rate" : <integer>,
    "repeat" : <integer>,
    "bad_q" : <bool>,
    "trigger" : <string>,
    "fn" : <string>,
    "gain" : <decimal>,
    "offset" : <decimal>,
    "set" : <string>,
    "evt" : <string>,
    "set_src" : <string>, 
    "set_value" : <string>,
    "set_confirm_buttons" : <string>,
    "set_confirm" : <bool>,
    "set_confirm_msg" : <string>,
    "set_confirm_title" : <string>,
    "ignore_prefix" : <bool>
}

formats : Formats : used for formatting data values, used with the oas-tag-txt and oas-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 oas-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 oas-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>,
    "string" : <string>,
    "bool_f" : <string>,
    "bool_t" : <string>,
    "int" : <string>,
    "float" : <string>,
    "date" : <string>,
    "locale" : <string>
}

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 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 oas-tag-val attribute:

<input type="text" id="my-textbox" oas-tag-val='{"tag":"Pump.Value"}' ">

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 oas-tag-val attribute, like all oas-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 oas-tag-val attribute expects JSON in the format:

{
    "tag": "TagName.Property",
    "config" : <Config>
}

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:

{
    "formats": [
        "bad_q": <optional string: displayed when data quality is bad>,
        "string": <optional string: replaces {0} with server value>,
        "bool_f": <optional string: displayed when boolean server value = false>,
        "bool_t": <optional string: displayed when boolean server value = true>,
        "int": <optional string: integer number formatter - see reference>,
        "float", <optional string: float number formatter - see reference>
    ]   
}

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:

<input type="text" id="my-textbox" oas-tag-val='{"tag":"Pump.Value", "config":{"formats":["bool_f":"NO", "bool_t":"YES"]}}' ">

The Javascript OAS_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:

OAS_config =
{
    debug: false,   
    debug_refresh: false,   
    interval: 1000,             
    auto_start: true,       
    token:'',                           
    serverURL:'http://localhost:58725'
};

debug: bool

Display debug logging messages within a browser debug console. You can hook into this logging mechanism as well, by calling OAS.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 OAS.authenticate() is called successfully. If you would like to defer refreshes, set this to false and call OAS.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

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:

MyCompany.Server3.DataValues.Tag1.Value
MyCompany.Server3.DataValues.Tag2.Value
MyCompany.Server3.DataValues.Tag3.Value

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.

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. Note: If the OAS server cannot be reached, the refresh_callback function will not be triggered.

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 oas-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.

OAS_config =
{
    token:'',                           
    serverURL:'http://localhost:58725',
    watch_tags: ["Pump.Value", "Random.Value"],
    refresh_callback: update_screen
};
 
// called on every refresh of data
function update_screen(data) {
    var pump = OAS.get_value("Pump.Value");
    var random = OAS.get_value("Random.Value");
    // your code here 
}

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 or .NET MVC

When a page is initially rendered a call can be made to the OASConfig library to create the token, which can then be embedded in the page header. Within .NET MVC, this authentication call can be made in template code to embed a WebHMI token, or within a controller for accessing OAS data directly or for providing client script access to an authentication token.

VB.NET

Dim un as String = "YourUserName"
Dim pw as String = "YourPassword"
Dim config as new OASConfig.Config()
Dim token as String = config.GetToken(un, pw)
Dim url as String = "http://yourserver:port"
ClientScriptManager.RegisterStartupScript(Me.GetType(), _
    "OASWebToken", _
    "OAS_config = {token:'" + token + "','" + url + "'};", _
    True)

C#

string un = "YourUserName";
string pw = "YourPassword";
OASConfig.Config config = new OASConfig.Config();
string token = config.GetToken(un, pw);
string url = "http://yourserver:port";
ClientScriptManager.RegisterStartupScript(this.GetType(), 
    "OASWebToken", 
    "OAS_config = {token:'" + token + "','" + url + "'};", 
    true);

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 or .NET MVC, 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 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:

$(document).ready(function(){OAS.authenticate("someUser","somePassword");})

Java Script Authentication

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

OAS.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 OAS.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 OAS.token property, and then use it on other screens in the OAS_config settings so there’s no need to call OAS.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.

<script type="text/javascript">
      OAS_config = {
            token:'7e61b230-481d-4551-b24b-ba9046e3d8f2',
            serverURL: 'http://localhost:58725',
            refresh_callback: update_local
      };
 
      function update_local(data){
            // this function is called on every server callback
            if (OAS.token != OAS_config.token) {
                  // the authentication token has been updated
                  // you can now use the token for all subsequent pages within a session
                  OAS_config.token = OAS.token;
            }
      }
 
      function do_authentication() {
            var un = $("#username").val();
            var pw = $("#password").val();
            OAS.authenticate(un, pw);
      }
</script>

If you are interested in visualizing your data in a desktop or mobile browser with zero programming, you may be interested in Getting Started with the Web HMI Dashboard.

Features

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 or .NET MVC, JSP, PHP, Ruby on Rails, or even static HTML with JavaScript.
• Easily integrates with existing web applications
• Based on ubiquitous standard technologies including Javascript, jQuery, JSON, HTML, 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