Advantech AE Technical Share Documentadvdownload.advantech.com/productfile/Downloadfile2/1-13...WA Dashboard: Pluggable Widget Interface Programming Guide Version 1.0.1 Page 3 本資料為研華科技專有之財產，非經書面許可

Page 1 WA Dashboard: Pluggable Widget Interface Programming Guide Version 1.0.1

本資料為研華科技專有之財產，非經書面許可，不准透露或使用本資料，亦不准複印、複製或轉變成任何其它形式使用。

The information contained herein is the exclusive property of Advantech and shall not be distributed, reproduced, or disclosed in whole or

in part without prior written permission of Advantech.

Advantech AE Technical Share Document

Date 2016 / 3 / 10 SR# 1-2392879041

Category ■ FAQ □ SOP Related OS Microsoft Windows7

Abstract WebAccess Dashboard – Pluggable Widget Interface Programming Guide

Keyword WebAccess, Widget, HelloWorld

Description:

This document will show users how to implement a widget in WebAccess Dashboard by

understanding pluggable widget interface. By implementing these widget interfaces and

corresponding JavaScript/CSS/Html files, the widget can support following functionalities:

- Widget drag and drop in Dashboard Editor.

- Widget property setting in Dashboard Editor.

- Refresh data by WebAccess WebService or user defined data source in Dashboard Viewer.

- Support Multi-language

- Support Widget interaction





Contents

HISTORY ...................................................................................................................................5

1 INTRODUCTION ..................................................................................................................6

1.1 OBJECTIVE ..........................................................................................................................6

1.2 DOCUMENT ORGANIZATION ...............................................................................................6

2 REFERENCES .......................................................................................................................7

3 ABBREVIATIONS ................................................................................................................8

4 WIDGET COMPONENTS ...................................................................................................9

4.1 OVERVIEW ..........................................................................................................................9

4.2 WIDGET INTERFACE .........................................................................................................13

4.2.1 Basis of Widget Interface .........................................................................................13

4.2.2 Details of Widget Interfaces .....................................................................................16

getInitStructure() ...............................................................................................................16

drawWidChart() .................................................................................................................18

openSavedWidget() ...........................................................................................................21

getWidgetStructure() .........................................................................................................23

validatePropertyValues() ...................................................................................................24

applyPropertyValues() .......................................................................................................26

showPropertyItems() .........................................................................................................28

loadPropertyValues() .........................................................................................................30

refreshWidValue() .............................................................................................................32

getUploadImgNspaces() ....................................................................................................35

getTextMuiNspaces() ........................................................................................................36

4.3 WIDGET PROPERTY PAGE .................................................................................................37

4.3.1 Design guideline .......................................................................................................37

4.3.2 Common Properties of every Widget .......................................................................39





4.4 WIDGET METADATA .........................................................................................................42

4.4.1 Library Information ..................................................................................................43

4.4.2 Widget Information ..................................................................................................45

4.5 MULTI-LANGUAGE ............................................................................................................49

4.5.1 Prepare the Language Pack ......................................................................................49

4.5.2 For static HTML pages .............................................................................................50

4.5.3 For dynamic content .................................................................................................51

4.5.4 For Generating MUI Dialog in Property page ..........................................................53

4.6 WIDGET INTERACTION ......................................................................................................57

4.6.1 Data Commander Widget .........................................................................................58

4.6.2 Data Follower Widget ..............................................................................................62

5 DASHBOARD APIS ............................................................................................................64

5.1 JAVASCRIPT GLOBAL VARIABLES ....................................................................................64

5.2 APIS IN PARAMETERUTIL .................................................................................................65

5.3 APIS IN COMMONUTIL ......................................................................................................66

5.4 APIS IN DASHBOARDUTIL .................................................................................................66

5.5 APIS IN UIUTIL .................................................................................................................68

5.6 APIS IN DASHBOARDPROPERTY ........................................................................................70

5.7 APIS IN DASHBOARDCOMMON .........................................................................................71

5.8 APIS IN DATASOURCEUTIL(VIA AJAX) .............................................................................71

5.9 APIS IN DATASOURCEUTILRT(VIA SIGNALR) ...................................................................96

5.10 APIS IN WEBCOMMUNICATOR ......................................................................................106

5.11 APIS IN DATASOURCEUTILCOMBO ..............................................................................106

5.12 APIS IN VALIDATEUTIL ................................................................................................118

5.13 APIS IN WIDGETUTIL ....................................................................................................118

APPANDAX A: ABOUT BEMS ..........................................................................................120





A.1. VALUE OF “BEMSBUILDINGINFO” GLOBAL PARAMETER: ............................................120





History

Date Version Content

2013/03/27 1.0.0 Document first released.

2013/05/02 1.0.1 1. Add Appandex A: About BEMS

2. Modify 4.6.2 Data Follower Widget, add an example to get global

parameter: “BEMSBuildingInfo”

3. Modify 5.2 APIs in parameterUtil

2013/05/22 1.0.2 1. Update Campus Node ID definition in Page 59

2013/06/26 1.0.3 1. Modify 4.6.1.8, Modify parameter name of BEMS Building Tree

2. Modify A.1, Modify “BEMSBuildingInfo” to “BEMSNodeId”

3. Add A.2, Specify the value of “BEMSNodeLevel”

2014/05/26 1.0.4 1. Documents refine with new interface definitions and APIs

2014/06/05 1.0.5 1. Add 4.5.4 For Generating MUI Dialog in Property page

2. Add missing APIs

3.Minor bug fix : Widget icon on Hover/IgnoredCwp/ Supported language

2015/04/28 1.0.6 1. Add dataSourceUtil APIs

2. Add dataSourceUtilRT APIs

3. Add dataSourceUtilCombo APIs

2015/12/15 1.0.6 Maintain





1 Introduction

1.1 Objective

This document will show users how to implement a widget in WebAccess Dashboard by

understanding pluggable widget interface. By implementing these widget interfaces and corresponding

JavaScript/CSS/Html files, the widget can support following functionalities:

- Widget drag and drop in Dashboard Editor.

- Widget property setting in Dashboard Editor.

- Refresh data by WebAccess WebService or user defined data source in Dashboard Viewer.

- Support Multi-language

- Support Widget interaction

- Interact with other widgets within the same dashboard.

- Interact with global tree menu. (only for BEMS3.0 solution)

1.2 Document Organization

This document is organized into the following chapters:

Chapter 1, Introduction.

Chapter 2, References.

Chapter 3, Abbreviations.

Chapter 4, Widget Components

Chapter 5, Dashboard APIs





2 References

[1] The jQuery Foundation, “jQuery API”, http://api.jquery.com/

[2] The jQuery Foundation, “jQuery API Documentation”, http://api.jqueryui.com/

[3] “jqPlot Charts and Graphs for jQuery”, http://www.jqplot.com/

[4] “jQuery client side language translation plugin”, https://github.com/coolbloke1324/jquery-lang-js

[5] “DevExtreme Documentation”, http://js.devexpress.com/Documentation

http://api.jquery.com/

http://api.jqueryui.com/

http://www.jqplot.com/

https://github.com/coolbloke1324/jquery-lang-js

http://js.devexpress.com/Documentation





3 Abbreviations

Keys Details

WA WebAccess





4 Widget Components

4.1 Overview

The pluggable widget interface aims to separate the widget implementation from WebAccess

Dashboard main program. 3rd

party widget developer can therefor develop there own widgets

individually. The directory structure of pluggable widget is shown in Figure 4.1.

Figure 4.1: Directory Structure of pluggable widgets

All user defined widgets must been put under widget/plugin/ folder. The naming rule of the

sub-folder is as follow:

/widget/plugin/{vertical solution Name}/{widget category Name}/{widget Name}/

For example: /widget/plugin/example/line/line_1/ means that I create a line_1 widget under line

category. And line category belongs to example vertical solution.





Basically, a widget is composed by multiple .js, .xml and .html files. All these required files must

been put under /{widget Name}/ folder. In above example, the files are put under line_1 folder. The

definitions of these files are as follow:

- Widget interface implementation (.js)

Description Each widget must implement widget interfaces defined by WebAccess

Dashboard main program. We will introduce the details of interface

implementation in section 4.2.

File Naming Rule {WidgetName}.interfaceObj.js

Example line_1.interfaceObj.js

- Widget Property Page (.html)

Description Every widget has its own properties that can be modified and applied.

Widget developer must follow the rules of property page structure to

create the property page for every type of widget. The details will be

shown in section 4.3.

File Naming Rule {WidgetName}.property.html

Example line_1.property.html

- Widget Preview Image (icon)

Description The preview image (icon) of this widget. The format will be :

(128*128 pixel, jpeg, jpg, bmp, or png file)

File Naming Rule {WidgetName}.png or jpeg or .jpg or .bmp

{WidgetName}HOV.png or jpeg or .jpg or .bmp

Example line_1.png / line_1HOV.png





- Widget Metadata (.xml)

Description The widget Metadata defines the widget related files’ information,

including file paths and file names. It will be in the form of XML. The

details will be shown in section 4.4.

File Naming Rule {WidgetName}.widgetInfo.xml

Example line_1.widgetInfo.xml

- Additional JavaScript Libraries that are used by this widget

Description For widget development, you may use some other JavaScript libraries or

define your own functions into several JavaScript files. Please put all of

these files into “/{widget Name}/util/” folder. In the above example,

line_1 widget uses mappingRule.js & objUtil.js files and puts these files

into “/line_1/util/” folder.

Finally, remember to specify these files’ path information into Widget

Metadata. Reference to section 4.4 for the details about Widget Metadata.

File Naming Rule Free format.

Example

- Language Pack (.js)

Description For supporting Multi-language display, each widget needs to define the

language Packs for every language supported by WebAccess Dashboard.

You need to put these files under “/{widget Name}/Language/” folder.

The details will be shown in section 4.5.

Current Supported Language:

- en (English)

- zh_tw (Traditional Chinese)

- zh_cn (Simplified Chinese)

File Naming Rule {WidgetName}.en.js,{WidgetName}.zh_tw.js, {WidgetName}.zh_cn.js

Example line_1.en.js, line_1.zh_tw.js, line_1.zh_cn.js





Note: In development stage, each kind of language translation will be put all

together into a language pack file per vertical solution. For example, in

example vertical solution, we have defined example.en.js,

example.zh_tw.js, example.zh_cn.js, example.defaultLang.js files

under the path: /widget/plugin/example/Language/. Please put all

widget’s English translation that belongs to example vertical solution

into example.en.js. (Likewise, all widget’s Traditional Chinese

translation => example.zh_tw.js and so on)

(Accordingly, BEMS vertical solution

/widget/plugin/BEMS/Language/BEMS.en.js,

/widget/plugin/BEMS/Language/BEMS.zh_tw.js)

…





4.2 Widget Interface

