9/22/2010 2.

Widget Developer Guide | Convergen…

Search this site: Search Hello vmurthy3 Logout

About Us Courses Resources Projects Competition

Home » Projects
Projects View Revisions
GIS Initiative (GRGI)
OpenFlow (OFLOW) 2. Widget Developer Guide
WhereAmI Outline
A. Widget Overview
B. Widget UI Guidelines
C. Widget Developer Resources
--- 1. Styling/Themes
Manage --- 2. Key Handling/Navigation
Freelinks --- 3. UI Elements Library
D. Widget Management and Deployment
My account --- 1. Widget Deployment Workflow
--- 2. Widget List Management
Create content E. Sample Widgets
Log out
B. Widget Overview

[outline]

B. Widget UI Guidelines
This section offers general UI guidelines for Widget Developers. The section is broken into two separate parts, design
considerations and user interaction. Design consideration focus on the visual aspect of widgets and user interaction focus
on key handling navigation and types of data. The guidelines are here to help Widget Developers to create user friendly
widgets.

1. Design Consideration
Interlacing
TV display uses interlacing scan where each frame is made up of two frames. Horizontal lines can flicker or vibrate if they
are too thin. Therefore, make sure to create thick horizontal lines.

Color
Colors are much more saturated on TV screen than on computer screen. Make sure to use CMYK colors. Extremely
vibrant or pale colors can cause problem.

Font
Text should readable from a larger distance (10 feet). Avoid serif font and stick with sans serif or slab serif font. Font size
should be no less than 24pt. Avoid red text. Use anti-aliasing for readability.

Navigation
Avoid scrolling when possible. Divide contents up if it requires scrolling and make use of panels.

2. User Interaction

http://www.cip.gatech.edu/node/1387#d1 1/9
9/22/2010 2. Widget Developer Guide | Convergen…
Key Handlings/Navigation
Navigation on TV demands less attention than it is on Keyboard. User should receive active feedback when key is used.

Types of Data
Data should clear and precise. Users should be able to read it quickly by glances without losing focus in main program.

3. General Resources
• TV Without Borders - A web site dedicated to open standards for interactive TV.
• BBC Future Media Standards and Guidelines
• Interaction Design Principles for Interactive Television - Karyn Lu

[outline]

C. Widget Developer Resources

1. Styling/Themes
Currently, the platform uses custom themes from Theme Roller of JQuery UI website as themes. The components
downloaded from Theme Roller are UI Core and Widgets (JQuery UI Controls). Interaction and Effects components are
omitted from the themes. For more information please visit JQuery UI. The custom themes are stored under the jquery
folder of the platform directory. Each theme is divided into separate folder. For example, the ui-darkness theme is under
./jquery/ui-dark ness. In theory, both the OUX developer and widget developer can use these themes. However, if widget
developers want their widget to match the theme used by OUX, then they have an option to do so. The following section will
explain how widgets can get themes from OUX.

Default Widget functions from widget_methods.js

• getOUXTheme() - get OUX theme for the widget
• registerThemeWidget() - register self (the widget) to the list of widgets that are using OUX theme. This function calls the
updateThemeWidgetList() function in the OUX.
• updateOUXTheme() - update OUX theme in the widget

Widget developers have a choice of receiving OUX theme updates by registering their widgets to the platform. Here is how
widget developers can register their widgets.

1. Make sure JQuery links in the widget’s html header are defined as the following:

. <!-- JQUERY FILES!-->

. <link class="jquery" id="customCSS" type="text/css" rel="stylesheet" href="./../../jquery/ui-lefrog/css/custom-theme/jquery-ui-1.8.2.cu
. <script class="jquery" id="minJS" type="text/javascript" src="./../../jquery/ui-lefrog/js/jquery-1.4.2.min.js"></script>
. <script class="jquery" id="uiMinJS" type="text/javascript" src="./../../jquery/ui-lefrog/js/jquery-ui-1.8.2.custom.min.js"></script>

2. Include widget_methods.js.

3. Call getOUXTheme() function to register OUX theme updates.

2. Key Handling/Navigation

Overview

Key Handling, or how users navigate through widgets, is a very important part of the platform. This is one of the major
differences between web development and widget development. Instead of having a pointing object such as a mouse that
can move through the screen, users are limited to using remote control as their primary input device. This limitation has
made key handling in the platform rather strict.

