Purple Robot includes a built-in JavaScript engine based on the Mozilla Rhino project. Scripts may be executed by triggers or submitted to the built-in webserver via the built-in localhost HTTP server.

Purple Robot supports the following extensions to the core JavaScript classes and functions:

PurpleRobot.updateConfig(params:Object)

This function sets configuration parameters from a JavaScript object where the object properties are the names of the parameters and the keys are the values.

Example:

PurpleRobot.updateConfig({"config_json_refresh_interval": "60", "config_show_background": true });

Note that this function replaces an older version that just took a single key-value pair as an argument. While that form of the function remains, it should not be used in new scripts moving forward.


PurpleRobot.readUrl(url:String)

This function fetches the string contents of a given URL and returns the string value. If the URL points to non-string content, _null _is returned instead.


PurpleRobot.loadLibrary(libraryName:String)

This function imports an existing library into the current execution context. The specified library must be included in the app’s assets to load properly. Currently, the following libraries are part of the standard Purple Robot package: astro.js, foursquare.js, jstat.js, underscore.js.


PurpleRobot.updateWidget(params:Object)

Note that this method only updates widgets provided by the Purple Notifier application, not the embedded widgets in Purple Robot, which will soon be deprecated.

This method updates home screen widgets with images, text, and tap actions. params is a JavaScript object that includes the following keys:

  • identifier (required): String identifying the widget(s) to be updated. If multiple widgets share the same identifier, all are updated with the contents of params as best possible.

  • title (optional): String containing the title text to be updated. All widgets with text use the title parameter.

  • message (optional): String containing additional descriptive text.

  • image (optional): URL pointing to the image to use in image-bearing widgets. All image widgets use the image parameter.

  • image_two, image_three, image_four, image_five (optional): Additional image URLs for widgets with multiple images.

  • action (optional): A JavaScript string containing the script for Purple Robot to execute when a default widget interaction (tap) occurs. The widget will broadcast this string back to Purple Robot for execution on interaction events.

  • action_two, action_three, action_four, action_five (optional): Additional action scripts that may be assigned to widgets using the extended image_* parameters as button images.

PurpleRobot.updateWidget(title:String, message:String, applicationName:String)

PurpleRobot.updateWidget(title:String, message:String, applicationName:String, launchParams:Object, script:String)

This function updates the content of any homescreen Purple Robot widgets with the provided title and message. A named application may be specified to launch upon tapping the widget and a script to be executed after the application launch intent is broadcast. A map of launch parameters may also be specified as additional arguments in the launch intent.


PurpleRobot.emitToast(message:String, longDuration:Boolean)

This function displays an unobtrusive toast notification with the specified duration (true = lengthy, false = short).


PurpleRobot.launchUrl(url:String)

This function launches the specified URL using the default handler for the URL type.


PurpleRobot.launchApplication(applicationName:String)

PurpleRobot.launchApplication(applicationName:String, launchParams:Object, script:String)

This function launches the specified application with the specified launch parameters. An optional script may be provided that is run after the launch intent is broadcast.


PurpleRobot.packageForApplicationName(applicationName:String)

Returns the Android application package name for the given application name.


PurpleRobot.showApplicationLaunchNotification(title:String, message:String, applicationName:String, displayDate:Number)

PurpleRobot.showApplicationLaunchNotification(title:String, message:String, applicationName:String, displayDate:Number, launchParams:Object, script:String)

Constructs a status notification that launches the specified application when tapped. The notification may be scheduled by specifying the desired date in the number of milliseconds of the Unix epoch. (Use “0” to display the notification immediately.) Optional launch parameters and a post-launch script may be also be provided.


PurpleRobot.fetchLabel(context:String, key:String)

Prompts the user to enter a new label for key. context is a free form string to store any information related to the context in which the label was requested.


PurpleRobot.version()

Returns the version string of the running instance of Purple Robot.


PurpleRobot.versionCode()