4.2.1 Basis of Widget Interface

WebAccess Dashboard treats every pluggable Widget as a JavaScript Object. While WebAccess

Dashboard do some operation and need to access a Widget, it will get the widget object and execute

some functions defined and implemented inside this widget object. These functions will have common

function names defined by WebAccess Dashboard. We call that “Widget Interface”. All you need to do

is to follow the rule to create a Widget Object and implement these interfaces under the widget object.

Figure 4.2 Widget interface implementation file. (line_1.interfaceObj.js)





Figure 4.2 shows an empty template of a Widget Interface Implementation file. In this example, we

try to create a line_1 widget. This file can be divided into two parts:

- Part 1 (surround by blue rectangle)

The first part aims to check if the widget object is existed or not. For creating a line_1

widget, the widget object will be “widget.plugin.example.line.line_1”. Under this line_1

widget object, you need to futher create a child object “interfaceObj”. WebAccess Dashboard

will access all the widget interfaces under “interfaceObj”.

The example uses a WebAccess Dashboard API to create chains of objects in a given string:

commonUtil.createObjFromString(global, "widget.plugin.example.line.line_1.interfaceObj", {});

Therefore, the object “widget.plugin.example.line.line_1.interfaceObj” will than be created.

Notice that “widget.plugin.example.line.line_1” is also a namespace of line_1 widget.

You need to specify it into Widget Metadata (in xml node “WidObjRef”). We will discuss

about it in section 4.4

- Part 2 (surround by red rectangle)

You can see nine red rectangles in Figure 4.2. These are the widget interfaces that you need to

implement for your widget. These interfaces will be called during the following Dashboard

actions:

Add Widget to Dashboard

Interface to be implemented:

getInitStructure() //get default widget object structure

drawWidChart() //draw widget by widget object structure

Open Dashboard


openSavedWidget() //return saved widget object structure for opening a dashboard

Save Dashboard


getWidgetStructure() //return widget object structure for saving into a dashboard





Apply Widget Properties to Cache


validatePropertyValues() //validate property values

applyPropertyValues() //set property values to widget object structure

Select Widget and display its properties


showPropertyItems() //construct html structure of this widget

loadPropertyValues() // show properties value of this widget

Refresh Value


refreshWidValue() // get value from data source and redraw widget by value

In addition, there are two optional interfaces for garbage collection. Widget can implement it if

it has used uploading image or mui function.

Resource Garbage collection

getUploadImgNspaces() //for widget that has used uploading image function

getTextMuiNspaces() //for widget that has used MUI function

By implementing these interfaces, widget will be able to draw chart/grid/graph… in the widget area;

display widget properties; modify and apply widget properties; refresh data in runtime…etc. In section

4.2.2, we will introduce each widget interface in detail.





4.2.2 Details of Widget Interfaces

getInitStructure()

Description

- Prepare an initial object structure for your widget. The structure may include initial values

of widget attributes and widget data. Please wrap these informations into a JavaScript object

and return for futher usage.

Syntax

getInitStructure(lid, widProperty, params)

Parameters

lid

- The id of the most outer div of this widget

widProperty

- Common widget properties, you can edit these properties in this interface for changing their

initial values. (Please refer to Section 4.3.2 for more details)

params

- Reserve for further use in the future. Can be ignored currently.

Returns

structObj

- A JavaScript object with initial structure of this widget

Example

Figure 4.3.1 getInitStructure() interface of line_2 widget (Part 1)





Figure 4.3.1 shows an example of getInitStructure() interface implemented by line_2 widget. Since

we use dxChart library to create a line chart widget, it needs initial line data and initial attribute

values of the line chart for futher chart drawing. Therefore, we construct an initial structure with

key/value pairs, such as:

- “drawStruct” : initial HTML structure in PC/Tablet Mode or Mobile Mode

- “chartOption” : structures of initial attribute values of line chart

- “seriesInfo” : structures of initial data value

- …

Next, we change the initial values of line_2’s common widget properties (shown in Figure 4.3.2,

line 51~70). Finally we return the constructed initial structure.

Figure 4.3.2 getInitStructure() interface of line_2 widget (Part 2)





drawWidChart()

Description

- In this interface, you need to call the drawing method of your charting libaray to draw a

chart/grid or write some text…etc. in the widget area. We give you a “widLid” input to specify

the id of div for widget to manipulate. Inside this div area, you can create your own widget.

- You may need the input “structObj” to get the object structure of this widget for drawing.

Syntax

drawWidChart( lid, dashName, widLid, widProperty, widObj,

needSel, structObj, refreshCBObj, params)

Parameters

lid


dashName

- Dashboard Name. This widget resides in this dashboard.

widLid

- The id of div for widget to manipulate. You need to draw chart or edit html contents inside this

widLid div.

widProperty(can be ignore in most of widgets)

- Common widget properties. (Please refer to Section 4.3.2 for more details).

widObj (can be ignore in most of widgets)

- Store many attribute values from widgetInfo.xml, plus the ratio of outer div size.

needSel (can be ignore in most of widgets)

- Specify if this widget need to be selected or not. Only be used when the widget uses callback

method

structObj

- Object structure of this widget.

refreshCBObj (can be ignore in most of widgets)

- Related variables for callback method.

params (can be ignore in most of widgets)






Returns

structObj

- A JavaScript object with structure of this widget

- Different with the output of getInitStructure() interface: you can add some attributes which was

created after drawing. Therefore, next time Dashboard call this interface, it can bring new

“structObj” as the input. You can use this strategy to re-plot data rather than re-draw the widget.

Example

Figure 4.4 drawWidChart() interface of line_2 widget

Figure 4.4 shows an example of drawWidChart() interface implemented by line_2 widget. It can be





divided into four steps:

1. Adjust HTML structure in “widLid” div. We use the global variable “mobileMode” to detect

the viewer is in which mode. The user interface of PC/tablet and phone is different. So adjust by

this parameter.

2. Read saved attributes from “structObj”

3. we use “widLid” and the attrubure values from step1 as the input for the drawing APIs.

4. After drawing, store and return the “structObj” with new attribute values.





openSavedWidget()

Description

- This interface will be called while the dashboard, which this widget resides, is opened by end

user. We define this interface for giving you an opportunity to modify the “structObj” object. If

you don’t need to do anything, just return it.

Syntax

openSavedWidget(lid, structObj, params)

Parameters

lid


structObj


- Note: This object is come from saved dashboard file. The data in this object are determined by

what you saved in getWidgetStructure() interface.

params


Returns

structObj

- A JavaScript object: Object structure of this widget

Example





Figure 4.5 openSavedWidget() interface of line_2 widget

Figure 4.5 shows an example of openSavedWidget() interface implemented by line_2 widget. We

add some attribures in “structObj”. If this interface is called in view mode, we give values to make

the chart initially. If in edit mode, we create random values as sample values.





getWidgetStructure()

Description

- This interface will be called while the end user saves the dashboard which this widget resides.

We define this interface for giving you an opportunity to modify the “structObj” object. If you

don’t need to do anything, just return it.

Syntax

getWidgetStructure(lid, structObj, params)

Parameters

lid


structObj


params


Returns

structObj

- A JavaScript object: Object structure of this widget

- Note: since this return object will be saved in Dashboard file, you may remove some

unnecessary information in “structObj” for keeping the saved file size small.

Example

Figure 4.6 getWidgetStructure() interface of line_2 widget

Figure 4.6 shows an example of getWidgetStructure() interface implemented by line_2 widget.

Since “structObj.seriesInfo.data” and “structObj.seriesInfo.series” are charting data which are

created by dxChart after drawing. We don’t need to store them in dashboard file. Therefore we set

them to “empty” and return modified “structObj”.





validatePropertyValues()

Description

- This interface will be called during end user press “apply” button on the property pane. You can

implement validation functions to validate the input values in the property pane.

- If an error occurs, you need to create an error object and throw it out. Please use the API:

validateUtil.composeExp(error_key, error_param[]) to create the error object.

(“error_key” is defined in each language pack files, “error_param” will be used only when you

need to pass parameters into error_key’s translation. The detail strategy of Multi-language will

be introduced in section 4.5)

- You can also throw an array of error objects for multiple error message display.

Syntax

validatePropertyValues(lid, params)

Parameters

lid


params


Returns

- None

Example

Figure 4.7 validatePropertyValues() interface of line_2 widget





Figure 4.7 shows an example of validatePropertyValues() interface implemented by line_2 widget.

We use isNaN function to check if the value of #dxRecordCount and #tooltipSize are not number.

If not, use validateUtil.composeExp() API to create a error object and throw it out.





applyPropertyValues()

Description

- After calling validatePropertyValues() interface, WebAccess Dashboard than call this interface

for this widget to store the property values into widget object structure. You need to implement

this interface to select and get every property values in your property page; store these values

into structObj; finally return structObj.

- You can use a Dashboard API: dashboardProperty.htmlCacheMapping() for storing property

values to structObj. We will introduce this API in section 5.

Syntax

applyPropertyValues(lid, structObj, params)

Parameters

lid


structObj


params


Returns

structObj

- Object structure of this widget. (with new property values)

Example

Figure 4.8 applyPropertyValues() interface of line_2 widget

Figure 4.8 shows an example of applyPropertyValues() interface implemented by line_2 widget. In

this interface, we use dashboardProperty.htmlCacheMapping() API to store every property values

into structObj.chartOption object. For other special objects and values, such as date / point group





property /…, that cannot be handled by dashboardProperty.htmlCacheMapping() API, we use

applyProperty function to update. Finally, we return the structObj with new property values.





showPropertyItems()

Description

- When user uses Dashboard Editor and clicks a widget in Dashboard Area, WebAccess

Dashboard will call this interface to construct HTML structure in property pane.

- “propertyPagePaths” contains the paths defined in Widget Metadata. You can load the

contants of these paths by Dashboard API: “commonUtil.loadFileToPage()” and than append

these HTML contants under the DIV with “daProperties” ID.

- You can also bind some HTML event, such as blur, mouseOver…etc, on your input components

in this interface.

- If any of third party components you have used needs to be initialized, you need to implement it

under this interface.

- Use “gTagList” globel parameter to get tag list from SignalR. Or you can use

“uiUtil.addTagListBtn” to create a select box with filtered tag list.

Syntax

showPropertyItems(lid, propertyPagePaths, structObj, params)

Parameters

lid


propertyPagePaths

- Property page paths which are defined in Widget Metadata (widgetInfo.xml)

structObj


params


Returns

- None





Example

Figure 4.9 showPropertyItems() interface of line_2 widget

Figure 4.9 shows an example of showPropertyItems() interface implemented by line_2 widget. In

this example, we do the following things:

- Load every property pages by “commonUtil.loadFileToPage()” API, and then use jQuery

syntax to append these HTML contants under “#daProperties” DIV.

