Web Based Gadget User Interface

Technical Specifications

(Last update: May 27th, 2013)

TABLE OF CONTENTS

Introduction ...................................................................................................................................................................1

Platform and Accessibility ..............................................................................................................................................2

Project Structure ............................................................................................................................................................2

gadget/data ...............................................................................................................................................................2

gadget/dnd ................................................................................................................................................................3

gadget/nls..................................................................................................................................................................4

gadget/resources .......................................................................................................................................................5

gadget/widget ...........................................................................................................................................................5

gadget/App.js.............................................................................................................................................................8

gAppEmulator.php .....................................................................................................................................................8

How to add a new Type of Gadget to the Application .....................................................................................................9

INTRODUCTION

This document contains relevant information about the implementation of the Web Gadget Based User Interface
Project. It shows the project structure in detail in order to allow the reader to understand how it is organized and how it
can be extended.

The document Web Gadget Based User Interface Project, as requested by client, was taken as functional requirements
for the implementation. Functionality was tested against the specifications given in the mentioned document and the
idea of subsequent extensions was always taken into consideration so the structure and current code is as reusable and
easily extensible as possible.
PLATFORM AND ACCESSIBILITY

Dojo version: Dojo Toolkit v1.9

Dojo Theme: claro

Accessibility: Mouse and Keyboard

PROJECT STRUCTURE

A new module named gadget was created at the same path dojo, dijit and dojox usually resides. This module holds the
js, css and images of the newly created dojo components and widgets. Currently, instead of using a local copy of the
dojo library, the gadget application uses the library hosted at Google CDN, so at that path (js) only application related
files are stored. Loading dojo from a different server slightly speeds up the application and at the same time it saves
server resources for other important tasks.

dojoconfig.js file contains the dojo configuration for the app. The gadget module is registered there.

gadget/data

Inside the gadget/data package can be found data layer related classes.

At this time only transformers will be found there. A transformer class is responsible of parsing the data in a format A
and transforms it into a format B and vice versa, so the data in format B can be reversed to the format A as well. This is
used in several fields of the property sheets, in the case that a field understands its value(s) in a format that differs from
the format in which it is sent by the server.

For example: the field where the col/row quantity is specified has two number spinners; the format expected by that
field is:
 {
number1: 9,
number2: 10
}

but the value that comes from the server is:

{
n: 9,
dist: 10
}

Why don’t make the field widget expect the data in the format the server sends it?

Undoubtedly it would be a solution, but field widgets were created thinking that they could be used in another
scenario. With this method, the above mentioned field widget could be perfectly used to handle any other property
that requires two numbers, not necessarily related to the col/row property. The only thing a programmer has to do is to
implement the corresponding transformer. This favors code reuse by avoiding the creation of different widgets with
identical behavior for properties of the same nature.

The class gadget/data/transformers/_AbstractDataTransformer defines the interface that transformers have to

implement.

Following a list of transformers:

 gadget/data/transformers/AOpTransformer – aOpObj

 gadget/data/transformers/DOpTransformer - dOpObj

 gadget/data/transformers/DelayTransformer - dlyObj

 gadget/data/transformers/PageColRowTransformer – n2Obj

 gadget/data/transformers/RefreshTransformer - refreshObj

gadget/dnd

The package gadget/dnd contains three .js files that define the following three classes. All of them related to drag and
drop:

 GadgetSource: extends dojo/dnd/Source class and overrides the necessary methods to provide the previous
grid based drag and drop behavior. It is not used now. New drag and drop is implemented in the class
GadgetMovable.
 GadgetMover: extends dojo/dnd/Mover. This extension corrects an issue on Google Chrome for Mac that was
causing an undesired behavior when right clicking a gadget.
 GadgetMovable: extends dojo/dnd/move and GadgetMover. Overrides necessary methods to achieve the
new drag and drop behavior.
gadget/nls

This is the internationalization package. It contains a folder for each supported language.

Inside the folders a file named gadget.js contains the translation of all strings used in the UI to the language defined by
the locale (name of the folder). A common gadget.js file looks like follows:

The gadget.js file for the default language (English) is located at the root of gadget/nls. The application currently
supports English (default), Spanish and French. By editing the content of gadget/nls is quite easy to modify the texts
that are shown in the UI and also to add new translations to the project.

How to change between existing translations

By changing the dojo.locale property. If another language must be set by default, the locale property of the dojoConfig
object must be changed. Edit the file js/gadget/dojoconfig.js.
gadget/resources

Resources package is where all the images and css files reside. Each css file corresponds to a widget and gadget-all.css
imports all the css files.