http://www.cip.gatech.edu/node/1387#d1 2/9
9/22/2010 2. Widget Developer Guide | Convergen…

Key Handling Layers

There are three layers of key handling. First, the platform will provide the first layer key handling, second layer is provided
by UI elements, and the last layer is provided by widget developers. Below are some major points regarding key handling in
the platform.

• If the widget developer uses the provided library for creating interactive html elements, then the platform takes care of the
navigation completely.
• If the widget developer wishes to override/customize this default key-handling then she has to register callback functions
with the Platform for each of the elements and the related key presses.

Functions for Widget Developers

registerKeyPressCallbacks({element-id}, {key_label}, {reference_to_callback_function})

If the there is no function registered for the element, then the default handling of the Platform takes over.

• If the widget developer creates interactive html elements outside of the supported library and wants navigation to be taken
care of, for these html elements, then, she has to attach a class (navigationClass) to these elements.
• Callback functions will have to be registered (as described above) for custom html elements if the widget developer wants
to perform key-handling for custom html-elements.
• Callback functions must return true if the focus is still in the widget else it should return false

The widget developer has to implement 3 functions that are necessary for the Platform to handle key navigation -

getActiveElementId() implemented by the Widget Developer to return the id of the element that currently has focus.

setActiveElementId(_activeElementId) implemented by the Widget Developer to set the id of the element that currently has
focus

getActiveClass() implemented by the Widget Developer to return the class that will be associated with the active element.

var global_activeElementId = "{id of element that has focus}"; should be set when the widget loads

The above snippets of code will be present in the Javascript file as a scaffold.
Also, If the widget developer is not implementing any key navigation, she needs to set the first element that should be in
focus when the widget loads and the Platform will be able to keep track of the active element subsequently

Remote Control to Keyboard Mapping

When testing on the computer, the remote control cannot be used. In order to emulate as closely to the STB environment
as possible, the Remote Control keys are mapped on the Keyboard. For example, the [RETURN] key in Remote Control is
mapped to 'g' on the Keyboard.

http://www.cip.gatech.edu/node/1387#d1 3/9
9/22/2010 2. Widget Developer Guide | Convergen…

3. UI Elements Library
UI Elements Library is a set of pre-built elements provided by the platform for Widget Developers. To use these UI
Elements, Widget Developers will have to include specific UI Element Javascripts (JS files). These Elements are designed
to provide Widget Developer quick and simple solution to push their widgets on to the TV. They can also serve as
examples for Widget Developers as well.

To use any of the following UI Elements, please make sure to include the UI Elements Library file:
PLATFORM_UIElementsLibrary.js

Container Elements

Container Elements are panel containers which are packaged with pre-built key handling and widget views. To use these
container elements, the Widget Developer will need to ensure the HTML body have IDs and Classes specific to each
container element and provide an array of data to be used by the containers. The array of data is specific to each container
element. It is used to generate panels that will be rendered by the browser.

Tabs || PLATFORM_UIElementsTabPanels.js

Tabs Container is based on JQuery UI’s Tabs. To use Tabs, an array which contains information of id, html, css of
individual panels is required. Both Key Handling and Views are supported.

Pre-built Functions

1. Key Handling - Left

2. Views – Regular, Small, Ticker, and Icon.

HTML Body

. <body>
. <div id='view'>
. <div id='tabs' class='panel_container'></div>
. </div>

http://www.cip.gatech.edu/node/1387#d1 4/9
9/22/2010 2. Widget Developer Guide | Convergen…
. </body>

Example Panels Array

. var panels = new Array(

. {id: 'panel_today', name: 'Today'},
. {id: 'panel_forecast', name: 'Forecast'},
. {id: 'panel_location', name: 'Location'}
. );

Public Methods

createTabs(panels)
Creates a set of jquery UI tabs from a specified array. Array has id, html, css of the panels

getSelectedTab()
return the index of the currently selected tab

switchToTab(n)
switch to the tab whose index is passed as a parameter (start index:1)

tabSelectLEFT()
selects the tab to the left of the current tab

tabSelectRIGHT()
selects the tab to the right of the current tab

Flip Panels || PLATFORM_UIElem entsFlipPanels.js

Flip Panels Container is designed so that users can ‘flip’ (like flipping through TV channels) panels using the right and left
key on the remote. Both Key Handling and Views are supported.

Pre-built Functions

Key Handling - Left

Views – Regular, Small, Ticker, and Icon.