- Init some third party components in showProperty() function.

- Bind event on “#a_refreshDList” for getting commander widget list in same dashboard.





loadPropertyValues()

Description

- After calling showPropertyItems() interface to construct HTML structure in property pane,

WebAccess Dashboard then call this interface to load every property values of this widget. You

need to retrieve current property values stored in structObj; assign these values into HTML

structure of property pane.

- You can use a Dashboard API: dashboardProperty.htmlCacheMapping() for reading property

values from structObj and assign these values into HTML structure. We will introduce this API

in section 5.

Syntax

loadPropertyValues(lid, structObj, params)

Parameters

lid


structObj


params


Returns

- None

Example

Figure 4.10 loadPropertyValues() interface of line_2 widget

Figure 4.10 shows an example of loadPropertyValues() interface implemented by line_2 widget.

Generally, we use jQuery syntax to select a HTML component and assign a value to it. However,

we can also use Dashboard API : dashboardProperty.htmlCacheMapping() for loading values

from structObj.chartOption to HTML components. For those HTML components which cannot be





handled by dashboardProperty.htmlCacheMapping(), we write a loadProperty() function to

handle it.





refreshWidValue()

Description

- This interface let you define how to refresh your widget values in Dashboard Viewer. You can:

- Update value from Parameter Table (call Parameter Table API, will be discussed in

section 4.6)

- Update WebAccess Tag Value by Dashboard API:

“dataSourceUtilCombo.getTagValuesAndRefresh ()” (use SignalR or AJAX(in iOS

platform) to query WebAccess WebService. You need to give it a call-back function for

processing the result of tag values. Please refer to section 5 for details.)

- In your own way (by web service of your own…etc.)

- Do nothing. If you don’t need to modify anything of this widget in runtime.

- Note : If you use datasourceUtilCombo APIs in params.isFopen, you need to detect

params["tagInfos"] for the value from signalR.

Syntax

refreshWidValue(dashName, lid, structObj, params)

Parameters

dashName

- Dashboard Name. This widget resides in this dashboard.

lid


structObj


params

- We have defined some parameters listed as below currently:

params.commanderId: if this API is called by commander, this variable will contain

commander widget’s id.

params.isFopen: if this API is called by opening a dashboard

params.tagInfos: An array of TagInfo Objects. If this API is called by server (signalr) pushing

message, this object will contain the newest tag information.





TagInfo example (Analog): {“tagName”:”AO_0”, “tagType”:”1”,”value”:760}

TagInfo example (Digital): {“tagName”:”DO_0”, “tagType”:”2”,”value”:1}

TagInfo example (Analog): {“tagName”:”Text_0”, “tagType”:”3”,”value”:”This is a Text”}

params.tagInfos example: [{“tagName”:”AO_0”, “tagType”:”1”,”value”:760},

{“tagName”:”Text_0”, “tagType”:”3”,”value”:”This is a Text”}]

Returns

- None

Example

Figure 4.11 refreshWidValue() interface of line_2 widget

Figure 4.11 shows an example of refreshWidValue() interface implemented by line_2 widget. As

you can see, we use Dashboard API: “dataSourceUtilCombo.getTagValuesAndRefresh ()” to get

WebAccess Tag values. It needs a call-back function input (cbObj). We define a





“drawAndRefresh()” function in objUtil and set it as the call-back function. When WebAccess

Dashboard finishing get WebAccess Tag values, it will call drawAndRefresh () for updating the

values of line_2 widget in runtime. If you get tag value by signalr, server will push data to your

refreshWidValue by passing parameter params.tagInfos.





getUploadImgNspaces()

Description

- This interface is optional. It is used for image garbage collection when your widget has used

uploading-image function. We define this interface for letting you tell the main program the

namespace under the “structObj” object you store the image path. If your widget does not have

uploading-image function, you need not to implement this interface.

Syntax

getUploadImgNspaces()

Parameters

- none

Returns

An array string containing namespaces under structObj

Example

Figure 4.12 getUploadImgNspaces () interface of singleLineText widget

Figure 4.12 shows an example of getUploadImgNspaces () interface implemented by

singleLineText widget. This widget use uploading-image function in two places.





getTextMuiNspaces()

Description

- This interface is optional. It is used for MUI string garbage collection when your widget has

used MUI string function. We define this interface for letting you tell the main program the

namespace under the “structObj” object you store the MUI key string. If your widget does not

have MUI string function, you need not to implement this interface.

Syntax

getTextMuiNspaces()

Parameters

- none.

Returns

An array string containing namespaces under structObj

Example

Figure 4.13 getTextMuiNspaces () interface of singleLineText widget

Figure 4.13 shows an example of getTextMuiNspaces () interface implemented by singleLineText

widget. This widget used MUI string function in one place.





4.3 Widget Property Page

4.3.1 Design guideline

In Dashboard Editor, Property pane is primarily using jQuery UI Accordion to present the property

list. The user needs to use HTML to create the property pane for every type of widget. Each widget has

its unique structure and properties. Figure 4.12 shows a Property Pane of line_2 widget:

Figure 4.12 Property Pane of line_2 widget

Figure 4.13 shows a portion of the HTML code for the HTML property page. It represents the Title

property.





Figure 4.13 - An example of property.html

There are few components you must have when you wish to edit a HTML property page:

a. <h3> tag:

- A <h3> tag defines one of the headers in the property list. More <h3> can be added if

necessary.

b. <div><table> tags:

- A <table> inside of a <div> represents the content of the <h3> tag. When the <h3> is clicked,

the drop down menu described by the <table> will be displayed.

- The <table> constrain the format and helps to organize the contents.

- The <div> is the place holder for the <table>.

c. Multi-language support

- You can see manu HTML elements with “jql” attribute. When Dashboard main program see this

attribute, it will translate the text within this element (as a key) to the selected language by the

language packs defined for this widget. For example:

<a href="#" jql>t_9001_Title</a></h3>

If the selected language is English, we will translate “t_9001_title” to “Title”. The details of

Multi-language support will be shown in section 4.5





4.3.2 Common Properties of every Widget

Every widget has a common properties page builded in by WebAccess Dashboard. It will

automatically been loaded by WebAccess Dashboard before loading Widget’s property page. In Figure

4.12, you can see that the common properties are shown in “Preference”, “Widget Setting” and “Title”

list. We will wrap these attributes into an object “widProperty” and pass this object as an input for

widget interfaces.

The “Preference” properties’ desctiption are as follow:

- Widget Preference Name, (widProperty.widPref)

The widget preference name used by this widget

The “Widget Setting” properties’ desctiption are as follow:

- Widget Id, (widProperty.widgetId)

A unique ID of this widget (under its dashboard)

Note: You MUST NOT edit this value.

- Widget Name, (widProperty.widgetName)

Name of this widget, the default name will be WidTitle defined in Widget Metadata; plus a “_”;

plus a sequence number. Example: line_1_1

- Frame Color, (widProperty.frameColour)

Outer frame’s color of this widget

- Background Color, (widProperty.backgroundColour)

Background Color of this widget

- Background Image, (widProperty.bkImage)

Background Image of this widget

widProperty.bkImage.bkImageExtend:

“contain” : Original proportions

“100% 100%” : Extend Image to fill widget area

widProperty.bkImage.bkImageInner:

“N” : background image cover Title div

“Y” : background image not cover Title div

widProperty.bkImage.bkImageUrl: image’s url

- Refresh Time interval, (widProperty.refreshTime)

Refresh Time interval of this widget. It contains following sub-elements:





widProperty.refreshTime.timeInterval: interval value.

widProperty.refreshTime.timeIntervalType: interval type. Value: “sec” or “min” or “hr”

widProperty.refreshTime.timeInterval_m: interval value (in mobile phone mode).

widProperty.refreshTime.timeIntervalType_m: interval type (in mobile phone mode).

Value: “sec” or “min” or “hr”

- Height in mobile phone mode, (widProperty.mobile)

Height of this widget in mobile phone mode (by portrait and landscape)

widProperty.mobile.heightValue: Portrait height

widProperty.mobile.heightValueL: Landscape height

The “Title” properties’ desctiption are as follow:

- Enable title or not, (widProperty.titleEnable)

Is title region enable (“Y”) or not (“N”)

- Title Text, (widProperty.titleText)

The MUI key for title content

- Title Font Family, (widProperty.titleFontfamily)

Title font family setting

- Title Font size, (widProperty.titleSize and widProperty.titleUnit)

Title font size setting

- Title Font color, (widProperty.titleColour)

Title font color setting

- Title Background color, (widProperty.titleBgColour)

Title background color of this widget

- Title Background Image (widProperty.titleBkImage)

Title background image of this widget

widProperty.titleBkImage.bkImageExtend:

“contain” : Original proportions

“100% 100%” : Extend Image to fill widget area

widProperty.titleBkImage.bkImageUrl: image’s url

The HTML structure of Common Property Page is defined in widget\sharedPage\

widget_prop_setting.html. All the above properties will be shown in property pane in default. If you





want to hide some “Optional” properties defined in above, you can get its HTML element ID in

widget_prop_setting.html and configure “IgnoredCwp” in the Widget Metadata of your widget. Please

reference section 4.4.2 for detail setting.





4.4 Widget Metadata

Widget Metadata defines the entire important informations of a widget, including Widget ID,

Widget Object Namespace, Library path…etc. There are two main sections in the Metadata:

- Library information

- Widget information

Widget Metadata will be in the form of XML. The basic xml format is as follow:

<WidgetInfo>

<LibDetails>

<LibDetail>

……………………….. (Library information)

</LibDetail>

</LibDetails>

<WidgetDetails>

<WidgetDetail>

……………………….. (Widget information)

</WidgetDetail>

</WidgetDetails>

</WidgetInfo>

General Rules:

- <LibDetails> can contain multiple <LibDetail> elements to specify multiple kinds of library set.

Also for <WidgetDetails>, it can contain multiple <WidgetDetail> elements to specify multiple

widgets.

- Basically, we need you to prepare a Widget Metadata file (widgetInfo.xml) per widget. In that

case, it will only one <WidgetDetail> element within <WidgetDetails>.

- In development stage, we encourage you to combine these Widget Metadata files into one file

per category. For example, in BEMS category, all widget’s metadata will be combined into

“widget\plugin\BEMS\BEMS.widgetInfo.xml”. In that case, it will has multiple <LibDetail>

and <WidgetDetail> elements in BEMS.widgetInfo.xml.





4.4.1 Library Information

Syntax

Figure 4.14: An example of Library Information in widgetInfo.xml

Parameters

LibRefId:

- Define the ID of this library reference set. Note that the LibRefId must be unique.

- Naming Rule: L_{Developer ID}_{library Type}_{sequence Number}

- {Developer ID}: Three Characters, [A-Za-z0-9]

