69
WebAccess Dashboard Pluggable Widget Interface Programming Guide Version : 1.0.0 Author：WebAccess Team Advantech Co., Ltd
WebAccess Dashboard Pluggable Widget Interface Programming Guide
Version : 1.0.0
Author：WebAccess Team
Advantech Co., Ltd
Contents
CONTENTS ...................................................................................................................................2
1. INTRODUCTION ...................................................................................................................5
1.1 OBJECTIVE .............................................................................................................................5
1.2 DOCUMENT ORGANIZATION ......................................................................................................5
2 REFERENCES .............................................................................................................................6
3 ABBREVIATIONS .......................................................................................................................7
4 WIDGET COMPONENTS ...........................................................................................................8
4.1 OVERVIEW .............................................................................................................................8
4.2 WIDGET INTERFACE ...............................................................................................................11
4.2.1 Basis of Widget Interface .........................................................................................11
4.2.2 Details of Widget Interfaces .....................................................................................14
getInitStructure() ...............................................................................................................14
drawWidChart() .................................................................................................................16
openSavedWidget() ...........................................................................................................19
getWidgetStructure() ........................................................................................................21
validatePropertyValues() ...................................................................................................22
applyPropertyValues() .......................................................................................................24
showPropertyItems() .........................................................................................................25
loadPropertyValues() .........................................................................................................27
refreshWidValue() .............................................................................................................28
getUploadImgNspaces() ....................................................................................................30
getTextMuiNspaces() ........................................................................................................31
4.3 WIDGET PROPERTY PAGE .......................................................................................................32
4.3.1 Design guideline .......................................................................................................32
4.3.2 Common Properties of every Widget.......................................................................34
4.4 WIDGET METADATA ..............................................................................................................36
4.4.1 Library Information ..................................................................................................37
4.4.2 Widget Information ..................................................................................................39
4.5 MULTI-LANGUAGE ................................................................................................................43
4.5.1 Prepare the Language Pack ......................................................................................43
4.5.2 For static HTML pages ..............................................................................................44
4.5.3 For dynamic content ................................................................................................45
4.5.4 For Generating MUI Dialog in Property page ...........................................................47
4.6 WIDGET INTERACTION ...........................................................................................................50
4.6.1 Data Commander Widget .........................................................................................51
4.6.2 Data Follower Widget ...............................................................................................55
5 DASHBOARD APIS ..................................................................................................................57
5.1 JAVASCRIPT GLOBAL VARIABLES...............................................................................................57
5.2 APIS IN PARAMETERUTIL ........................................................................................................58
5.3 APIS IN COMMONUTIL ...........................................................................................................59
5.4 APIS IN DASHBOARDUTIL .......................................................................................................59
5.5 APIS IN UIUTIL .....................................................................................................................61
5.6 APIS IN DASHBOARDPROPERTY ................................................................................................63
5.7 APIS IN DASHBOARDCOMMON ................................................................................................64
5.8 APIS IN DATASOURCEUTIL(VIA AJAX) ........................................................................................64
5.9 APIS IN DATASOURCEUTILRT(VIA SIGNALR) ...............................................................................66
5.10 APIS IN WEBCOMMUNICATOR ...............................................................................................66
5.11 APIS IN DATASOURCEUTILCOMBO .........................................................................................67
5.12 APIS IN VALIDATEUTIL .........................................................................................................67
5.13 APIS IN WIDGETUTIL ...........................................................................................................67
APPANDAX A: ABOUT BEMS ....................................................................................................69
A.1. VALUE OF “BEMSBUILDINGINFO” GLOBAL PARAMETER: .............................................................69
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 Web Service 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
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 their 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 then 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
Interface to be implemented:
openSavedWidget() //return saved widget object structure for opening a
dashboard
Save Dashboard
Interface to be implemented:
getWidgetStructure() //return widget object structure for saving into a
dashboard
Apply Widget Properties to Cache
Interface to be implemented:
validatePropertyValues() //validate property values
applyPropertyValues() //set property values to widget object structure
Select Widget and display its properties
Interface to be implemented:
showPropertyItems() //construct html structure of this widget
loadPropertyValues() // show properties value of this widget
Refresh Value
Interface to be implemented:
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 the information into a
JavaScript object and return for further 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 further 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 library 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
- The id of the most outer div of this widget
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)
- Reserve for further use in the future. Can be ignored currently.
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
- The id of the most outer div of this widget
structObj - Object structure of this widget.
- Note: This object is come from saved dashboard file. The data in this object are
determined by what you saved in getWidgetStructure() interface.
params - Reserve for further use in the future. Can be ignored currently.
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 attributes 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
- The id of the most outer div of this widget
structObj - Object structure of this widget.
params - Reserve for further use in the future. Can be ignored currently.
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
- The id of the most outer div of this widget
params - Reserve for further use in the future. Can be ignored currently.
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 values of #dxRecordCount and #tooltipSize are not number. If not, use validateUtil.composeExp() API to create an 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
- The id of the most outer div of this widget
structObj
- Object structure of this widget.
params - Reserve for further use in the future. Can be ignored currently.
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 then
append these HTML contents 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” global 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
- The id of the most outer div of this widget
propertyPagePaths
- Property page paths which are defined in Widget Metadata (widgetInfo.xml)
structObj
- Object structure of this widget.
params - Reserve for further use in the future. Can be ignored currently.
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 contents 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
- The id of the most outer div of this widget
structObj - Object structure of this widget.
params - Reserve for further use in the future. Can be ignored currently.
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 Web Service. 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
- The id of the most outer div of this widget
structObj - Object structure of this widget.
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.14 shows a Property Pane of line_2 widget:
Figure 4.14 Property Pane of line_2 widget
Figure 4.15 shows a portion of the HTML code for the HTML property page. It represents
the Title property.
Figure 4.15 - 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 many 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 built in by WebAccess Dashboard. It will automatically been loaded by WebAccess Dashboard before loading Widget’s property page. In Figure 4.14, 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’ descriptions are as follow:
- Widget Preference Name, (widProperty.widPref)
The widget preference name used by this widget The “Widget Setting” properties’ descriptions 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’ descriptions 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 information 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 among 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.
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 supported 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, localStorage.getItem('langJs_currentLang')); $("#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 return [“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, localStorage.getItem('langJs_currentLang')); 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 could 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 integer value that user inputted 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”
- Variable (Value of widgetVar)::
textValue: specify the value of text; (string)
4.6.1.6 Single Select Tree Widget
- Value of WidCategory: “SingleTree”
- Variable (Value of widgetVar)::
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):
Append 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):
Append 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):
Convert 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):
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):
Swap 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_FILE) 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)
- dataSourceUtil.getWATagListToOption():
Getting tag List from Web Access and convert it into html element: (<option>tag1</option ><option>tag2</option >…).
- dataSourceUtil.getWATagListHtml(selectId):
Much like dataSourceUtil.getWATagListToOption except that it encloses the result with a <select></select> tag
- dataSourceUtil.getTagValuesAndRefresh(isAsync, tags, vFormat, cbObj):
Getting tag values from WebAccess. 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. isAsync: usually set it to true tags: tag name array vFormat: if you want to get tag display value, set it to true cbObj:
A callback 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.
- dataSourceUtil. getTagValuesAndFieldsAndRefresh (isAsync, tagParams,cbObj):
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 this call back object, usually it is redraw the chart with these tag values. isAsync: usually set it to true tagParams: 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 } ]
cbObj: 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/tagfield values.
- dataSourceUtil.getWATagList (listTarget, paramObj):
- dataSourceUtil.getWATagListFilter (listTarget, paramObj, filters):
listTarget: choose tag from project, node or comport ."1":by project, ="2": by node, ="3": by comport number, default:by project. paramObj: give project name , node name, comport number. filters: filter conditions.
5.9 APIs in dataSourceUtilRT(via signalr)
- dataSourceUtilRT.getTagValuesAndRefresh(tags,vFormat,lid,cbObj):
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. isAsync: usually set it to true tags: tag name array vFormat: if you want to get tag display value, set it to true cbObj:
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.
- dataSourceUtilRT. getTagValuesAndFieldsAndRefresh (isAsync, tagParams,cbObj):
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. isAsync: usually set it to true tagParams: 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 } ]
cbObj: 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/tagfield values.
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 have 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
- dataSourceUtilCombo.getTagValuesAndRefresh(isRT, tags, vFormat, lid,
cbObj):
This API is similar to dataSourceUtilRT.getTagValuesAndRefresh and dataSourceUtil.getTagValuesAndRefresh except that it has a parameter named “isRT”. If you want the tag value from sinalr, then set its value true. Otherwise, set its value false, then the tag value is from ajax. Parameters: please refer to dataSourceUtilRT.getTagValuesAndRefresh and dataSourceUtil.getTagValuesAndRefresh.
- dataSourceUtilCombo.getTagValuesAndFieldsAndRefresh(isRT,
tagParams, lid, cbObj):
This API is similar to dataSourceUtilRT.getTagValuesAndFieldsAndRefresh and dataSourceUtil.getTagValuesAndFieldsAndRefresh except that it has a parameter named “isRT”. If you want the tag value from sinalr, then set its value true. Otherwise, set its value false, then the tag value is from ajax. Parameters: please refer to dataSourceUtilRT.getTagValuesAndFieldsAndRefresh and dataSourceUtil.getTagValuesAndFieldsAndRefresh.
5.12 APIs in validateUtil
- validateUtil.composeExp(errCode, params):
Compose 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):
Maximize the div region in dashboard.
- widgetUtil.restoreWidget(lid, dashName):
Restore the div region in dashboard.
- widgetUtil.getDrawingRegionId(lid):
Get inner 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”
