DISPLIO Developer Documentation

This is the page for DISPLIO developer documentation. Here you will find information on all the available widget types, javascript functions, variables and object structures that can be used to create widgets for DISPLIO.

The documentation was updated on July 28th, 2016.

If you find any inconsistencies, bugs, old information or have any additional questions, please feel free to contact our developer team at support@displ.io

Table of Contents

1. Overview

DISPLIO widgets are built using familiar and widely available web technologies - Javascript, CSS and HTML. There are various ways to build DISPLIO widgets and this documentation will cover all of them in detail.

All widget rendering, code execution and processing is performed in the cloud - the device simply displays pre-rendered images from the cloud and sends back status and events, such as screen orientation, double tap and shake events.

The environment in which the widgets are run is the same as a web browser and is provided by WebKit.

All rendering and code execution must be performed in under 5 seconds.

The screen resolution is 176x246 and may render the widget in both portrait and landscape orientations. It is completely monochrome, so for better results it is advised to use bitmap fonts and monochrome images.

2. Creating a URL widget

In case you would like to render the widget on your server side or it's more convenient for you to simply provide a prepared HTML by using whatever serverside language you'd like, you may simply create a widget by providing an URL. When an update is required, the DISPLIO cloud will fetch the HTML from your server, render it and send it to DISPLIO. The rendering viewport is automatically adjusted for current device orientation and screen resolution. If there is Javascript code provided in the HTML it will also be executed. (See section 4. about details on Javascript).

Follow these steps in order to create an URL widget:

  1. Login to the web application. (app.getdisplio.com)
  2. Go to "My Widgets" section.
  3. Click "Create new Widget".
  4. Fill in some basic info (widget name and description).
  5. Choose "External URL" as the widget type.
  6. Enter the URL to your hosted widget.
  7. Done, when installed - DISPLIO will display contents of the provided URL.

3. Creating a hosted widget using the widget builder

You can also host the widget code on the DISPLIO cloud without using your own server. This also allows you to build widgets using the Widget Builder, using which you can visualy create the UI and simulate the look on DISPLIO.

3.1. Visual editor

Visual editor is the easiest way to build DISPLIO widgets. You can simply drag the desired UI elements (textbox, list, imageview and rectangle) and arrange the layout however you'd like and preview it in both portrait and landscape orientations. You can assign names to theses elements in the properties view which will exposes them to javascript and allow you to change their values from your code.

3.2. HTML

If you are familiar with HTML and would like more flexibility than is offered by the Visual editor, you can also use HTML and CSS to create the visual part of your widget.

Follow these steps in order to widget with Widget builder:

  1. Login to the web application. (app.getdisplio.com)
  2. Go to "My Widgets" section.
  3. Click "Create new Widget".
  4. Fill in some basic info (widget name and description).
  5. Choose "Visual Editor / Javascript" or "HTML / Javascript" as the widget type.
  6. Click done -> this will redirect you to Visual/Code editor.

4. Javascript

Javascript environment in DISPLIO is the same as in a modern web browser. It is provided by WebKit and fully implements ECMAScript 5 standard. All rendering and code execution must be performed in under 5 seconds.

4.1. Global variables

There are four global variables used to read and write data from DISPLIO.

Variable Direction Type Description
displio Input Object Various device status parameters

_id: Unique ID of the device.
name: Name of the device.
orientation: Device orientation. (See possible values bellow.)
timezone: User's time zone.
usbConnected - Is USB connected?
batteryCharged - Has the battery finished charging?
batteryCharging - Is the battery currently charging?
batteryVoltage - Battery voltage.
batteryPercentage - Percentage of current battery charge.
conf Input Object Configuration parameters provided by the user.
event Input String Event that triggered the update.

refresh - Periodical update.
doubletap - When the user double taps or shakes the device, causing a manual update.
rotate - when the user rotates the device, changing the screen orientation.
renderData Output Object Values for components created with visual editor. For example, to set value for textfield with name "test", just may use renderData.test = "hello world";

Possible Orientation values:

Value Orientation
PU Portrait Up
PD Portrait Down
LL Landscape Left
LR Landscape Right
FF Device is on its back
FB Device is with its screen down

4.2. Methods

In addition to standard javascript methods, here are some additional functions.

getJSON(url)

Requests a JSON object from external URL. This method is blocking.

var response = getJSON('http://example.com/data.json');

console.log(response.name);
console.log(response.surname);

setImageEmpty(name)

Set image view component to hide the image if it was previously set.

4.3. External libraries

It is possible to use external libraries, such as jQuery. For URL or HTML widgets simply include a script tag to an external CDN source for the library. For the Visual editor, use the "Upload asset" button to upload the .js file and it will be automatically included.

5. Publishing your widget

If you have successfully created and finished your widget and would like to allow other DISPLIO users to install it on their devices, please contact us at support@displ.io