- {library Type}: Free format

- {sequence Number}: [0-9]

- Example:

L_ACL_JQ_1

LibPaths:

- The paths of chart library, including .js and .css. You could define multiple libraries here

(separated by comma)

- Example:

/widget/sharedJs/jqplot/jquery.jqplot.js,

/widget/sharedJs/jqplot/plugins/jqplot.cursor.js,

/widget/sharedCss/jqplot/jquery.jqplot.css





Description

- If you have a set of libraries (.js or .css) that will be used by multiple widgets, you can specify

these libraries in the section of Library Information. By given this set of libraries a “LibRefId”,

widget can specify this ID into the section of Widget Information to claim that it uses these

libraries.

- Generally, if you develop multiple widgets, you will have multiple widgetInfo.xml files. You

can specify the section of Library Information in one of these widgetInfo.xml files. Others can

just simply specify the “LibRefId” in the section of Widget Information of their

widgetInfo.xml files.





4.4.2 Widget Information

Syntax

Figure 4.15: An example of Widget Information in widgetInfo.xml

Parameters

WidTitle:

- Title of the Widget, It will be used as a default widget name in Widget Property Pane.

- Naming Rule: Free Format

WidTypeId:

- A unique ID of the Widget. Note that WidTypeId must be global unique amound all widgets.

- Naming Rule: W_{Developer ID}_{Widget Type}_{sequence Number}

- {Developer ID}: Three Characters, [A-Za-z0-9]

- {Widget Type}: Free format

- {sequence Number}: [0-9]

- Example:

W_ACL_LINE_EXAMPLE_1





WidCategory:

- Define the category of this widget. The detail description of each kind of widget categories is in

section 4.6.1.

- Values. Must be one of the following:

DateTime:

This widget is a DateTime widget. It provides “sDate”, “eDate”…etc. variables

Button:

A button widget contains multiple buttons. It provides “buttonValue” variable.

Refresh:

A widget contains a refresh button. It triggers the follower widget to redraw.

Text:

This widget is a Text widget. It provides “textValue” variable.

SingleTree:

A widget contains a tree list with single selection functionality on the tree node. It provides

“treeValue” variable

Others:

All other kinds of widgets (beside above categories) specify this value.

- We will discuss about each kind of widget category in section 4.6.

IgnoredCwp:

- Specify the Common Widget Property you want to ignore in your Widget Property Page. You

could define multiple properties here (separated by comma)

- Value: (ID of HTML elements in widget\sharedPage\widget_prop_setting.html)

timeInterval:

Ignore interval value.

timeIntervalType:

Ignore interval type.

rTime:

Ignore realtime option. If the widget is not use WebAccess signalR, please add this value.

WidObjRef:

- The name of this widget object in JavaScript. You can treat it as a namespace of this widget.

Remember to construct the widget object (by the method described in section 4.2.1 Part 1) with





the same name specified here.

- Example:

For line_1 widget in “example” vertical solution, the value of WidObjRef will be:

“widget.plugin.example.line.line_1”.

UsedSharedLibRef:

- Specify the LibRefId here to claim the library sets used by this widget. You could define

multiple LibRefId here (separated by comma)

- Example:

L_ACL_JQ_1,L_ACL_JQPLOTWID_1

The above example means that this widget use “L_ACL_JQ_1” and “L_ACL_JQPLOTWID_1”

library sets.

PrivateLibs:

- Specify the paths of used libraries which are not defined in the library sets of

UsedSharedLibRef. You could define multiple libraries here (separated by comma)

- You can use %widgetFolder% to represent the widget folder path defined in WidgetFolder

element.

- Example:

%widgetFolder%/util/mappingRule.js,

%widgetFolder%/util/objUtil.js,

%widgetFolder%/line_1.interfaceObj.js

IsDrawCb:

- Specify if this widget need to use call-back function in drawWidChart() interface.

- Value: “Y” or “N”. (In most cases, you don’t need to use call-back. Just specify “N” here.)

WidgetFolder:

- Specify the widget folder path which your widget resides.

- Note that the folder path starts from /widget/ folder

- Example:

/widget/plugin/example/line/line_1

PropertyPagePaths:

- Specify the Widget Property Page path of this widget

- Example:





%widgetFolder%/line_1.property.html

ImagePath:

- Specify the Preview Image path of this widget

- Example:

%widgetFolder%/line_1.jpg

ImagePathHov:

- Specify the Hovered Preview Image path of this widget. (This image will be displayed while

mouse hovers on.)

- Example:

%widgetFolder%/line_1HOV.jpg

WidMinSizeW:

- Specify the Widget minimum width in pixels

- Example:

300

WidMinSizeH:

- Specify the Widget minimum height in pixels

- Example:

300

TitleLangs:

- Specify the MUI value for WidTitle(listed above)

- Example:

<en>[Cmd]Numeric Range</en>

<zh_cn>[指令]数值范围</zh_cn>

<zh_tw>[指令]數值範圍</zh_tw>

IntervalWithPush:

- Specify if this is a time-based widget

- Example:

“Y” or “N”(“N” is also equal to ignoring this attribute)





4.5 Multi-language

WebAccess Dashboard supports multi-language display in static HTML page or dynamic Dialog

page / alert message. For supporting multi-language in your widget, you need to follow the rules to

create the widget property page and the dynamic contents generated in your JavaScript functions.

WebAccess Dashboard uses “jquery-lang-js” library [4] as the basis of Multi-language solution and

derive some APIs from it. The following sections will introduce the detail strategies of Multi-language

display.

4.5.1 Prepare the Language Pack

For each suppored language, you need to define a Language pack for it. The language packs are

defined in JavaScript files. The content format is as follow:

widget.plugin.example.dateTime.date_1.lang.en = {

't_9501_Date': 'Date',

't_9502_Sdate': 'Start Date',

't_9503_EDate': 'End Date'

}

Table 4.1 content format of a language pack

- The language pack starts with the widget namespace (widget.plugin.example.dateTime.date_1)

defined in the “WidObjRef” element of widgetInfo.xml.

- Following by a keyword “lang” to specify the content is a language pack.

- Following by a type name of the language. The supported languages and the type name

mapping is as follow:

Language Type name Note

Default Language defaultLang

English en

Traditional Chinese zh_tw

Simplified Chinese zh_cn

- The content of the language pack is constructed by multiple langKey-langValue pairs

(separated by comma).





- langKey: means the target to be translated

- langValue: means the translation result of this type of language

In runtime, WebAccess Dashboard will translate these langKeys into correlative langValues.

- The format of langKey:

Normal Message: t_{Sequence Number}_{Key ID}

Error Message: e_{Sequence Number}_{Key ID}

- {Sequence Number}: at least 4 digits, [0-9]. We reserve different range of sequence

number for different vertical solution:

Vertical Range of Sequence Number

BEMS 2001~3000

WebAccess Dashboard kernal 0000~1000

Build-in Widgets 1001~2000

Example 9001~10000

- {key ID}: Free format [A-Za-z0-9_]

- The format of langValue:

Basically, the format of langValue is free format. You just need to write down the

corresponding language characters. However, WebAccess Dashboard supports translate

language with parameters. If you have some parameter values need to be carried into the

langValue, please add “{paramNum}” into the langValue. paramNum is a sequence number

and start from 0.

For example, you may have a langValue: “please add {0} into {1}”. {0} and {1} are the

parameters. The parameter values will be assigned by the API for dynamic content. Please refer

to section 4.5.3 for the details about this API.

4.5.2 For static HTML pages

In HTML content (property.html or any other HTML pages used by your widget) you can simply

add a “jql” attribute to an element for denoting this element as being available for translation. Such as:

- span

<span jql>t_9502_Sdate</span>





- select / option

<select id="jqTitleAlign">

<option value='center' jql>t_9007_Center</option>

<option value='right' jql>t_9008_Right</option>

<option value='left' jql>t_9009_Left</option>

</select>

- Button

<button jql>t_9800_testButton</button>

- Placeholder text

<input type="text" id="jqTitleSize" size="7" placeholder=”t_9801_testPH” jql/>

When WebAccess Dashboard parses the “jql” attribute in the element, it will replace the langKey

(t_xxxx_xxx) by the langValue that you have defined in Language Pack.

4.5.3 For dynamic content

If your widget has some dynamic contents (such alert message) needed to be translated, WebAccess

Dashboard provide two APIs for dynamic content translation. You can use these APIs in your JavaScript

codes.

- dashboardMui.muiFunctions.convert(langKey, lang);

Parameters

langKey

- The langKey to be translated.

lang (optional)

- Language Type Name. To specify the language you want to translate to. Leave blank will

use current language for translation.





Description

- This API will convert the input “langKey” into the langValue defined in your language

pack.

Returns

langValue

- Translated value correlated with langKey.

- dashboardMui.muiFunctions.convertWithParam(langKey, param, lang);

Parameters

langKey

- The langKey to be translated.

param

- An array of parameter values.

lang (optional)

- Language Type Name. To specify the language you want to translate to. Leave blank will

use current language for translation.

Description

- When you define some parameters in a langValue, you need to use this API to carry

“param” in. For example, if you have a langValue: “please add {0} into {1}”, you need

to assign the values in param[0] and param[1] and bring the array “param” as the input

into this API. This API will replace “{0}” and “{1}” by param[0] and param[1].

Returns

langValue

- Translated value correlated with input key.





The following example shows that how to generate an alert message with dynamic content

translation in you JavaScript code:

alert(dashboardMui.muiFunctions.convert(“t_0029_TimeInv”));

var tmpObj = [];

tmpObj[0] = “some text”

tmpObj[1] = “another text”

alert(dashboardMui.muiFunctions.convertWithParam(“t_9982_TestParam”, tmpObj));

4.5.4 For Generating MUI Dialog in Property page

WebAccess Dashboard provides MUI Dialog for your widget to setup properties’ MUI content in

the property page. The implementation steps are as follow:

4.5.4.1 Add Text input in property.html

Add the following code in your widget’s property.html.

<tr>

<td>

<label for="exTitleText">

<span jql>t_2018_TitleText</span>

</label>

</td>

<td>

<input type="text" id="exTitleText" jql size="20" placeholder="" disabled/>

<button id='openMuiDialog'><i class="icon-pencil"></i></button>

</td>

</tr>

The above code will add a text input for displaying MUI string; a <button> for user to click and

open a MUI Dialog. The display is shown as follow:





4.5.4.2 Setup interface.js

You need to add some code in the widget interfaces for accomplishing MUI dialog setup. We list as

follow:

- getInitStructure

In this interface, you need to get a MUI unique key for text translation. Please refer to the

following code:

var textKey = dashboardMui.genLanguageRecKey();

var keyObj = { "textKey": textKey };