Returns the version number of the running instance of Purple Robot.


PurpleRobot.persistString(key:String, value:String)

PurpleRobot.fetchString(key:String)

These functions save and retrieve an arbitrary string for use between invocations of various scripts.


PurpleRobot.persistEncryptedString(key:String, value:String)

PurpleRobot.fetchEncryptedString(key:String)

These functions save and retrieve an arbitrary string for use between invocations of various scripts. Strings passed to these functions are encrypted on storage and decrypted on retrieval.


PurpleRobot.persistString(namespace:String, key:String, value:String)

PurpleRobot.fetchString(namespace:String, key:String)

These functions save and retrieve an arbitrary string for use between invocations of various scripts. Unlike the versions of these methods above, this version with the namespace parameter manages the scoped variable within an app-specified namespace that can be retrieved later via methods like fetchNamespaceMap.


PurpleRobot.persistEncryptedString(namespace:String, key:String, value:String)

PurpleRobot.fetchEncryptedString(namespace:String, key:String)

These functions save and retrieve an arbitrary string for use between invocations of various scripts. Strings passed to these functions are encrypted on storage and decrypted on retrieval. Unlike the versions of these methods above, this version with the namespace parameter manages the scoped variable within an app-specified namespace that can be retrieved later via methods like fetchNamespaceMap.


PurpleRobot.fetchNamespaces()

Returns a list of namespaces currently holding values.


PurpleRobot.fetchNamespace(namespace:String)

Adds a new namespace to Purple Robot.


PurpleRobot.addNamespace(namespace:String)

Returns an object containing all keys and values stored in the provided namespace.


PurpleRobot.fetchNamespaceMap(namespace:String)

Fetches a map of the variables set in the given namespace.


PurpleRobot.vibrate(pattern:String)

This function executes the specified haptic pattern using he device’s built-in vibrator. Available patterns: buzz, blip, sos.


PurpleRobot.playTone(tone:String)

This function plays the specified ringtone.


PurpleRobot.playDefaultTone()

This function plays the default ringtone.


PurpleRobot.scheduleScript(identifier:String, date:String, action:String)

Schedules action to be executed at the time contained in date. date is a string encoding the intended time using the same format in the date triggers (example: 20130101T123400). action can be written in any of the supported scripting languages.


PurpleRobot.dateFromTimestamp(timestamp:Number)

PurpleRobot.now()

PurpleRobot.formatDate(date:Date)

PurpleRobot.parseDate(dateString:String)

Creates native date types from timestamps or the current clock. Translates native dates to strings (and vice versa) for use in functions like scheduleScript.


PurpleRobot.log(message:String)

This function writes the specified message to the device’s LogCat stream.


PurpleRobot.showNativeDialog(title:String, message:String, confirmTitle:String, cancelTitle:String, confirmScript:String, cancelScript:String)

This function displays a full-screen alert dialog with the specified message and title as well as a confirm and cancel button. Scripts may be specified for execution on the selection of one of the two buttons.


PurpleRobot.updateTrigger(triggerId:String, trigger:Object)

This function updates triggers with matching identifiers with the contents of the supplied JSON string. (The JSON string uses the same format as that found in the initial configuration document.) Returns true if a matching trigger was located and updated.

See add_trigger.html for an example of this function in use.


PurpleRobot.resetTrigger(triggerId:String)

This function resets any state information saved in a matching trigger (such as last fire date) and resets it to its original state.


PurpleRobot.enableTrigger(triggerId:String)

PurpleRobot.disableTrigger(triggerId:String)

These functions enable or disable the identified trigger. A disabled trigger will not execute when disabled.


PurpleRobot.fetchTriggerIds()

Returns a list of identifiers for the current triggers on the device.


PurpleRobot.fetchTrigger(triggerId:String)

Returns an object representing the specified trigger and its parameters.


PurpleRobot.deleteTrigger(triggerId:String)

Remove any trigger with the specified identifier from the local device.