HTML Body

. <body>
. <div id='view'>
. <div id='flippanels' class='panel_container'></div>
. </div>
. </body>

Public Methods

createFlipPanels(panels)
Creates a set of Flip panels from a specified array. Array has id, html, css of the panels

getCurrentPanelIndex()
returns the index of the current active pane

flipToPanel(index)
Show the panel with the index passed as parameter

Scroll Panels || PLATFORM_UIElem entsScrollPanels.js

http://www.cip.gatech.edu/node/1387#d1 5/9
9/22/2010 2. Widget Developer Guide | Convergen…
Scroll Panels allow the users to scroll through a list of panels and to select specific panel to display. Both Key Handling
and Views are supported.

Pre-built Functions

Key Handling - Left

Views – Regular, Small, Ticker, and Icon.

HTML Body

. <body>
. <div id='view'>
. <div id='panel_list'></div>
. <div id='panel_container'></div>
. </div>
. </body>

Public Methods

createScrollPanels(panels)
Creates scroll panels from a specified array. Array has id, name, html of the panels

switchScrollPanels(index)
switch to the tab whose index is passed as a parameter

updateScrollPanels(index, html)
update scroll panel whose index is passed as parameter with html

showScrollPanelList()
show scroll panel list

Other UI Elements

An additional set of UI Elements are also provided by the platform to support Key Handlings. To use these UI Elements,
the Widget Developer will need to simply include the JS files specific to each. There are no additional requirements. Once
the JS files are included, then the developers can create these elements by calling the methods and passing in a set of
required parameters.

Text Box

createTextBoxElement(name, id, maxlength, value, size, cssClassString, appendElementId)

Creates a text box element from the given parameters - text entry and number input is handled

iPhone type checkboxes

http://www.cip.gatech.edu/node/1387#d1 6/9
9/22/2010 2. Widget Developer Guide | Convergen…

createSlidingCheckboxes(array)
Creates a set of checkboxes from a specified array

List of radio buttons or checkboxes

createInputListItems(array, appendTo)
Creates list items with a radio button or checkbox input element. OK triggers the change event

Button

createButton(button)
Creates a button - does not work if its a form submit button. OK triggers the click event

Other w idget related Scaffolding functions

function channelChangeEventHandler(index) - Called with the index of the current channel if the widget subscribes to the
“channel change event”

[outline]

D. Widget Management and Deployment

1. Widget Deployment Workflow

Basic Information

To begin a project, a team will need both a project key and a project name.
Email us a Team Name and we will send you back all your details i.e. password and project key. We will also provide you
with a folder with the Platform Libraries code and example widgets.

To access the above mentioned folders you need to use any standard FTP/SCP clients - WinSCP or PuTTy (If you are
running Linux or OSX, you can use standard command line tools)

1. Log on to App Server (www.moto-vm2.cip.gatech.edu) using one of the scp/ftp clients

2. The Platform Libraries and the sample widgets can be found, under the path /home/[Team Name]/files/[Project Key]/ on the
server
3. Example widgets and your widget will reside at home/[Team Name]/files/[Project Key]/widgets/

The project key will define the context root (defines the relative path to an instance of the widget platform on the server) for
the Team’s development environment.

Example: http://moto-vm2.cip.gatech.edu:8080/[ProjectKey]/OUX/OUX1/OUX1.html

The Team will use one account – “TeamName” on the moto-vm2.cip.gatech.edu server. This account will be “jailed”, which
means their access is limited to the home folder.

Deployment Script

Steps for widget developer to update code on the App Server:

1. Download the widgets and xml folders (both of them can be under the "/home/[Team Name]/files/[Project Key]/" folder) on
your local machine.
2. Make necessary changes to your local copy.
3. Copy the modified files (using the scp/ftp client)
4. The developer will also need to copy a file named "deploy"(a blank file) which is used to update the application.

Please note, every time code is modified, the widget developer needs follow the above mentioned steps

The updates can then be views from the team's defined browser URL:

Example: http://moto-vm2.cip.gatech.edu:8080/{ProjectKey}/OUX/OUX1/OUX1.html

Displaying on STB

For displaying it on the STB, the Team1 will login to –

http://{TV-Server}/widget_submit.html and select the options

Enter Widget Platform User - (Each STB has the name of the STB user – Widget Platform User 1, 2...)

