Build your own widget usingAdapterWidget

EasyIO

Version 1.0, 2019-10-10

Table of ContentsWhat is AdapterWidget ? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  1

Why develop AdapterWidget ? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  1

Who should use AdapterWidget ? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  1

How to develop widget based on AdapterWidget ? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  1

Define User Property. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  2

Define Widget’s logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  3

Toggle Widget Demo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  4

1. Download jQuery Toggles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  4

2. Create AdapterWidget and Define User Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  4

3. Make Data Binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  5

4. Javascript Coding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  6

5. Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  7

6. Define More User Properties For setTrue/setFalse Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  8

7. Hook Widget’s Event To setTrue/setFalse Action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  9

8. Final Tweak. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  10

9. Make Your Widget as UserLib . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  10

10. Export Your Widget as a package file(.gul) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  11

11. Import Widget from a package file(.gul) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  11

Reuse AdapterWidget in CPT Dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  11

Develop Widget using AdapterWidget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  12

Convert AdapterWidget based UserLib into a CPT Dashboard widget . . . . . . . . . . . . . . . . . . . . . . . . .  13

Manage CPT Dashboard widget converted from AdapterWidget . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  13

AdapterWidget Programming Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  14

Container Dom Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  14

this.elem. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  14

Callback Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  15

requiredScripts() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  15

init() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  15

update(userPropertyName) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  15

cleanup() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  16

Data Service Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  16

readData(propertyName) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  16

writeData(userPropertyName, value) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  16

invokeAction(path, [value, [valueDataType='void']]) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  16

hasData(userPropertyName) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  17

runSqlQuery(query, dataCallback) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  17

hasWritePerm() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  18

readNote(path, dataHandler) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  18

writeNote(path, content) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  18

startSpinner() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  19

stopSpinner() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  19

Preloaded 3rd Javascript Library. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  19

What is AdapterWidget ?AdapterWidget is developed for CPT graphics widget developers, who want to develop his/her ownwidgets running on CPT graphics web page and/or CPT dashboard, then maybe deliver the newwidgets to his/her customer to use.

Why develop AdapterWidget ?CPT Tools already provide dozens of widgets for user to choose when building CPT graphics. But itis hard to meet all user’s diverse requirements, so we come out AdapterWidget.

AdapterWidget already handles the logics of data communication, applying basic widgetproperties(size, zorder etc), javascript/css files loading, so that developer of AdapterWidget can justfocus on the specific logic of his/her own widget.

After you develop an AdapterWidget, you can save it as a Graphic UserLib, then export it as singlepackage file to share it with others for reuse, more details on how to export a Graphic UserLib andhow to import a Graphic UserLib.

Most of AdapterWidget can be converted to a CPT Dashboard widget with one click, withoutchanging any code. That means your efforts spent on developing AdapterWidget can be reused onCPT Dashboard. More details on how to reuse AdapterWidget in CPT Dashboard

Who should use AdapterWidget ?AdapterWidget is NOT for non-technical users. To develop new widget based on AdapterWidget,you will need to be familiar with Javascript, Html and CSS. Otherwise, AdapterWidget is not for you.

AdapterWidget is a perfect fit under following cases:

• want more graphic widgets that CPT Tools not provided yet

• the widget provided by CPT Tools not meet your requirement well

• provide project specific widgets to your customer, so that they can use them

• you know web programming technologies

How to develop widget based onAdapterWidget ?To develop your widgets based on AdapterWidget, you will need to do two things:

• Define User Property

• Coding new widgets’s logic

1

To develop your widget based on AdapterWidget framework, you will need toknow some basic knowledge of web development, some good online course aboutweb development:

• Learn web development

• jQuery Tutorial

Define User PropertyWhen you define a new widget based on AdapterWidget, you probably want to allow users of yourwidget to customize the look-n-feel or logics. You can define your own properties on your widgetfor above purpose. We name your own property as User Property.

User Property behaves the same as other property(like size, zorder, visible etc), except onedifference: its name must start with @. This helps CPT Tools to differentiate User Property frombuiltin property.

For example, if you are developing a Slider widget for user to change some integer data point’svalue, you may want user to define the valid value range. You can use User Property to implementthat.

Till now, there are 7 data types(String, Integer, Float, Boolean, Area, Color and Image) for UserProperty. When you creating a new User Property, you can choose the most suitable data type.When user edits User Property, CPT Tools will choose the most suitable property editor widgetbased on the User Property’s data type.

To define a User Property:

• Select an AdapterWidget

• In AdapterWidget’s property editor, right click, then in the contextual menu, choose "New UserProperty …"

2

• In the new User Property dialog, define its name and data type, then save

User Property’s name MUST start with character @.

Placeholder

tooltip text for the User Property, displayed when user mouse over your UserProperty in CPT Tools.

ActionOnly