return { "canvasObjData": canvasObjData, "canvasObjOptions": canvasObjOptions,

"energyItemWidId": energyItemWidId,

"buildingID": buildingID, "calendar": calendar, "energyItemCode": energyItemCode,

"keyObj": keyObj };

We use dashboardMui.genLanguageRecKey() API to generate a key, and use an Object

(keyObj) to save key into structObj. If you have multiple text needs to be translated, only need

to call dashboardMui.genLanguageRecKey () API several times, and save multiple key into

keyObj.

The format of keyObj could be: {“key1” : textKey, “key2” : textKey2 …….}

Finally, remember to return structObj with keyObj.





- showPropertyItems

In this interface, you need to bind a click event of the <button> defined in 4.5.4.1 property.html.

var cbObjForMuiDlg = {};

cbObjForMuiDlg[waDashboardConstants.CB_ATTR_NAME_FUNC] = function () {

var textVal = dashboardMui.getTranslatedTextInput(structObj.keyObj.textKey,

localStorage.getItem('langJs_currentLang'));

$("#exTitleText").attr('placeholder', textVal);

};

$("#openMuiDialog").bind("click", function () {

dashboardMui.openInputMuiDialog(structObj.keyObj.textKey, cbObjForMuiDlg);

});

In the above code, we first define a callback function. It will be executed after user specifying

the MUI text in the MUI dialog. In the callback function, we obtain the translated text by

dashboardMui.getTranslatedTextInput() API, and display the translated text on 'placeholder'

property of <input> which is defined in 4.5.4.1 property.html.

Then we define the click event function of <button> (in this example, button id is

openMuiDialog). By calling dashboardMui.openInputMuiDialog() API, it will generate a

MUI dialog for user to enter MUI text. Dialog is displayed as follow:

- loadPropertyValues

Load the translated text value into property page.

var textVal = dashboardMui.getDisplayedText(structObj.keyObj.textKey,


$("#exTitleText").attr('placeholder', textVal);





dashboardMui.muiFunctions.runByDivId(localStorage.getItem('langJs_currentLang'), "daProperties");

- getTextMuiNspaces

For MUI string garbage collection. You need to an array of keys that are defined in the keyObj.

For example, if the structure of keyObj is

{“key1” : textKey, “key2” : textKey2 }

Then you need to retrun [“keyObj.key1”, “keyObj.key2”]

tempObj.getTextMuiNspaces = function () {

return ["keyObj.textKey"];

};

4.5.4.3 Display the translated text in Widget

Since you may define how to draw your widget of refresh widget display in drawWidChart

and refreshWidValue interfaces, you can simply call dashboardMui.getTranslatedTextInput() API

to get the translated text and decide how to display it.

Title = dashboardMui.getTranslatedTextInput(structObj.keyObj.textKey,


if (Title == "" || Title == waDashboardConstants.WARN_KEYNOTEXIST)

Title = " ";

In the above code, we use a “Title” variable to store the translated text. We further to process

the Title text while it is an empty text or a “KEY NOT EXIST” warning message (defined by

“waDashboardConstants.WARN_KEYNOTEXIST” constant string).





4.6 Widget Interaction

WebAccess Dashboard supports values exchange between widget to widget. Basic idea is that:

- Some widgets in a Dashboard act as Data Commander. They will trigger the event while data

has been changed. The data cound be a date, a value of tree node, or a value of button.

- The other widgets in the Dashboard act as Data Follower. They may follow some of the Data

Commanders for the event notification. While an event has been triggered, Data Follower can

get the new data and adjust widget presentation.

- For example, a Line chart widget (Data Follower) follows a DateTime widget (Data

Commander). It will use the Date provided by DateTime widget as a range to query database.

While an end user change the Date value, DateTime widget will trigger an event to notify Line

chart widget. Line chart widget will go to get the new Date value and redraw the line with new

Date range.

For the requirements of Data exchange, WebAccess Dashboard implements a parameter table for

saving these data and provides some APIs for Get/Set parameter table values. Furthermore, since

different kind of Data Commander Widget may provide different kind of data, we define the widget

category (WidCategory, Defined in section 4.4.2) and the variable names that each kind of Data

Commander Widget needs to provide.

In the following sections, we will discuss about the design guideline of Data Commander Widget

and Data Follower Widget.





4.6.1 Data Commander Widget

A Data Commander Widget provides zero to more variable values for Data Follower Widget to use.

The definitions of each kind of Widget Categories are as follow:

4.6.1.1 General Guideline:

- All the following kinds of widgets have a Category Value in “WidCategory” defined in Widget

Metadata.

- Each kind of Widget Category has zero to more parameters. The naming rule of a parameter

stored in WebAccess Dashboard’s Parameter Table will be: {WidgetId}.{VariableName}.

{WidgetId} can get by dashboardCommon.getWidgetCacheObj() API. And we defined the

{VariableName} for each kind of Widget Category in section 4.6.1.2 ~ section 4.6.1.8

- Data Commander Widget acts the role to set the value of parameter. So you need to call the

following APIs in your event function, which will be triggered when the parameter value

changed:

dashboardCommon.getWidgetCacheObj(dashName, lid)

- Get WidgetCacheObj of “lid” widget in “dashName” dashboard. It will return a

JavaScript Object.

- After getting WidgetCacheObj, you can access widget common properties in

WidgetCacheObj.widProperty. Then you can get the value of WidgetId.

- You can use the globe parameter “activeTabFileName” as the input of dashName.

parameterUtil.setParameterValueByWidgetId(widgetId, widgetVar, value)

- Set “widgetId” widget’s “widgetVar” variable with a new value “value”.

- widgetVar of each kind of widget categories is defined in section 4.6.1.2 ~ section

4.6.1.8

- For example, you have a DateTime widget with an input element for startDate and an

“Apply” button. You may want to bind an “onClick” event on this “Apply” button.

Therefore, you need to use this API to assign the new value of startDate into Parameter

Table.





dashboardUtil.notifyAndRefreshWids(widgetId)

- Notify the value change event to all Data Follower Widgets which follow your “widgetId”

widget in this dashboard.

- You need to call this API after finish calling the above setParameterValueByWidgetId()

API

4.6.1.2 DateTime Widget

- Value of WidCategory : “DateTime”

- Variables (Value of widgetVar)

dataType: The data type you want to get from WebAccess

0 : (last value)

1 : (maximun value)

2 : (minimum value)

3 : (average value)

timeMode: Date Time selection Mode

CT : (Specify a period of time from the current time)

SI : (Specify a Start time and a period of time)

SE : (Specify a Start time and a End time) (Reserved for future use)

sDate: Specify a Start Date; Integer value representing the number of milliseconds since

1970/January/1 00:00:00 UTC (Unix Epoch)

eDate: Specify a End Date; Integer value representing the number of milliseconds since

1970/January/1 00:00:00 UTC (Unix Epoch) (Reserved for future use)

intervalType: Interval type

S : Second

M : Minute

H : Hour

D : Day

num: Total interval, an interger value that user inputed from Date widget

interval: interval between any two records. (Computed by date widgets)

records: Record number (Computed by date widgets)

note: Not used (Reserved for future use)





- Example: User wants to monitor average tag value within past 720 hr from current time. The

date widget automatically divides 720 by 2 since 720 records are too much to display on chart.

Finally, the variable value will be as follow:

dateType = 3

timeMode=”CT”

sDate: current time (in milliseconds)

intervalType=”H”

num=720

interval=2

record=360

4.6.1.3 Button Widget

- Value of WidCategory: “Button”

- Variable (Value of widgetVar)::

buttonValue: Specify the button value; (string)

4.6.1.4 Refresh Widget

- Value of WidCategory: “Refresh”

- Variable: None

4.6.1.5 Text Widget

- Value of WidCategory: “Text”


textValue: specify the value of text; (string)

4.6.1.6 Single Select Tree Widget

- Value of WidCategory: “SingleTree”


treeValue: specify the selected tree node value; (string)





4.6.1.7 BEMS Building Tree

- Not a widget. But it will provide a global parameter for all widgets to use.

- Global Parameter Name:

BEMSBuildingInfo: specify the selected building name; (string)





4.6.2 Data Follower Widget

A Widget which follows one or more Data Commander Widgets’ parameters for redraw is a Data

Follower Widget. The basic guideline for developing a Data Follower Widget is as follow:

a. Put a selection element in Widget Property Page of Dashboard Editor

In dashboard editor, you need to let a system administrator to select a Data Commander

Widget for connecting with your widget. Therefore, you need to add a selection element

(comboBox, radio button…etc.) in your Widget Property Page.

NOTE: You MUST to add a class named “widgetCategory” in the selection element of

your widget property HTML page. For example, text_1.property.html contains following

HTML code:

<td>

<select id="dateWidList" class="widCategory">

</select>

</td>

That means we have a select element in text_1 widget’s property page. The content of this

select element will be given in the next step.

b. Add the content of the selection element in showPropertyItems() interface

You can create the HTML structure of the selection element in showPropertyItems()

interface. Please use the following API for getting a widget list of a specific widget category:

dashboardUtil.getWidgetObjList(widCategory, dashName)

- It will return an array of objects with the same “widCatgory”. An object contains

elements of widgetId and widgetName. You can use widgetName for display and

widgetId for the value of selection element.

- “dashName” can be ignored if you want the widget list in the same dashboard.

c. Get new parameter values in refreshWidValue() interface

When the correlated Data Commander Widget changes the parameter values, it will trigger

the event and then execute your refreshWidValue() interface. You can use the following API for

getting new parameter value of that Data Commander Widget.





parameterUtil.getParameterValueByWidgetId(widgetId, widgetVar)

- Get “widgetId” widget’s “widgetVar” variable value.

For getting Global Parameter’s value, please use the following API:

parameterUtil. getParameterValue(key, isGlobal, isKeyWithSymbol)

- Get the value of “key” in Parameter Table

- For example, if you want to get the value of BEMS Building Tree:

key = BEMSBuildingInfo

isGlobal = ture

isKeyWithSymbol : can be ignored, of set it to false

Syntax: parameterUtil.getParameterValue(“BEMSBuindingInfo”, true)





5 Dashboard APIs

In this section, we will introduce you WebAccess Dashboard APIs that you may use in you widget.

5.1 JavaScript Global Variables

You can use the following variables directly in your JavaScript code. (These variables will be

prepared before loading you *.js files.)

- contextUrl:

The URL prefix of this web application (current value is http://<ip>/broadweb/WADashboard)

- docRoot:

The base path of this web application (current value is /WADashboard)

- activeTabFileName:

Current dashboard name

- currentLid:

The lid of current selected widget

- isVMode:

Specify that current Dashboard is in View Mode or not. Boolean Type (true or false)

- mobileMode:

Specify that current Dashboard is in mobile phone mode or not. Boolean Type (true or false)

- gTagList:

Specify a list of Tags under one WebAccess project. Its data will be updated by server pushing

data.





5.2 APIs in parameterUtil

- parameterUtil.getParameterValueByWidgetId(widgetId, widgetVar)

Get “widgetId” widget’s “widgetVar” variable value from parameter table of current

dashboard.

- parameterUtil.getParameterValue(key, isGlobal, isKeyWithSymbol):

Get the parameter value from parameter table of current dashboard (isGlobal = false) or Global

scope (isGlobal = true). The third variable “isKeyWithSymbol” can be simply ignored or just

set it as “false”.

- parameterUtil.setParameterValueByWidgetId(widgetId, widgetVar, value)

Set “widgetId” widget’s “widgetVar” variable with a new value “value” into parameter table

of current dashboard.

- parameterUtil.setParameterValue(key, value, isGlobal, isKeyWithSymbol):

In contrast to parameterUtil.getParameterValue, this API set parameter value to parameter table

of current dashboard (isGlobal = false) or Global scope (isGlobal = true). The third variable

“isKeyWithSymbol” can be simply ignored or just set it as “false”.

- parameterUtil.getParamReplacedString(origString):

Get string whose parameter keys are replaced with parameter values (ex:

%location%.%floor%.HVAC -> Taipei.F3.HVAC).





5.3 APIs in commonUtil

- commonUtil.loadFileToPage(urlPrefix, filePath, notCache):

For the usage of loading *.js, *.css, and *.html files. The path of the file you want to load is

(urlPrefix+filePath). We usually use contextUrl (global variable) for “urlPrefix” and its

relative path for “filePath”. “notCache” is for specifying whether you load it from browser

cache.

- commonUtil.loadJsFilesToPage(contextUrl, docRoot, filePaths):

For the usage of loading *.js and *.css files. We usually use contextUrl (global variable) for

contextUrl, docRoot (global variable) for docRoot, and relative path array for filePaths.

- commonUtil.createObjFromString(obj, objString, value):

For obj as root, creating object hierarchy through objString if not existed; setting the last child's

value to “value” if its value is not existed.

Ex:

commonUtil.createObjFromString(global, "widget.plugin.example.line.line_1.interfaceObj",

{}).

- commonUtil.isIOSSafari():

Return if current browser is safari and run on iOS. Its value is true or false.

5.4 APIs in dashboardUtil

- dashboardUtil.getWidgetObjList(widCategory, dashName)

It will return an array of objects with the same “widCatgory”. An object contains elements

of widgetId and widgetName.

“dashName” can be ignored if you want the widget list in the same dashboard.

- dashboardUtil.notifyAndRefreshWids(widgetId)

Notify the value change event to all Data Follower Widgets which follow your “widgetId”

widget in current dashboard. It will notify all widgets in this dashboard if “widgetId” is





undefined.

- dashboardUtil.isWidgetIdExisted(widgetId)

Check if “widgetId” widget is existed in current dashboard or not.

- dashboardUtil.getDashboardList(waDashboardConstants.TARGET_FILE)

Get a dashboard list object

Format: Array of objects. For each object, contains the following variables

recId : dashboard’s id

folderName : dashboard’s folder name

fileName : dashboard’s display name

You may use this object to generate a dashboard dropdown list in your widget’s property

page for specifying which dashboard you want to open in the click event function.





5.5 APIs in uiUtil

- uiUtil.appendColorPickerStyle(elemIds):

Appending jpicker style to html element. The parameter "elemIds" is id of html element. It is

either an array of ids or a single id.

- uiUtil.appendRadioStyle(elemIds):

Appending jpicker style to html element. The parameter "elemIds" is id of html element. It is

either an array of ids or a single id.

- uiUtil.setRGBAToJpicker(rgba_str, jpicker_obj):

Converting color (RGBA) in string format into color (RGBA) JSON object format.

rgba_str :RGBA in string.

jpicker_obj : jPicker object.

- uiUtil.getRGBAFromJpicker(jpicker_obj):

jPicker saves the color (RGBA) in a JSON object format,

,

Note:

jPicker’s alpha are ranged from 0~255 (0= 0% ~ 255 = 100%).

Parameters: jPicker object

Return: RGBA in string format. Example “rgba(0,0,0,1)”

- uiUtil.addTagList(elemJobj):

Auto create tag list with filter function.

Parameters: jQuery element object (input type=text)

Return: none





- uiUtil.appendAndShowQuickSysMsg(message):

Display message in Dashboard Viewer (PC/Tablet mode or Mobile phone mode).

Parameters:

message : a string that you want to display.

Return: none





5.6 APIs in dashboardProperty

- dashboardProperty.setMapObj(pJson, hId, hType, feedFunc, applyFunc):

To organize the giving parameters and construct to a single JSON format object. It is mainly

used for swapping data between cache (JSON object) and html element. The parameters

feedFunc and applyFunc are optional. This API returns a JSON format object.

pJson is the object of the JSON in string format.

hId is the ID of the HTML in string format.

hType is the type of the html element in string format. Valid values are "text", "int", "jpicker",

"radio", "setValue" currently. You could refer

widget.builtin.text.singleLineText.util.mappingRule.getRuleObj() for how to use it.

- dashboardProperty.htmlCacheMapping(MapArray, handle, widobj):

Swapping data between cache and the property HTML. Based on the different type of html

element, it will handle them with the appropriate method. Currently dashboard support: "text",

"int", "jpicker", "radio", "setValue". Other type of handler will be added in the future.

mapArray : an Array list of mapping ID.

handle :handler (“toCache” or “toHtml”) in string.

Widobj : structObj





5.7 APIs in dashboardCommon

- dashboardCommon. getWidgetStructObj(dashName, lid):

Getting structObj from cache

- dashboardCommon. setWidgetStructObj (dashName, lid, obj):

In contrast to dashboardCommon. getWidgetStructObj, it is a method for setting value.

- dashboardCommon.getWidgetCacheObj(dashName, lid)

Get WidgetCacheObj of “lid” widget in “dashName” dashboard. It will return a JavaScript

Object.

After getting WidgetCacheObj, you can access:

widget common properties in WidgetCacheObj.widProperty.

Your structObj in WidgetCacheObj.structObj.

You can use the globe parameter “activeTabFileName” as the input of dashName.

- dashboardCommon.openDashboardbyDiv(recId, folderName, fileName, isRefresh) Open dashboard in Viewer by dashboard ID (recId)

Usually used for binding a click event on your HTML object and jump to the dashboard

(recId).

You can use the API:

dashboardUtil.getDashboardList(waDashboardConstants.TARGET_FI

LE) to generate a dashboard list object. This object contains dashboard id (recId),

folderName and filename. You may use this object to generate a dashboard dropdown list in

your widget’s property page for specifying which dashboard you want to open in the click

event function.

5.8 APIs in dataSourceUtil(via ajax)

001-- dataSourceUtil

API dataSourceUtil.getTagValuesAndRefresh(isAsync, tags, vFormat, lid, cbObj)

Parameter isAsync boolean If you need synchronous requests, set this option to





false, else set it true.

tags array tag name array

vFormat Boolean if you want to get tag display value, set it to true

lid String The id of the most outer div of this widget

cbObj object A call back object. It has two attributes

(waDashboardConstants.CB_ATTR_NAME_FUNC],

waDashboardConstants.CB_ATTR_NAME_PARAMS). You

would define and assign it for executing after getting

tag values.

Description Getting tag values from WebAccess. It wiil subscribe these tags from server.

Server will push new tag value if tag value has changed. Treating tag values as

a parameter and add it to the cbObj’s parameterList attribute. Then execute

this call back object, usually it is redraw the chart with these tag values.

Return [

{

"tagName":"",

"tagType":"",

"value":""

}

]


API dataSourceUtil.getTagValuesAndFieldsAndRefresh(isAsync, tagParams, lid,

cbObj)



tagParams array Tag object array.

Ex: [{tagName:"",tagType:""}]

tagType:





waDashboardConstants.TAG_TYPE_ANALOG =

"1";

waDashboardConstants.TAG_TYPE_DIGITAL = "2";

waDashboardConstants.TAG_TYPE_TEXT = "3";





waDashboardConstants.CB_ATTR_NAME_PARAMS).

You would define and assign it for executing after

getting tag values.

Description Getting tag/tagfield values and from WebAccess. Treating tag/tagfield values

as a parameter and add it to the cbObj’s parameterList attribute. Then execute


Return [

{

"tagName":"",

"tagType":"",

"value":""

}

]


API dataSourceUtil.getRealTimeTagValuesAndSubscribe(isAsync, tags,

RecordCount, lid, cbObj)

Parameter isAsync boolea

n

If you need synchronous requests, set this option

to false, else set it true.






RecordCou

nt number Number of records.




waDashboardConstants.CB_ATTR_NAME_PARAMS)

