Overview
The Notification Module is used to control the notification objects such as the LEDs, beeper and pager on the device. While some devices are equipped more than one of a given object type, most have multiple LEDs, a single beeper and a single pager.
To control notification objects, it is first necessary to query the device to discover which objects are available. This is done using the Enumerate method and EnumNotificationsEvent, which returns a unique identifier for each available notification to be used to set the notification state. Notifications can be set as "on," "off" or "cycling." with the behaviour of 'on' or 'off' notification objects self explanatory; when set to cyclic LEDs will flash for the specified number of times whereas the beeper and pager will only activate once for the specified duration.
Syntax
| notification (Module) <META> Syntax |
|---|
<META HTTP-Equiv="Notification" content="[method / parameter]"> |
| Notification JavaScript Object Syntax: |
|---|
| By default the JavaScript Object 'notification' will exist on the current page and can be used to interact directly with the notification. |
|
To Invoke notification methods via JavaScript use the following syntax: notification.method();
e.g. notification . enumerate(); |
|
To Set notification parameters via JavaScript use the following syntax: notification.parameter = 'value'; remembering to enclose your value in quotes where appropriate.
e.g. notification . setLEDOnDuration = 'value'; |
|
To Set notification return events via JavaScript use the following syntax: notification.event = JavaScript Function;
e.g. notification . enumNotificationsEvent = 'doFunction(%json)';
|
|
To set multiple EMML parameters / events on a single line use the following syntax: notification.setEMML("[Your EMML Tags]");
e.g. notification . setEMML("setLEDOnDuration:value ; enumNotificationsEvent:url('JavaScript:doFunction(%json)');enumerate"); |
Methods
Items listed in this section indicate methods or, in some cases, indicate parameters which will be retrieved.
| Name | Description | Default Value |
|---|---|---|
| enumerate | Immediately triggers an EnumNotificationsEvent containing the notification objects available on the current device | N/A |
Parameters
Items listed in this section indicate parameters, or attributes which can be set.
| Name | Possible Values | Description | Default Value |
|---|---|---|---|
| setLEDOnDuration:[Value] | Milliseconds | Subsequent calls to cycle LED notifications will cause them to remain on for the specified number of milliseconds per cycle. This parameter has no effect if the LED State is set to 'On' or 'Off' | 1000 |
| setLEDOffDuration:[Value] | Milliseconds | Subsequent calls to cycle LED notifications will cause them to remain off for the specified number of milliseconds per cycle. This parameter has no effect if the LED State is set to 'On' or 'Off' | 1000 |
| setLEDNumberOfCycles:[Value] | Positive Number | Subsequent calls to cycle LED notifications will cause them to switch between on and off the specified number of times. | 1 |
| setBeeperFrequency:[Value] | Frequency in Hertz | When the beeper next sounds it will do so at the specified number of Hertz, provided this is supported by the hardware. This parameter has an effect for both StateOn and StateCycle. | 2000 |
| setBeeperVolume:[Value] | Number greater than 0. The maximum value is platform dependant. | When the beeper next sounds it will do so at the specified volume. 0 represents minimum volume, the decibels each volume level represents is device dependant | 0 |
| setBeeperDuration:[Value] | Milliseconds | When the beeper is next instructed to cycle it will sound for the specified number of milliseconds | 1000 |
| setVibrateDuration:[Value] | Milliseconds | When the pager is next instructed to cycle it will vibrate the device for the specified number of milliseconds | 1000 |
| stateOn:[Value] | The index of the notification, obtained via the EnumNotificationsEvent | Turns the specified notification object on. This will either light an LED, sound the beeper or vibrate the device depending on the type of the notification. Please note that some platforms may not allow you to continuously vibrate the pager to conserve battery. | Device Specific |
| stateOff:[Value] | The index of the notification, obtained via the EnumNotificationsEvent | Turns the specified notification object off. This will either extinguish an LED, silence the beeper or stop the device from vibrating | Device Specific |
| stateCycle:[Value] | The index of the notification, obtained via the EnumNotificationsEvent | Cycles the specified notification object. LEDs will alternate between on and off for the specified number of cycles. The beeper and pager will be invoked once for the specified number of milliseconds. | Device Specific |
Events
Values are returned to the caller in RhoElements via Events. Most modules contain events and those returned from this module are given below along with the event parameters. Events can cause a navigation to a new URL or a JavaScript function on the page to be invoked. Each event will in most cases have a number of parameters associated with it which will either be strings or JavaScript arrays. Event parameters can be accessed either directly or via JSON objects.
enumNotificationsEvent
The EnumNotificationsEvent is triggered in response to calling the 'Enumerate' method and is used to obtain the notifications available on the device and their associated identifiers. There is a single return value for this event which is a two dimensional array, with one dimension listing the available notifications and the other dimension listing the attributes for each notification object
| ID | Name | Description |
|---|---|---|
| 1 | notificationsArray (notificationIndex, notificationType, notificationName) | 2 Dimensional array of notifications, see remarks |
Multi Instance
When multiple RhoElememts applications are running the following considerations should be made: Only the application with Focus will have the ability to enable/disable notifications. When an application is sent to background if there are any notifications in progress (vibrator, beeper etc.) they would be stopped.
Remarks
No Notification Objects
If the device has no notification objects the array returned by EnumNotificationsEvent will be empty
Notification State
If RhoElements is exited after applying notifications, the settings will not revert.
EnumNotificationsEvent Array Format
There is a single return value for this event which is a two dimensional array with the format below:
(
( // Array for Notification 1
notificationIndex, // Unique Identifier for each notification.
notificationType, // Type of the notification. '0' Indicates an LED; '1' indicates a Beeper and '2' indicates a pager
notificationName // Human readable name of the notification, e.g. "Green LED"
)
( // Array for Notification 2
notificationIndex,
notificationType,
notificationName
)
)
Requirements
| RhoElements Version | 1.0.0 or above |
|---|---|
| Supported Devices | All supported devices. |
| Minimum Requirements | None. |
| Persistence | Partially Persistent - Changes to this module will persist when navigating to a new page with the exception of the EnumNotificationsEvent which is page specific. |
HTML/JavaScript Examples
The following example stores the available notifications in a JavaScript array and displays them to the user in an HTML table. Note that a 2 dimensional array is returned in the EnumNotificationsEvent.
<HTML>
<HEAD>
<META HTTP-Equiv="Notification" content="EnumNotificationsEvent:url('javascript:setupNtfyArr(%s)');">
</HEA
D>
<script>
var ntfyArr = new Array();
var notType = new Array('LED', 'BEEPER', 'PAGER');
var NTFY_INDEX = 0;
var NTFY_TYPE = 1;
var NTFY_NAME = 2;
function setupNtfyArr(notArr)
{
ntfyArr = notArr;
var html = "";
for(i=0; i<ntfyArr.length; i++)
{
html += '' + ntfyArr[i][NTFY_INDEX] + ', '
+ notType[ntfyArr[i][NTFY_TYPE]] + ''
+ ntfyArr[i][NTFY_NAME] + '';
}
html += "";
htmDiv.innerHTML = html;
}
function onListNotifications()
{
notification.enumerate();
}
</scr
ipt>
<BODY>
<div id="htmDiv">
<INPUT TYPE="button" VALUE="List Notification Objects" ONCLICK="onListNotifications();">
</div
>
</BOD
Y>
</HTM
L>
The following function takes a notification index and a notification type. Depending on the type of notification it invokes it appropriately. The index and type of each notification can be obtained via the EnumNotificationsEvent as demonstrated in the previous example
<script>
function annoyUser(index, type)
{
if (type == 0)
{
// If the Type of Notification is an LED flash it 10 times, on for 1 second off for 1 second.
notification.setLEDOnDuration = 1000;
notification.setLEDOffDuration = 1000;
notification.setLEDNumberOfCycles = 10;
// Flash the LED
notification.stateCycle = index;
}
else if (type == 1)
{
// If the Type of the Notification is a Beeper emit a continuous high pitch tone at maximum volume
notification.setBeeperFrequency = 8000;
notification.setBeeperVolume = 3;
// Start the Beeper
notification.stateOn = index;
}
else if (type == 2)
{
// If the type of the notification is a Pager then vibrate the device for 15 seconds
notification.setVibrateDuration = 15000;
notification.stateCycle = index);
}
}
</scr
ipt>