specify the User Property is an action, CPT Tools will only display allcomponent’s actions when you edit it. To enable this, the User Property must bea String.

• Then the new property will show up in the property editor tree, and you can give it a defaultvalue

Define Widget’s logicNow you need to input your widget’s logics(javascript codes) into javascriptCode property. ClickjavascriptCode property, a code editor dialog will show up, and CPT have put some code skeletonand comments there.

There are 3 areas in the AdapterWidget Editing window: Code Editor, Preview and Test Data:

3

• Code Editor is plain code editor, that support javascript syntax highlight, simple code errorchecking etc. And you change the font’s size at the bottom of the Code Editor.

• Preview is a simple embed web browser, that will create a container for AdapterWidget, set upmock APIs used by AdapterWidget.

This preview area is only designed to have a quick look on the widget’s UI looking,it does not communicate with controller backend. If you don’t need it, you can hideit by clicking the checkbox Enable Preview at the bottom of Code Editor.

• Test Data is a list of User Property. For example, you can change @BoolValue User Property andsee what the toggle widget behaves on the fly.

We will explain the programming interface of AdapterWidget in details later, now let’s try a demo.

Toggle Widget DemoHere we will demo how to use AdapterWidget to integrate the wonderful jQuery Toggles, a 3rdparty javascript library, to make our own toggle widget, that can be used on CPT graphics web page.

1. Download jQuery TogglesGo to jQuery Toggles, download the source codes zipball, unzip it under CPT/grweb/public folder, itlooks like this:

2. Create AdapterWidget and Define User PropertyNow we can drag and drop a AdapterWidget(under general category) to graphic canvas, then createa User Property named @BoolValue:

4

3. Make Data BindingNow bind a boolean slot to the new User Property @BoolValue:

5

Here we bind ConstBool.out to @BoolValue property for demo.

4. Javascript CodingNow click the javascriptCode property, and input following codes:

6