. You would define and assign it for executing after

getting tag values.

Description Getting real time tag values array from WebAccess. Used for real time trend.

It wiil subscribe these tags from server. Server will push new value if value

has changed. Treating tag values as a parameter and add it to the cbObj’s

parameterList attribute. Then execute this call back object, usually it is

redraw the chart with these tag values.

Return [

{

"Name":"AO_01",

"Total":10,

"StartTime":"2015-04-28 11:11:00",

"Values":[]

}

]


API dataSourceUtil.unsubscribeRealTimeTag(isAsync, realtimeTagParams, lid,

cbObj)

Parameter isAsync boolean If you need synchronous requests, set this

option to false, else set it true.

realtimeTagPara

ms

object {Interval:"", Records:"", Total:"",

Tags:[Name:""]}







(waDashboardConstants.CB_ATTR_NAME_F

UNC],

waDashboardConstants.CB_ATTR_NAME_P

ARAMS). You would define and assign it for

executing after getting tag values.

Description Unsubscribe real time trend tag value.

Return none


API dataSourceUtil.setTagValuesAndRefresh(isAsync, tags, vFormat, lid, cbObj)










getting tag values.

Description Setting tag/tagfield values to WebAccess.

Return none






API dataSourceUtil.getNodeList()

Parameter

Description Get WebAccess node list.

Return [

{

"nodeName":"SCADA",

"description":""

}

]


API dataSourceUtil.getActionLogCount(isAsync, nodeName, lid, cbObj)



nodeName string WebAccess node name.






getting tag values.

Description Get Action log’s total count.

Return number


API dataSourceUtil.getActionLogAndCount (isAsync, nodeName, count, start, lid,

cbObj)








count number Number of log.

start number Started log number.






getting tag values.

Description Get Action log and total count.

Return {

"nodeName":"SCADA",

"totalCount":"63",

"actionLogs":[

{

"action":”",

"description":"",

"priority":"",

"tagName":"",

"time":"2015/04/20 15:24:21"

}

],

"resStatus":"0"

}






API dataSourceUtil.getActionLog (isAsync, nodeName, count, start, lid, cbObj)