PurpleRobot.clearTriggers()

Removes all triggers from the local device.


PurpleRobot.enableProbes()

PurpleRobot.disableProbes()

These functions toggle the active state of the probe data acquisition system. Individual probes’ settings are not overridden, so a probe that was individually disabled prior, will not be re-enabled – just those that were enabled before.


PurpleRobot.enableProbe(probeName:String)

PurpleRobot.disableProbe(probeName:String)

Enable or disable a specific probe by name.


PurpleRobot.updateProbe(options:Object)

Updates an individual probe’s configuration settings. Note that the options object must contain a name field that identifies the probe by name. Returns true on success, false otherwise (probe not found).


PurpleRobot.probesState()

Returns a Boolean value indicating whether the probes are currently enabled.


PurpleRobot.emitReading(name:String, value:Object)

This function inserts a probe reading into the data stream with a timestamp of the current time when the function was called. Note that the value can be a String, Number, or full JavaScript Object.

See emit_usage.html for example usage.


PurpleRobot.readings()

Returns a map of the latest readings and values generated on the device.


PurpleRobot.models()

Returns a list of models and parameters currently available on the device.


PurpleRobot.addModel(url:String)

PurpleRobot.deleteModel(url:String)

PurpleRobot.enableModel(url:String)

PurpleRobot.disableModel(url:String)

Adds, removes, enables, and disables predictive models identified by their URLs. The format of the document located at url varies by model type and is currently beyond the scope of this document.


PurpleRobot.predictions()

Returns a map of the latest predictions generated by models on the device.


PurpleRobot.updateConfig(key:String, value)

This function updates a configuration parameter identified by key with value. Note that value can be a string, number, or Boolean value.


PurpleRobot.refreshConfigUrl()

This function instructs PurpleRobot to download the latest configuration information from the configuration URL.


PurpleRobot.updateConfigUrl(urlString:String)

This function updates the configuration URL with the provided URL string and refreshes the configuration from the new source. If the configuration should be cleared, pass an empty string to the function.

See set_config.html & reset_config.html for example usage.


PurpleRobot.setPassword(password:String)

PurpleRobot.clearPassword()

These functions manipulate the password that provides access to the configuration settings.

See set_password.html & clear_password.html for example usage.


PurpleRobot.enableBackgroundImage()

PurpleRobot.disableBackgroundImage()

These functions toggle the appearance of the background image on the home activity when probes are disabled.

See enable_bg_image.html & disable_bg_image.html for example usage.


PurpleRobot.restoreDefaultId()

PurpleRobot.setUserId(id:String)

PurpleRobot.fetchUserId()

PurpleRobot.fetchUserHash()

These functions set, fetch, and restore the app’s user identifier. fetchUserHash returns the MD5 hash of the user ID.

See set_user_id.html & restore_user_id.html for example usage.


PurpleRobot.enableUpdateChecks()

PurpleRobot.enableUpdateChecks()

These functions toggle periodic update checks for new versions (HockeyApp debug builds only).


PurpleRobot.broadcastIntent(action:String, extras:Object)

This function broadcasts an Android intent that may be intercepted by other applications’ BroadcastReceivers for use an inter-app communications channel. For example, to send an intent to Purple Notifier to update the basic widget, the following code may be used:

var extras = {};
extras['WIDGET'] = 'BASIC_WIDGET_UPDATE';
extras['config_basic_title'] = 'My New Title';
extras['config_basic_message'] = 'Greetings from Purple Robot! Tap me to launch Facebook.';
extras['package_name'] = 'com.facebook.katana';

PurpleRobot.broadcastIntent('edu.northwestern.cbits.purple.UPDATE_WIDGET', extras);

Please refer to the respective apps for their definitions of broadcast intents that they can receive.


PurpleRobot.runScript(script:String)

Runs the provided script in a new execution context.


PurpleRobot.valueFromString(stringValue:String)

Attempts to convert a value encoded as stringValue into a native type.