this.requiredScripts = function() {  // *Note*, you need to put the javascript/css files  // under 'CPT/grweb/public/user_codes' folder manually,  // otherwise these files cann't be deployed to device  return ["../user_codes/toggles/css/toggles.css",  "../user_codes/toggles/css/themes/toggles-light.css",  "../user_codes/toggles/toggles.js"];};

// the method will be called just after AdapterWidget finishes initializationthis.init = function() {  // this.elem is a div element created by AdapterWidget,  // new html element should be created under it  $(this.elem).css("text-align", "center")  .addClass("toggle toggle-light")  .toggles();

  // set init state of toggle widget  this.update("@BoolValue");};

// update toggle state based on the value of '@BoolValue'// property this method will be called in 'this.init' method// and everytime '@BoolValue' property changedthis.update = function(userPropertyName) {  // only continue if changed property is '@BoolValue'  if (userPropertyName != "@BoolValue")  return;  // set toggle widget's state  $(this.elem).data('toggles').toggle(  // read value of '@BoolValue'  _.str.toBoolean(this.readData("@BoolValue")));};

// [required] put possible clean up codes herethis.cleanup = function() {};

Click Save button, you can see that the toggle widget works in the Preview area. And in Test Dataarea, you can change property @BoolValue to true, the toggle button will display on state; change it tofalse, the toggle button will display off state.

5. DeploymentNow we are ready to push files to controller, do a Full Deployment, wait until it’s done and clickpreview button to see graphic page in browser.

You can change the ConstBool object’s state using setTrue/setFalse actions, and the toggle buttonwill change its state to reflect your changes.

7

Till now, the toggle widget is just a readonly widget, when click it in browser web page, it will toggleits state, but the change will not be pushed to backend object ConstBool.

6. Define More User Properties For setTrue/setFalseActionsWe will define two more User Properties to allow user to specify the setTrue/setFalse actions' path,so that when the toggle widget’s state changed, it will invoke related action.

We use @OnAction for setTrue action, @OffAction for setFalse action. One important thing is whencreate @OnAction and @OffAction, the ActionOnly checkbox must be checked, this will tell CPT Toolsthat this User Property is only about an action slot’s path, so that when user clicks the property forediting, CPT Tools will display action selection editor.

set @OnAction to /ConstBo.setTrue, set @OffAction to /ConstBo.setFalse using the follwoing action editdialog:

8

7. Hook Widget’s Event To setTrue/setFalse ActionNow update javascriptCode:

this.init = function() {  $(this.elem).css("text-align", "center")  .addClass("toggle toggle-light")  .toggles();

  var _this = this;  this.onActionPath = this.readData("@OnAction");  this.offActionPath = this.readData("@OffAction");  $(this.elem).on("toggle", function(e, active) {  if (active)  _this.invokeAction(_this.onActionPath);  else  _this.invokeAction(_this.offActionPath);  });

  this.update("@BoolValue");};

The above code will listen to the toggle event, and when the event happens, it will invoke the actionbased on the active value, that is the current state of toggle widget.

The 'invokeAction' method will communicate with backend to trigger the setTrue/setFalse action,more details later.

Now do a deployment and open preview page, click the toggle widget will change the state of

9

ConstBo object.

8. Final TweakWhen bind @BoolValue to ConstBo.out, CPT Tools will set up the object’s actions as the widget’scontextual menu. That’s why when you click the toggle widget, the action menu will show up.

It can be turned off by click actions property and uncheck all actions:

9. Make Your Widget as UserLibTo make your widget can be reused, you can save it as a graphic UserLib:

Here the User Lib’s name is toggle, and set its Category as Toggles.

Then later you can just drag this new graphic userlib object to canvas to create a new toggle widget.

10

10. Export Your Widget as a package file(.gul)After you finish your widget, you can export it as a single package file, all required files(css,javascript, images etc) are packed together. The package file’s extension name is .gul(GraphicUserLib). You can share it with others, just like share a plain file.

Right click on your widget, there will be a contextual menu showing up:

Click the Export Graphic UserLib … menu, CPT will ask for where to save the exported package file,choose a folder then click Save button. By default, CPT will generate a default package name, forexample Toggles-Toggle_20160804.gul, although you can change it, better to leave it as default. Atlast, CPT Tools will open the exported package file in File Explorer, so that you can easily find it andsend it to others.

11. Import Widget from a package file(.gul)If you want to reuse a widget shared by others, you need to get the .gul file, then in GraphicUserLibs UI box, right click and in the contextual menu click Import Graphic UserLib … menu item,then locate the package file and click Ok. During import, CPT may ask you to confirm before a file isoverwritted.

After import, you can start to use the widget.

Reuse AdapterWidget in CPT DashboardWe design AdapterWidget in a way that it is easy to be converted as CPT dashboard widget. So mostof your developing efforts on AdapterWidget will be reused. Here are some examples:

11

Develop Widget using AdapterWidgetWhen you developing a widget based on AdapterWidget and want to reuse it in CPT dashboard, youneed to keep something in mind:

• Only depends on APIs documented in the AdapterWidget Programming Interface

• Don’t depends on existence of any outside dom element, your widget should be self-contained.

12

If you beer these rules in mind, then your widget is able to be used in dashboard.

Convert AdapterWidget based UserLib into a CPTDashboard widgetAfter you finish developing your widget and it works well on CPT Graphics web page, then you canfollow these steps to make it work in CPT dashboard:

1. Save your widget as a graphic UserLib

2. Convert your widget to dashboard widget

3. Do a deployment

Now open CPT dashboard, create a new Pane, then click + button to add a widget, on the widgetselection menu, your widget will be there.

If you want to more examples for reference, you can contact us at cptsuite@gmail.com.

Manage CPT Dashboard widget converted fromAdapterWidgetAll converted dashboard widgets are stored under CPT/grweb/public/dashboard/plugins/cpt/widgetsfolder. You can open the folder in File Explorer.

13

To make it easier, CPT Tools provides a dashboard widget management UI. You can open themanagement UI, open any graphic file, click menu Tools › Dashboard Widget Management …, or youcan right click in graphic UserLib box, there is a menu item, too.

You can rename or delete a dashboard widget here, after your changes is done, you need to runFULL deployment to make your changes happen on controller side.

After deployment, the dashboard widgets on controller side will be exact the sameas your computer. That means any dashboard widget on controller that does notexist on your computer, will be removed.

AdapterWidget Programming InterfaceTo make the widget development easier, AdapterWidget isolate the inner widget from outsideenvironment, it provides the container dom element, several data service methods. On the otherside, the inner widget need to implement several callback methods, that will be called byAdapterWidget under certain condition.

Container Dom Element

this.elem

the container dom element object

AdapterWidget will create a container 'div' dom element for the inner widget. inner widget shouldlimit its operations(for example, create new dom element) within this container. The containerelement looks like this:

<div id="AdapterWidget_1_container" style="width: 92px; height: 34px; margin: 0pxauto;"></div>

AdapterWidget will take care of the container element’s position, size, zorder, visibility etc; but

14

within the container element, the inner widget has totally control.

+ You can use this.elem to access the container element object, but more convenient way is usingjQuery wrapped object $(this.elem), so that all jQuery functionalities are ready to be use, forexample:

  // get container's width  $(this.elem).width();

  // create a div element  $(this.elem).append("<div>hello</div>");

Callback Methods

requiredScripts()

Return a URL array of required javascript and css resource that are required.

This is the first callback method to be called by AdapterWidget. If the returned value is an emptyarray, undefined or null values, AdapterWidget will load nothing; otherwise, AdapterWidget willload these resource in order. In general, css resource should be loaded before javascript resource.

All resource files must be put under CPT/grweb/public/user_codes folder.

this.requiredScripts = function() {  return ["../user_codes/toggles/css/toggles.css",  "../user_codes/toggles/css/themes/toggles-light.css",  "../user_codes/toggles/toggles.js"];};

init()

Will be called after all required resources(css and javascript) loaded.

This is the right place to execute initialization tasks, for example, create widget’s dom element,initialize widget’s data, set up widget’s style, bind listener to widget’s event etc. Refer to abovetoggle widget demo for example.

update(userPropertyName)

Will be called whenever any User Property’s value changed.

This is the right place to update widget’s UI state. readData can be used to get User Property’s value.Refer to above toggle widget demo for example.

15

cleanup()

Will be called when the widget will be removed from web page.

Data Service Methods

readData(propertyName)

This method will return property’s value, no matter User Property or not.

All property’s values are returned as string, it is the inner widget’s responsibility to cast it intocorrect data type.

  // read value of User Property '@maxValue'  var maxVal = parseFloat(this.readData("@maxValue"));

writeData(userPropertyName, value)

Call this method will change an object’s slot that bound to the given userProperty with value

  // change object's slot '/Add2.in1' to 100  // '/Add2.in' is bound to User Property '@data'  this.writeData("@data", 100);

invokeAction(path, [value, [valueDataType='void']])

Call this method will invoke action addressed by path with optional value and optionalvalueDataType.

If value parameter is omitted, then its default value is null.

If valueDataType is omitted, then the framework will try to get the action’s value type based on path;if that fails, then valueDataType will be void. Possible valueDataType values: bool, int, long, float,double, sys::Buf(or str for null-terminated string), more details here.

16

  // invoke 'setTrue' action on object '/ConstBo'  this.invokeAction("/ConstBo.setTrue");

  // invoke 'set' action on object '/ConstFl'  this.invokeAction("/ConstFl.set", 80.0, 'float');

  // if action path "/ConstFl.set" is stored in a  // User Property, for example '@SetPoint', then  // you can invoke the action like this:  this.invokeAction("@SetPoint", 80.0, 'float');

  // Above code is a shortcut for:  this.invokeAction(this.readData("@SetPoint"), 80.0, 'float');

hasData(userPropertyName)

Return if the given userPropertyName has been defined.

  // will return true if '@BoolValue' defined  // otherwise, return false  this.hasData("@BoolValue")

runSqlQuery(query, dataCallback)

Run the given sql query statement on history db in controller and feed data back to dataCallbackmethod.

query should be a any valid sql query statement, for example:

  SELECT strftime("%H", dt) AS hour,  avg(data1) AS data1Avg,  avg(data2) AS data2Avg  FROM foo WHERE dt > date("now", "-1 days")  GROUP BY hour;

Above query will get average data value per hour for columns data1 and data2 of yesterday.

dataCallback function should accept a data object and the data object looks like this:

17

  data = {  columns: ['hour', 'data1Avg', 'data2Avg'], // result column labels  rows: [  ['00', '505', '780'],  ['01', '238', '1024'],  // ... ... more records  ]  }

in dataCallback function, you can decide how to render the queried result on UI.

Non-admin users can only run select sql query, that means they can not changethe data in DB; Users with admin role can run any sql query.

hasWritePerm()

Call this method to query if current account has write permission on current graphic page. Thereturn value is boolean value: true or false.

When calling invokeAction method, the framework already call this method already, and will returnstring permission denied when current account doesn’t have permission.

readNote(path, dataHandler)

This method will fetch a note’s content at given path.

dataHandler is a callback function, when a note is fetched, dataHandler will be called with the note’scontent string as the only parameter.

  // read value of User Property '@maxValue'  function dataHandler(content) {  // insert content into a DOM element, for example:  $("#testDiv").html(content);  }  // @NotePath user property stores the note's path  var path = this.readData('@NotePath');  this.readNote(path, dataHandler);

writeNote(path, content)

Call this method will save 'content' into note at 'path'.

  // change object's slot '/Add2.in1' to 100  // '/Add2.in' is bound to User Property '@data'  var path = this.readData('@NotePath');  this.writeNote(path, "this is a test note");

18

startSpinner()

Call this method to start a loading spinner, indicating that some work is under going.

stopSpinner()

Call this method to stop the spinner started by above startSpinner method.

Preloaded 3rd Javascript LibraryFollowing javascript libraries are used by CPT graphic web page, these are ready to be used withinthe inner widget, and no need to specify them in the requiredScripts method.

• jQuery

• Underscore.js

• Underscore.string.js

• Backbone.js

• Spin.js

• Bootstrap 2.32

• Moment.js

If a javascript library or css file are required by multiple widgets, AdapterWidgetwill guarantee it loaded only once.

19