getting tag values.

Description Get Action log.

Return [

{

"action":"",

"description":"",

"priority":"",

"tagName":"",

"time":"2015/04/20 15:24:21"

}

]


API dataSourceUtil.getAlarmLogCount(isAsync, nodeName, lid, cbObj)













getting tag values.

Description Get Alarm log total count.

Return number


API dataSourceUtil.getAlarmLogAndCount(isAsync, nodeName, count, start, lid,

cbObj)











getting tag values.

Description Get Alarm log and total count.

Return {

"nodeName":"SCADA",





"totalCount":"5000",

"alarmLogs":[

{

"action":"",

"description":"",

"priority":"",

"tagName":"”,

"time":"2015/04/28 11:17:23"

}

],

"resStatus":"0"

}


API dataSourceUtil.getAlarmLog(isAsync, nodeName, count, start, lid, cbObj)











getting tag values.

Description Get Alarm log.





Return [

{

"action":"",

"description":"",

"priority":"",

"tagName":"”,

"time":"2015/04/28 11:17:23"

}

]

013*-- dataSourceUtil

API dataSourceUtil.getAlarmSummaryCount(isAsync, lid, cbObj)








getting tag values.

Description Get Alarm Summary total count.

Return number


API dataSourceUtil.getAlarmSummaryAndCount (isAsync, count, start, lid, cbObj)














getting tag values.

Description Get Alarm Summary log and total count.

Return {

"totalCount":"10",

"alarmSummaries":

[

{

"ackStatus":1,

"alarmGroup":0,

"alarmPriority":8,

"name":"calc_dis03",

"time":"15/4/28 11:19:8",

"alarmValue":0.0,

"alarmLimit":0.0,

"alarmType":8,

"locked":0,

"nodeName":"SCADA"

}

],

"resStatus":"0"

}






API dataSourceUtil.getAlarmSummary(isAsync, count, start, lid, cbObj)










getting tag values.

Description Get Alarm Summary log.

Return [

{

"ackStatus":1,

"alarmGroup":0,

"alarmPriority":8,


"time":"15/4/28 11:19:8",

"alarmValue":0.0,

"alarmLimit":0.0,

"alarmType":8,

"locked":0,

"nodeName":"SCADA"

}

]






API dataSourceUtil.alarmAckAll (isAsync, nodeName, lid)









getting tag values.

Description Acknowledge alarm log.

Return none


API dataSourceUtil.alarmAck (isAsync, nodeName, tags, lid, cbObj)










getting tag values.

Description Acknowledge all alarm log.





Return none


API dataSourceUtil.getWATagList (listTarget, paramObj)

Parameter listTarget number "1":by project, ="2": by node, ="3": by comport

number, default:by project

paramO

bj

object {proj:"projectName",node:"nodeName",comp:"comp

ortNbr"}

Description Get tag list

Return [

{tagName:""},

{tagName:""}

]


API dataSourceUtil.getTagsData(isAsync, tags, attrName, lid, cbObj)




attrNa

me array ["Name","Name"]

Analog:

"NAME", "ADDRS", "DESCRP", "TYPE",

"PADDRS", "NODE", "COM", "DEVNM", "SECL",

"SECA", "ENUNIT", "SPANHI", "SPANLO",

"OUTPHI", "OUTPLO", "DSPFMT", "ALMHI",

"ALMLO", "ALMHH", "ALMLL", "ALMROC",

"ADVHI", "ADVLO", "APRHH", "APRHI",

"APRLO", "APRLL", "APRHDV", "APRLDV",





"APRROC"

Digital:

"NAME", "ADDRS", "DESCRP", "TYPE",

"PADDRS", "NODE", "COM", "DEVNM", "SECL",

"SECA", "DESCR0", "DESCR1", "DESCR2",

"DESCR3", "DESCR4", "DESCR5", "DESCR6",

"DESCR7", "PRDIG0", "PRDIG1", "PRDIG2",

"PRDIG3", "PRDIG4", "PRDIG5", "PRDIG6",

"PRDIG7"

Text:

"NAME", "ADDRS", "DESCRP", "TYPE", "PADDRS",

"NODE", "COM", "DEVNM", "SECL", "SECA", "TXTLEN"






getting tag values.

Description Getting tagfield values and from WebAccess.

Return [

{

"NAME":"AO_01",

"DESCRP":"Analog Output",

"ADDRS":"40001",

"TYPE":"ANALOG",

"PADDRS":"40001[0:16]"

……

}

]






API dataSourceUtil.getDataLog (isAsync, nodeName, tags, startTime,

intervalType, interval, recordsCount, dataType, lid, cbObj)


n



nodeName String WebAccess node name.


startTime string Start time

Format: yyyy-mm-dd HH:MM:SS

intervalTyp

e

String Interval type between each data

S: secend，M: minute，H: hour，D: day

interval number Interval between each data base on intervalType

recordsCou

nt

number Number of records.

dataType number 0 - Last，1-Min，2 - Max，3 - Avg。

attrName array ["Name","Name"]






getting tag values.

Description Get data log value.

Return [

{

"Name":"",

"Total":"10",





"StartTime":"2015-04-28 11:32:16",

"Values":[]

}

]


API dataSourceUtil.getDataLogByProject (isAsync, tags, startTime, intervalType,

interval, recordsCount, dataType, lid, cbObj)


n






intervalTyp

e



interval number Interval between each data base on intervalType

recordsCou

nt



attrName array ["Name","Name"]






getting tag values.

Description Get data log value by project.





Return [

{

"Name":"",

"Total":"10",

"StartTime":"2015-04-28 11:32:16",

"Values":[]

}

]


API dataSourceUtil.getMultiDataLogByProject(isAsync, datalogParams, lid,

cbObj)

Parameter isAsync boolean If you need synchronous requests, set this

option to false, else set it true.

datalogPara

ms

array Ex.

[{ "StartTime": "", "IntervalType": "", "Interval":

"", "Records": "", "Tags": [{ "Name": "Name",

"DataType": "DataType"}]}]



(waDashboardConstants.CB_ATTR_NAME_FUNC

],

waDashboardConstants.CB_ATTR_NAME_PARA

MS). You would define and assign it for

executing after getting tag values.

Description

Return [

{

"resStatus":"0",





"datalogs":

[

{

"Name":"AO_01",

"Total":"60",

"StartTime":"2015-04-24 00:00:00",

"Values":[]

}

]

},

{

"resStatus":"0",

"datalogs":

[

{

"Name":"AO_01",

"Total":"60",

"StartTime":"2015-04-28 00:00:00",

"Values":[]

}

]

}

]


API dataSourceUtil.getStationStatus (isAsync, nodeName, lid, cbObj)







nodeName string WebAccess Node name.






getting tag values.

Description

Return [

{"devices":[{"status":0,"unit":0}],"port":1,"status":0,"totalDevice":1}

]


API dataSourceUtil.getCompStatus (isAsync, nodeName, lid, cbObj)









getting tag values.

Description

Return {

"nodeName":"SCADA",

"staComps":





[

{

"devices":[],

"port":1,

"status":0,

"totalDevice":1

}

],

"resStatus":"0"

}


API dataSourceUtil.getDevStatus(isAsync, nodeName, port, lid, cbObj)




port number WebAccess comport number.






getting tag values.

Description

Return {

"nodeName":"SCADA",

"staDevs":

[





{

"status":0,

"unit":0

}

],

"resStatus":"0"

}


API dataSourceUtil.setComportStatus (isAsync, nodeName, port, state, lid,

cbObj)




port number WebAccess comport number.

state number 0:Enable; Other:Disable






getting tag values.

Description

Return none


API dataSourceUtil.setDeviceStatus(isAsync, nodeName, port, unit, state, lid,





cbObj)




port number WebAccess comport number.( 1~60)

unit number (0-255)

state number 0:Enable; Other:Disable






getting tag values.

Description Get device status.

Return none


API dataSourceUtil.getTagListByProjectFilter (filters)

Parameter filters string {

"Filters":[{

"Name":"TAGNAME",

"Value":"Con%"},

{

"Name":"ANALOG",

"Value":"FALSE"

}]

}





Description Get tag list with filter

Return [

{tagName:""},

{tagName:""}

]


API dataSourceUtil.getNodeStatus (isAsync, cbObj)







getting tag values.

Description Get Node status

Return


API dataSourceUtil.getBlockListByProject()

Parameter

Description Get Block list.

Return [{"blockId":1,"blockName":"04000A6015"}]






API dataSourceUtil.getBlockDetailByProject(blockName)

Parameter blockName string WebAccess project block name

Description Get Block detail in current project

Return [

{

"Address":"40001",

"Description":"AI_0",

"TagName":"04000A6015:AI_0",

"TagType":"Analog"

}

]

5.9 APIs in dataSourceUtilRT(via signalr)

001--dataSourceUtilRT

API dataSourceUtilRT.getTagValuesAndRefresh(isRT,tags, vFormat, lid, cbObj)

Parameter tags array tag name array

vFormat Bool if you want to get tag display value, set it to true





would define and assign it for executing after getting tag





values.





Return [

{

"tagName":"",

"tagType":"",

"value":""

}

]


API dataSourceUtilRT.getTagValuesAndFieldsAndRefresh(tagParams, lid, cbObj)

Parameter tagParams array tag info array, each element include tag name and type.

Tag type is must if you want to get its field value. If tag

type is numeric, use

waDashboardConstants.TAG_TYPE_ANALOG. Else

use waDashboardConstants.TAG_TYPE_TEXT.

