Overview
To get access to the JavaScript Widget Control API, create a widget, note the widgetID, and embed the widget in the body of your web page. When you embed a widget on your web page, the ‘io.js’ library from ioBridge will be accessible by your web page. This allows you to customize the functionality of the ioBridge widgets.
‘io.js’ includes the following functions:
- widgetExecute – executes a widget, like a user clicking on a button
- widgetSetState – sets a state of a widget, like a user clicking an on or off button
- widgetGetState – returns the state of a widget
- widgetSetString – sends a string via a widget
- widgetGetString – returns the string that a widget is currently set to
- widgetGetValue – returns the value that a widget is currently set to
Changes
v1.3
- Updated ‘widgetSetState’ to return the widget state instead of ‘false’
v1.2
- Added ‘widgetGetState’ function
v1.1
- Fixed issues in IE6
v1
- Initial release
Embed Code
Drop the widget Embed Code into your website and the ioBridge JavaScript Library is appended to the header of your page and gives you access to special ioBridge commands to control your widgets.
Example Widget Embed Code
<script type="text/javascript">
document.write(unescape("%3Cscript src='" + "http://www.iobridge.com/widgets/io.js?Q6Vs3RepsH6I' type='text/javascript'%3E%3C/script%3E"));
</script>
Hide Widget Code
If you don’t need to see the actual widget, you can hide it using the following commands. It’s recommend to embed hidden widgets near or right befire the </body> html tag.
<div id="ioWidgets" style="display:none;">
<script type="text/javascript">
document.write(unescape("%3Cscript src='" + "http://www.iobridge.com/widgets/io.js?Q6Vs3RepsH6I' type='text/javascript'%3E%3C/script%3E"));
</script>
</div>
widgetID
The widgetID is the string at the end of the widget code:
http://www.iobridge.com/widgets/io.js?Q6Vs3RepsH6I
‘Q6Vs3RepsH6I’ is the widgetID for the above widget.
JavaScript Commands
widgetExecute
Use widgetExecute on widgets that have one, fixed action. For example, if you created a fixed position servo widget that when normally clicked it sets a servo to a fixed position. Running widgetExecute from JavaScript allows JavaScript to execute the widget. The widget reacts just like if a user clicked on the widget.
widgetExecute('widgetID');
widgetSetState
If the widget has two states, like On and Off buttons on an X10 widget or a toggle button, use the widsetSetState JavaScript command to control the widget’s state. widsetSetState also returns the widget’s current state.
On State
The ‘on’ state corresponds to a logic level of high or ‘1’.
widgetSetState('widgetID', 1);
Off State
The ‘off’ state corresponds to a logic level of low or ‘0’.
widgetSetState('widgetID', 0);
widgetGetState
If the widget has two states, like On and Off buttons on an X10 widget or a switch, use the widsetGetState JavaScript command to get the widget’s current state. This function returns a ‘1’ for the on state and a ‘0’ for the off state.
var widget_state = widgetGetState('widgetID');
widgetSetString
Variable serial and servo widgets need to use widgetSetString to send data to your module.
widgetSetString('widgetID', 'This is my serial message');
widgetGetString
If you have a variable message widget, you can get the current string by using widgetGetString from JavaScript. Use for variable servo position widgets and serial messages.
var widget_string = widgetGetString('widgetID');
widgetGetValue
If you have a widget that reads in the value of a digital input or analog input, you can get the that value by using widgetGetValue from JavaScript.
var widget_value = widgetGetValue('widgetID');
Special Characters
If you want to send special characters and bytes with widgetSetString, use the URL encoded characters.
For example, if you wanted to break a message into two lines with a carriage and linefeed, issue this JavaScript command:
widgetSetString('Q6Vs3RepsH6I', 'This is line 1.%0D%0AThis is line 2.');
The result will be:
This is line 1. This is line 2.
Common URL Codes
- %0D = carriage return
- %0A = linefeed
Here is a table that lists all of the URL codes: URL Codes
Resources
- iTurn – Servo Widget Control Example Application
- JavaScript Widget Examples on GitHub