gadget/widget

This package contains widget related mixin classes, and the implementation of the different widgets.
Mixin Classes

A mixin, in this case, can be viewed as an interface with implemented methods. When a class that represents a widget
includes a mixin, the class implements the interface and includes, rather than inherits, all the mixin's attributes (fields,
properties) and methods. These mixin classes are extended by the widgets, they’re not instantiated directly.

 gadget/widget/_SingleFieldMixin: Basic functionality for fields that have a single value and a label.
 gadget/widget/_PropertySheetContainerMixin: Widgets that have a property sheet. This class implements the
logic for the show/save functionality. This mixin is used by all gadgets and the page widget.
 gadget/widget/_CanvasGridMixin: Implements a lot of functionality that corresponds to the canvas widget
that allows adding items organized in different layouts and also to drag & drop the items over the canvas. It is
responsible for the positioning of items in the canvas too. The page widget uses this mixin.
 gadget/widget/_CanvasGridItemMixin: This mixin implements the basic functionality for the items of a
_CanvasGridMixin. The gadget widgets use this mixin.

Dialog Widgets

These widgets are used all over the application for showing messages and confirmations.

 gadget/widget/MessageDialog: this widget extends dijit/Dialog. It is a dialog with an icon, a text and optional
action buttons.
  gadget/widget/WaitDialog: This widget extends MessageDialog. Basically it shows a text and a cancel button.

 gadget/widget/GadgetTypeDialog: This widget extends dijit/Dialog and allows to select a gadget type. It is
shown before launching the property sheet widget when creating a new gadget.

Field Widgets

All field widgets are used internally by the property sheet widgets to build the corresponding interface for the different
types of property sheets.

 gadget/widget/BooleanPicker: this widget allows the user to select on/off values using a switch like control.

 gadget/widget/ColorPicker: This widget allows the user to select a color and save it into a textbox. The user
clicks in the arrow and a popup with a dijit/ColorPalette is shown to select the desired color. The input will
keep the “name” of the selected color and shows a little box filled with the color.

 gadget/widget/BooleanField: This widget contains a label and a BooleanPicker.

 gadget/widget/ColorField: Contains a label and a ColorPicker.

 gadget/widget/DelayField: Two pairs of label and dijit/form/NumberSpinner.

 gadget/widget/FlagField: Contains a label and a dijit/form/CheckBox for each flag.

 gadget/widget/NumberField: A label and a dijit/form/NumberSpinner.

 gadget/widget/PixelField: A label and a dijit/form/NumberSpinner that allows only integer numbers.
  gadget/widget/RefreshField: Contains a label, a dijit/form/NumberSpinner and a dijit/form/Select.

 gadget/widget/SelectField: A label and a dijit/form/Select.

 gadget/widget/SourceField: A label and a dijit/form/FilteringSelect. Allows specifying a filter value to exclude
items from the available choices.
 gadget/widget/TextField: A label and a dijit/form/ValidationTextBox.
 gadget/widget/UniqueLabelField: This widget extends TextField and adds the functionality of validating against
all existing gadget names to avoid the selection of two gadgets with the same name. For using this type of field
a new ulblObj object was added to the property sheet configuration.
 gadget/widget/TwoNumberField: Contains two PixelField widgets.
 gadget/widget/TwoSourceAnaField: Two SourceField widgets and one SelectField to select an analog operator.
 gadget/widget/TwoSourceDigiField: Two SourceField widgets and one SelectField to select a digital operator.
 gadget/widget/UrlField: Contains a label and a dijit/form/ValidationTextBox. Text box validates that the Url
correctly specify a path to an image.

Property Sheet Widget

 gadget/widget/PropertySheet: This widget extends dijit/Dialog and it’s capable of building the corresponding
interface from a property sheet configuration using only the available fields and a fieldType/fieldClass map. So
with the map and the configuration provided in propSheets.json the widget can instantiate and startup the
corresponding field widgets and adds them to the dialog. This widget uses transformers as needed and also
provides single set/get values and validation methods. Each gadget has a property sheet instance that is
created at gadget startup. The property sheet is destroyed when the gadget is removed from the page.

Page, Gadget Widgets and the App class.

 gadget/widget/Gadget: This widget uses _CanvasGridItemMixin for allowing the gadget to be added to the
page. Also uses the _PropertySheetContainerMixin and adds other functionality like contextual menu and
tooltip.
 gadget/widget/Page: This is an important widget in the application, it uses _CanvasGridMixin and