Ex: [{ { "tagName": AI_0, "tagType":

waDashboardConstants.TAG_TYPE_ANALOG }},

{ { "tagName": AI_0.ENUNIT, "tagType":

waDashboardConstants.TAG_TYPE_TEXT } ]






values.





Description Getting tag/tagfield values and from WebAccess. It wiil subscribe these

tags/tagfields from server. Server will push new value if value has changed.

Treating tag/tagfield values as a parameter and add it to the cbObj’s

parameterList attribute. Then execute this call back object, usually it is redraw

the chart with these tag values.

Return [

{

"tagName":"",

"tagType":"",

"value":""

}

]


API dataSourceUtilRT.getRealTimeTagValuesAndSubscribe(tags, RecordCount, lid,

cbObj)


RecordCount number Number of record






getting tag values.

Description Getting real time tag values array from WebAccess. It wiil subscribe these tags

from server. Server will push new value if value has changed. Treating tag

values as a parameter and add it to the cbObj’s parameterList attribute. Then

execute this call back object, usually it is redraw the chart with these tag

values.





Return [

{

"Name":"AO_01",

"Total":10,

"StartTime":"2015-04-28 11:11:00",

"Values":[]

}

]


API dataSourceUtilRT.getActionLogAndCount (nodeName, count, start, lid,

cbObj)

Parameter nodeName String Node name

count number Number of log count







getting tag values.

Description Getting action log and title count from WebAccess.

Return {

"nodeName":"SCADA",

"totalCount":"63",

"actionLogs":[

{

"action":”",





"description":"",

"priority":"",

"tagName":"",

"time":"2015/04/20 15:24:21"

}

],

"resStatus":"0"

}


API dataSourceUtilRT.getAlarmLogAndCount (nodeName, count, start, lid, cbObj)

Parameter nodeName String Node name








getting tag values.

Description Getting WebAccess node alarm log and title count.

Return {

"nodeName":"SCADA",


"alarmLogs":[

{

"action":"",

"description":"",





"priority":"",

"tagName":"”,

"time":"2015/04/28 11:17:23"

}

],

"resStatus":"0"

}


API dataSourceUtilRT.getAlarmSummaryAndCount ( count, start, lid, cbObj)

Parameter count number Number of log count







values.

Description Get WebAccess alarm summary log and title count.

Return {

"totalCount":"10",

"alarmSummaries":

[

{

"ackStatus":1,

"alarmGroup":0,

"alarmPriority":8,






"time":"15/4/28 11:19:8",

"alarmValue":0.0,

"alarmLimit":0.0,

"alarmType":8,

"locked":0,

"nodeName":"SCADA"

}

],

"resStatus":"0"

}


API dataSourceUtilRT.getNodeStatus (cbObj)

Parameter cbObj object A call back object. It has two attributes



You would define and assign it for executing after getting

tag values.

Description Get WebAccess node status.

Return [

{

"nodeName":"SCADA",

"status":1

}

]


API dataSourceUtilRT.getCompStatus (nodeName, lid, cbObj)





Parameter nodeName string WebAccess node name






tag values.

Description Get comports status from WebAccess.

Return {

"nodeName":"SCADA",

"staComps":

[

{

"devices":[],

"port":1,

"status":0,

"totalDevice":1

}

],

"resStatus":"0"

}


API dataSourceUtilRT.getDevStatus (nodeName, port, lid, cbObj)

Parameter nodeName string WebAccess node name.

port string Comport number.










tag values.

Description Get devices status from WebAccess.

Return {

"nodeName":"SCADA",

"staDevs":

[

{

"status":0,

"unit":0

}

],

"resStatus":"0"

}


API dataSourceUtilRT.getDataLog (nodeName, tags, startTime, intervalType,

interval, recordsCount, dataType, lid, cbObj)

Parameter nodeName String WebAccess node name. if you want to get data log

by project set this parameter equal “” empty string.




intervalType String Interval type between each data


interval Number Interval between each data base on intervalType





recordsCount number Number of records.







getting tag values.

Description Getting tags data log in WebAccess.

Return [

{

"Name":"",

"Total":"10",

"StartTime":"2015-04-28 11:32:16",

"Values":[]

}

]


API dataSourceUtilRT.remMonitorTags(tags, vFormat, lid, cbObj)


vFormat Bool if your tag used display value, set it to true










values.

Description Remove tags from signalR’s pool.

Return none


API dataSourceUtilRT. getNodeStatusWithInterval (lid, cbObj)

Parameter lid String The id of the most outer div of this widget





values.

Description Used interval as a timer to get node status.

Return

5.10 APIs in webCommunicator

- webCommunicator.dispatchTagValues(lid, result):

This api is called by Server(signalr). It pushes new tag values to client when subscribed tags

related to some client has changed. Then it calls the refreshWidValue() of this widget. It stores

tagInfos in the attribute of optional parameter named “tagInfos”.

5.11 APIs in dataSourceUtilCombo

001-- dataSourceUtilCombo

API dataSourceUtilCombo.getTagValuesAndRefresh(isRT,tags, vFormat, lid,





cbObj)

Parameter isRT bool If you want the tag value from signalr, then set its value

true. Otherwise, set its value false, then the tag value is

from ajax.


vFormat Bool if you want to get tag display value, set it to true






values.





Return [

{

"tagName":"",

"tagType":"",

"value":""

}

]


API dataSourceUtilCombo.getTagValuesAndFieldsAndRefresh(isRT, tagParams,

lid, cbObj)







from ajax.

tagParams array tag info array, each element include tag name and type.

Tag type is must if you want to get its field value. If tag

type is numeric, use

waDashboardConstants.TAG_TYPE_ANALOG. Else

use waDashboardConstants.TAG_TYPE_TEXT.

Ex: [{ { "tagName": AI_0, "tagType":

waDashboardConstants.TAG_TYPE_ANALOG }},

{ { "tagName": AI_0.ENUNIT, "tagType":

waDashboardConstants.TAG_TYPE_TEXT } ]






values.

Description Getting tag/tagfield values and from WebAccess. It wiil subscribe these

tags/tagfields from server. Server will push new value if value has changed.

Treating tag/tagfield values as a parameter and add it to the cbObj’s

parameterList attribute. Then execute this call back object, usually it is redraw

the chart with these tag values.

Return [

{

"tagName":"",

"tagType":"",

"value":""

}

]






API dataSourceUtilCombo.getRealTimeTagValuesAndSubscribe(isRT, tags,

RecordCount, lid, cbObj)

Parameter isRT bool If you want the tag value from signalr, then set its

value true. Otherwise, set its value false, then the

tag value is from ajax.


RecordCount number Number of record






getting tag values.

Description Getting real time tag values array from WebAccess. It wiil subscribe these tags

from server. Server will push new value if value has changed. Treating tag

values as a parameter and add it to the cbObj’s parameterList attribute. Then

execute this call back object, usually it is redraw the chart with these tag

values.

Return [

{

"Name":"AO_01",

"Total":10,

"StartTime":"2015-04-28 11:11:00",

"Values":[]

}

]


API dataSourceUtilCombo.getActionLogAndCount (isRT, nodeName, count, start,





lid, cbObj)


value true. Otherwise, set its value false, then the tag

value is from ajax.

nodeName String Node name








getting tag values.

Description Getting action log and title count from WebAccess.

Return {

"nodeName":"SCADA",

"totalCount":"63",

"actionLogs":[

{

"action":”",

"description":"",

"priority":"",

"tagName":"",

"time":"2015/04/20 15:24:21"

}

],

"resStatus":"0"

}






API dataSourceUtilCombo.getAlarmLogAndCount (isRT, nodeName, count,

start, lid, cbObj)



from ajax.

nodeNa

me

String Node name








tag values.

Description Getting WebAccess node alarm log and title count.

Return {

"nodeName":"SCADA",


"alarmLogs":[

{

"action":"",

"description":"",

"priority":"",

"tagName":"”,

"time":"2015/04/28 11:17:23"

}

],





"resStatus":"0"

}


API dataSourceUtilCombo.getAlarmSummaryAndCount (isRT, count, start, lid,

cbObj)

Parameter isR

T

bool If you want the tag value from signalr, then set its value true.

Otherwise, set its value false, then the tag value is from ajax.

co

un

t

number Number of log count

sta

rt

number Started log number.


cb

Ob

j

object A call back object. It has two attributes




values.

Description Get WebAccess alarm summary log and title count.

Return {

"totalCount":"10",

"alarmSummaries":

[

{

"ackStatus":1,

"alarmGroup":0,

"alarmPriority":8,






"time":"15/4/28 11:19:8",

"alarmValue":0.0,

"alarmLimit":0.0,

"alarmType":8,

"locked":0,

"nodeName":"SCADA"

}

],

"resStatus":"0"

}


API dataSourceUtilCombo.getNodeStatus (isRT)



from ajax.

Description Get WebAccess node status.

Return [

{

"nodeName":"SCADA",

"status":1

}

]


API dataSourceUtilCombo.getCompStatus (isRT, nodeName, lid, cbObj)







from ajax.

nodeN

ame

string WebAccess node name






values.

Description Get comports status from WebAccess.

Return {

"nodeName":"SCADA",

"staComps":

[

{

"devices":[],

"port":1,

"status":0,

"totalDevice":1

}

],

"resStatus":"0"

}


API dataSourceUtilCombo.getDevStatus (isRT, nodeName, port, lid, cbObj)



from ajax.






port string Comport number.






tag values.

Description Get devices status from WebAccess.

Return {

"nodeName":"SCADA",

"staDevs":

[

{

"status":0,

"unit":0

}

],

"resStatus":"0"

}


API dataSourceUtilCombo.getDataLog (isRT, nodeName, tags, startTime,




value is from ajax.

nodeName String WebAccess node name.








intervalTyp

e



interval Number Interval between each data base on intervalType

recordsCou

nt








getting tag values.

Description Getting tags data log in WebAccess.

Return [

{

"Name":"",

"Total":"10",

"StartTime":"2015-04-28 11:32:16",

"Values":[]

}

]


API dataSourceUtilCombo.getDataLogByProject (isRT, tags, startTime,








value is from ajax.




intervalTy

pe



interval Numbe

r

Interval between each data base on intervalType

recordsCo

unt

numbe

r

Number of records.

dataType numbe

r

0 - Last，1-Min，2 - Max，3 - Avg。






getting tag values.

Description Getting tags data log by Project in WebAccess.

Return [

{

"Name":"AO_01",

"Total":"10",

"StartTime":"2015-04-28 11:32:16",

"Values":[]

}

]






API dataSourceUtilCombo.remMonitorTags(isRT, tags, vFormat, lid, cbObj)



from ajax.


vFormat Bool if your tag used display value, set it to true






values.

Description Remove tags from signalR’s pool.

Return none

5.12 APIs in validateUtil

- validateUtil.composeExp(errCode, params):

Composing an error for throwing. Mostly used in validating input failure and errCode is the key

in Mui, params is a parameter array for this error string.

5.13 APIs in widgetUtil

- widgetUtil.maximizeWidget (lid, dashName):

Maximizing the div region in dashboard.





- widgetUtil.restoreWidget(lid, dashName):

Restoring the div region in dashboard.

- widgetUtil.getDrawingRegionId(lid):

Getting innder widget div id(widLid) by lid.





Appandax A: About BEMS

A.1. Value of “BEMSBuildingInfo” global parameter:

The value of “BEMSBuildingInfo” will be the building ID. The rule of value is as follow:

- Enterprise Node:

- 5 digits (Enterprise ID).

- Ex: “00001”

- Company Node:

- 5 digits (Enterprise ID) + 5 digits (Company ID)

- Ex: “0000100001”

- Campus Node:

- 6 digits (Campus ID)

- Ex: “110000”

- Building Node:

- 6 digits (Campus ID) + 1 Char (Building Type) + 3 digits (Building ID)

- Ex: “110000A001”

- Floor Node:

- “Building Node ID” + 4 digits (Floor ID)

- Ex: “110000A0010001”

- Area Node:

- “Building Node ID” + 4 digits (Area ID)

- Ex: “110000A0010002”