Recent versions of Purple Robot (1.0.34+) implement a new PurpleRobot.updateWidget JavaScript endpoint that dispatches widget requests to Purple Notifier instead of the locally-implemented widgets (which will be deprecated as projects allow). This endpoint takes a JavaScript object, translates the keys into extras on an intent and fires the intent to Purple Notifier.

This document lists the available widgets and the fields each widget supports.

Identifiers & Actions

Each widget provided by Purple Notifier may have an identifier associated with it when the user adds the widget to the homescreen. The widgets may be configured with one widget per identifier, or multiple different widgets sharing a single identifier. In the JS object passed to PurpleRobot.updateWidget, the identifier key is always required.

Similarly, Purple Notifier can accept action keys that contain a script to execute when a widget is tapped. (Widgets with multiple targets can support multiple actions. See documentation below.) Purple Notifier does not execute the associated script, instead it broadcasts it back to Purple Robot (via an intent, containing an extra widget_action set to the string tap), which runs the script within its local JavaScript context.

Image, Title & Message Widget

This widget re-implements the basic Purple Robot widget that includes a title, descriptive message, and an icon.

Script example:

var params = {};
params['identifier'] = 'foobar';
params['title'] = 'Title Goes Here';
params['message'] = 'Longer message can go here.';
params['image'] = 'http://url.to/image/goes/here';
params['action'] = 'PurpleRobot.playDefaultTone();';

PurpleRobot.updateWidget(params);

Title & Message Widget

This widget re-implements the basic text-only Purple Robot widget that includes a title and descriptive message.

Script example:

var params = {};
params['identifier'] = 'foobar';
params['title'] = 'Title Goes Here';
params['message'] = 'Longer message can go here.';
params['action'] = 'PurpleRobot.playDefaultTone();';

PurpleRobot.updateWidget(params);

Title Only Widget

This widget implements a widget that includes only a title.

Script example:

var params = {};
params['identifier'] = 'foobar';
params['title'] = 'Title Goes Here';
params['action'] = 'PurpleRobot.playDefaultTone();';

PurpleRobot.updateWidget(params);

Image Only Widget

This widget implements a widget that includes only an image.

Script example:

var params = {};
params['identifier'] = 'foobar';
params['image'] = 'http://url.to/image/goes/here';
params['action'] = 'PurpleRobot.playDefaultTone();';

PurpleRobot.updateWidget(params);

Badge, Image, Title & Message Widget

This widget a widget that includes a title, descriptive message, and an icon. This widget allows text to be overlaid on the icon.

Script example:

var params = {};
params['identifier'] = 'foobar';
params['title'] = 'Title Goes Here';
params['message'] = 'Longer message can go here.';
params['image'] = 'http://url.to/image/goes/here';
params['badge'] = '123';
params['color'] = '#abceef';
params['fill'] = 0.75; // Fill ratio: 1.0 grows the text to fill the image dimensions.
params['action'] = 'PurpleRobot.playDefaultTone();';

PurpleRobot.updateWidget(params);

Badge, Image & Title Widget

This widget a widget that includes a title and an icon. This widget allows text to be overlaid on the icon.

Script example:

var params = {};
params['identifier'] = 'foobar';
params['title'] = 'Title Goes Here';
params['image'] = 'http://url.to/image/goes/here';
params['badge'] = '123';
params['color'] = '#abceef';
params['fill'] = 0.75; // Fill ratio: 1.0 grows the text to fill the image dimensions.
params['action'] = 'PurpleRobot.playDefaultTone();';

PurpleRobot.updateWidget(params);

Four Buttons Widget

This widget contains four images that may be tapped to run four different actions.

Script example:

var params = {};
params['identifier'] = 'foobar';
params['image'] = 'http://url.to/first/image/goes/here';
params['image_two'] = 'http://url.to/second/image/goes/here';
params['image_three'] = 'http://url.to/third/image/goes/here';
params['image_four'] = 'http://url.to/fourth/image/goes/here';
params['action_one'] = 'PurpleRobot.playDefaultTone();';
params['action_two'] = 'PurpleRobot.playDefaultTone();';
params['action_three'] = 'PurpleRobot.playDefaultTone();';
params['action_four'] = 'PurpleRobot.playDefaultTone();';

PurpleRobot.updateWidget(params);

Five Buttons Widget

This widget contains five images that may be tapped to run four different actions.

Script example:

var params = {};
params['identifier'] = 'foobar';
params['image'] = 'http://url.to/first/image/goes/here';
params['image_two'] = 'http://url.to/second/image/goes/here';
params['image_three'] = 'http://url.to/third/image/goes/here';
params['image_four'] = 'http://url.to/fourth/image/goes/here';
params['image_five'] = 'http://url.to/fifth/image/goes/here';
params['action_one'] = 'PurpleRobot.playDefaultTone();';
params['action_two'] = 'PurpleRobot.playDefaultTone();';
params['action_three'] = 'PurpleRobot.playDefaultTone();';
params['action_four'] = 'PurpleRobot.playDefaultTone();';
params['action_five'] = 'PurpleRobot.playDefaultTone();';

PurpleRobot.updateWidget(params);