Demoxi Widgets API Reference

Getting Started
Using the Services

Request Format
Response Data

State Variables
Widget Services

Close
BeginDrag
EndDrag
Open
GetProperties
SetProperties
Resize
Show
SetSkin
PlaySound
SetTitle
GetVersion

Identity Services

GetVaultAttributes
SetVaultAttributes

Getting Started

To get a quick start with Demoxi widgets, see the Demoxi Widgets Developer's Guide. It shows how to install the widget SDK and provides a detailed discussion of a fully functional Hello, World example widget.

Using the Services

Demoxi widget services use the Representational State Transfer (REST) API style
(see http://en.wikipedia.org/wiki/Representational_State_Transfer).

Request Format

All server requests are requested presented to http://localhost:4073. These are typically GET requests
(although either GET or POST will work).
The URL should be of the form:
http://localhost:4073/Widget/[Command]/[Widget]?parameter1=value1&parameter2=value2 ....

Command is the name of a widget service like Open; Widget is a widget identifier
(either a widget handle or the widget bundle name without the DW ending); and parameter is a request parameter like skin.

For example, to open a widget the Hello, World widget, use http://localhost:4073/Widget/Open/Hello. And to close the Hello, World widget, use http://localhost:4073/Widget/Close/<TMPL_VAR handle>. For a description of the state variables that are served with each widget file, see State Variables.

Response Status Codes

Typical return status codes include the following:

Status Code	Description
200 OK	Request processed successfully.
400 Bad Request	The request could not be understood by the server due to malformed syntax.
401 Unauthorized	The request requires user authentication.
500 Internal Server Error	The server encountered an unexpected condition which prevented it from fulfilling the request.

Return status codes do not cover all possible HTTP status codes that could be returned, but only those returned from the server. For example, if the request cannot reach the server, you will likely get a 503 Service Unavailable response. So, do not write your code just to handle just the documented response codes.

Response Data

JSON is used to return data from functions. JSON (JavaScript Object Notation) is a lightweight data format based on the object notation of the JavaScript language. It does not require JavaScript to read or write; it is easy to parse by any language; and libraries and tools exist in many languages to handle JSON. For a complete description of JSON and its many uses, we suggest Douglas Crockford's JSON.org (http://json.org) and JSON: The Fat-Free Alternative to XML (http://json.org/xml.html).

A typical JSON return data structure might look like this:

   jsonResult = '{ 
      "personal" : { 
         "language" : "eng" 
      } 
   }';

Accessing this JSON data structure from JavaScript is easy:

   result = eval ("(" + jsonResult + ")");
   alert (result.personal.language);

The jQuery getJSON function calls eval for you so you can access the data directly:

   $.getJSON (
      "http://localhost:4073/Widget/GetVaultAttribute/<TMPL_VAR handle>"
      ,{name: "personal.language"}
      ,function (result) {
         alert (result.personal.language);
      }
   );

State Variables

Widgets use a template mechanism to inject state variables into widget files. To access these variables within your widget HTML or JavaScript files, use the <TMPL_VAR> prefix.

For example, to access the name of the current user via userName from an HTML widget file:

   <html>
      <body>
            Welcome <TMPL_VAR userName>!
      </body>
   </html>

The following state variables are available to all widgets:

State Variable	Description
apiServer	The demoxi.net webserver URL.
handle	The widget handle.
serverAuth	The demoxi.net server authorization handle for the currently signed-in user.
userName	The currently signed-in user.

Widget Services

The widget commands allow the manipulation of widget appearance programmatically. It should be noted that since a widget's appearance is largely defined by its skin(s), making significant alterations to the appearance (e.g. changing a widget's color) is handled by resetting its skin. As such, most of the remaining commands have to do with size and visibility.

Close

Closes the specified widget.

Parameter	Required	Description
widget handle	Yes	The widget handle.

Parameter	Description
major	Major version number.
minor	Minor version number.
revision	Revision number.
build	Build number.

Error Code	Description
401 Unauthorized	The request requires user authentication.
403 Forbidden	The user has refused access to the attribute.

Parameter	Description
values	The property values.

Parameter	Required	Description
widget handle	Yes	The widget handle.
vault	No	The specific vault within the set user's identity vaults. Defaults to `wallet`.
names	Yes	The attribute names in category.name format.

Field	Description
values	The attribute values.

Demoxi Widgets API Reference

Table of Contents