_PropertySheetContainerMixin to allow a canvas like interface. It has a property sheet dialog for editing its
properties. This widget is responsible of providing the interfaces required for creating and deleting gadgets.
Also has a method to manage each type of message that the gadgetEmulator understands.

gadget/App.js

This is a class that is responsible of interacting with the server. It has public methods to request data from the server
and implements global error handling. Also initializes and creates the page widget instance and all the gadget instances
described in wDescrip.json, startup all those widgets and add the page widget into the document body. The App class
also processes the propSheet.json and gCompat.json files, providing the page with the necessary information for
creating and editing gadgets.

gAppEmulator.php
It is a Php script that emulates the server. Manages and keeps up to date the gDescrip.json and wDescrip.json files with
the information about the gadgets and the widgets. It responds to every request according to the specifications.

HOW TO ADD A NEW TYPE OF GADGET TO THE APPLICATION

Currently the application has four types of gadgets: AnaVar, DigiVar, AnaOp and DigiOp. Also provides various field
types that are sufficient to represent those gadget’s properties:

 txtObj: Text field

 ulblObj: Text field for gadget names that validates that each gadget have an unique name.

 boolObj: Selector for on/off or true/false values.

 numObj: Number field

 srcObj: Selector for other gadgets excluding the gadget that has been edited.

 aOpObj: Field composed by two srcObj and one selectObj, with logic specific for AnaOp gadgets.

 dOpObj: Field composed by two srcObj and one selectObj with logic specific for DigiOp gadgets.

 refreshObj: Field to specify how long to refresh something

 dlyObj: Field to specify on/off delays

 colorObj: Field to select a color using a color picker

 urlObj: Text field that validates an url, any file extensions could be specified to validate to.

 pxObj: Number field that only allows integers

 n2Obj: Field composed by two pxObj

 selectObj: Selector for a static list of choices.

To add a new gadget type first you have to add the new type in the file gCompat.json where all the available types are
defined.
Suppose we want to add a new gadget type called MonoVar. We add the following to gCompat.json

"MonoVar":{
"gTy": 29,
"wTy": "MonoVar",
"lbl": "Mono Variable",
"gSrc":[28,27]
}

Then we specify the properties of this gadget in propSheets.json

"psMonoVar":{
"label":"Mono Variable Properties",
"0":{
"label":"Gadget name",
"wType":"ulblObj"
},
"1":{
"label":"Startup value",
"wType":"boolObj"
},
"2":{
"label":"Source gadget",
"filter":"DigiVar",
"wType":"srcObj"
},
"3":{
"label":"Refresh from source every",
"wType":"refreshObj"
},
"4":{
"label":["Disabled","Hidden"],
"wType":"flgObj"
}
}

And finally we create a file named MonoVar.json with the default values for its properties.
 {
"gTy": 29,
"img":"MonoVar",
"0": "MonoVar.0",
"1": 0,
"2": 0,
"3": {
"n": 0,
"itvl": 0
},
"4": 0
}

The img property in the default properties is a css class name that will provide the image for this gadget. Currently the
images of the four supported gadgets are stored in the same file located at /gadget/resources/images/gadgets.PNG.

This is a common practice in web development because downloading all images in one single HTTP request is fastest
than downloading them from different URLs. This is considerably noticed when the number of images increases. So, we
encourage you to edit gadgets.PNG, add the new images at the right and properly update the css. The css classes for
each gadget are stored in /gadget/resources/Gadget.css.

.DigiVar{
background-image: url('images/gadgets.PNG');
background-position: 128px;
}

.DigiOp{
background-image: url('images/gadgets.PNG');
background-position: 96px;
}

.AnaVar{
background-image: url('images/gadgets.PNG');
background-position: 64px;
}

.AnaOp{
background-image: url('images/gadgets.PNG');
background-position: 32px;
}

As can be noticed all gadgets uses the same image but different background position.

To add an image for the newly created MonoVar we need to create an image of 32 x 32 pixels of size, insert it into the
images.PNG file and then add a css class like in the example correctly positioning the background image.
The css class for the MonoVar gadget may look like this.

.MonoVar{
background-image: url('images/gadgets.PNG');
background-position: 160px;
}

Don’t forget to add the value MonoVar to the property img in MonoVar.json for the MonoVar default properties values.

And that’s it! The new MonoVar gadget type is added to the application and ready to use.

Note: If the new gadget you want to add has a property which requires a field type that is not in the list of the currently
available field types, then you need to create it. That is not as trivial as creating a new gadget type that doesn’t need it
because it involves writing code for a new dojo widget but it can be easily done as well.