http://www.cip.gatech.edu/node/1387#d1 7/9
9/22/2010 2. Widget Developer Guide | Convergen…
Enter OUX – Enter which OUX to be displayed

Enter Project Key – Enter your project key

Click Load.

Then go and physically restart the box by pulling out the plug behind it and plugging it in again

2. Widgets List Management

In the set of files that we give you, under the folder called “xml” is where you would find the set of xml files that dictate
which widgets to be displayed. The ‘xml’ folder is structured as the following:

‘xml’ Folder Directory Structure

. /xml
. UserMapping.xml
. /users
. configFile1.xml
. configFile2.xml
. configFile3.xml

UserMapping.xml File

The UserMapping.xml file consists of the mapping of unique ids and widget configuration files. The xml file is structured as
the following:

. <userList>
. <user>
. <id>user1</id>
. <configFile>configFile1.xml</configFile>
. </user>
.
. <user>
. <id>user2</id>
. <configFile>configFile2.xml</configFile>
. </user>
. </userList>

Configuration File Example

. <?xml version="1.0" encoding="UTF-8" standalone="no"?>

. <user>
. <widgetList> <!-- List of Widgets -->
. <widget>
. <name>weather</name> <!-- Name of Widget -->
. <title>Weather</title> <!-- Title to be displayed for Widget -->
. <description>Shows the weather of a given zipcode</description> <!-- Description about the widget -->
. <icon>weather.png</icon> <!-- Image for Icon view -->
. <selected>true</selected> <!-- Determine if Widget is selected for use -->
. <version>1</version> <!-- Version of Widget -->
. </widget>
. </widgetList>
.
.
. <globalvalues> <!-- Global values -->
. <zipcode>94085</zipcode> <!-- User Location -->
. <email>[email protected]</email> <!-- User Email (optional) -->
. </globalvalues>
. </user>

Select and Load Widgets on OUX1

To load the widgets on your browser, the url on the browser should be –

http://moto-vm2.cip.gatech.edu:8080/[ProjectKey]/OUX/OUX1/OUX1.html?id=n

The ‘n’ corresponds to the value of the ‘id’ described in the UserMapping.xml file. By default its value is 1. If you set it to
any string, it will pick up the corresponding id from the above defined UserMapping.xml file. For example if you pass id=2,
then the list of widgets in the configFile2.xml will be displayed.

When the widget developer wants to load this set of widgets on the STB, they will need to map the corresponding id to the
mac-address of the STB. All the mac-addresses of STBs will be available by default in the User Mapping xml file. The
widget developers can modify config xml file to use, by changing the content inside the tags.

So when loading the widgets on the STB, all the widgets listed in the xml config file will be displayed

[outline]

These links are accessible only from GeorgiaTech Network

E. Sample Widgets
Widget
Descriptions Features UI Elements
Name
Flip Panels
http://www.cip.gatech.edu/node/1387#d1 8/9
9/22/2010 2. Widget Developer Guide | Convergen…
Flip Panels
Example widget with Panels showing RSS
[OUX1] Flip Panels
feeds
[OUX2]
Gopher
Example widget with the Gopher
[OUX1] Gopher
navigation
[OUX2]
GT Video
[OUX1] Shows Videos from GT Courses Has the ability to scroll within the widget Tabs
[OUX2]
News
Opinion Implements Sliders and horizontal radio Panels implemented by
A Survey widget
[OUX1] buttons using jQuery the developer herself
[OUX2]
OUX
Implements the Sliding Checkbox Element
Settings Settings & Preferences Widget Tabs
for selecting widgets
Widget
Program
Profile Shows the Current Program Name and
Uses 2 methods of the CSF API Tabs
[OUX1] Summary
[OUX2]
Scroll
panels
Shows RSS Feeds Has the ability to scroll within the widget Scroll Panel Container
[OUX1]
[OUX2]
SimpleBlend
Shows pictures from Flickr based on the Now When an image thumbnail in the widget is
[OUX1] None
Playing infomation from the CSF clicked it takes up the entire screen
[OUX2]
Skip To
Class Makes use of a backend service developed
Shows the time left to reach class None
[OUX1] by the Widget developer
[OUX2]
Weather
Has the ability to change the location and
[OUX1] Shows the Weather information Tabs
update Global Values
[OUX2]

[outline]

Printer-friendly version

© 2010 Georgia Institute of Technology

http://www.cip.gatech.edu/node/1387#d1 9/9