Notification

The Notification API allows you to create a notification object in the BlackBerry Hub.

Since: BlackBerry WebWorks 2.0

Installation:

To use this API in your project, add the notification plugin:

webworks plugin add com.blackberry.notification

Learning Resources:

BlackBerry WebWorks Notification Sample App Sample that demonstrates how to use the BlackBerry Notification API [BlackBerry on GitHub].

Constructors:
Notification
Functions:
void remove()
void close()
void requestPermission()
Properties:
String permission

Notification

The Notification object.

Synopsis:

Notification(title, options)

Parameters:

title {String}

Required. Used as title text in BlackBerry Hub entries.

options {Object}

The options object supplies more information needed to create the notification.

body {String}

Used as subtitle text in BlackBerry Hub entries.

tag {String}

Tag of the notification. If provided, it can be used to close the notification by static method Notification.remove(). Only one notification with the given tag can exist in the UIB. A newly created notification with the same tag will replace the existing notification.

target {String}

Target of application that will be launched if the user opens the notification in the BlackBerry Hub. This property should match the identifier returned by the invocation framework when the target application registered with the invocation framework. Value is passed on to the Invocation Framework as target. If the user doesn't specify options.target, the identifier of type "Application" of the current application will be used, which means the current application will be invoked if the user opens the notification. if there is no valid invocation identifier defined, no application will be invoked.

targetAction {String}

Action as registered with invocation framework. Value is passed on to the Invocation Framework as action. If the user doesn't specify options.targetAction, "bb.action.OPEN" will be used.

payload {String}

Payload to send to the invoked app. Data must be Base64 encoded. Value is passed on to the Invocation Framework as data.

payloadURI {String}

URI to payload data to send to the invoked app. Value is passed on to the Invocation Framework as uri. Example: "file://path/to/file".

payloadType {String}

The MIME type of URI or payload data to send to the invoked app. Value is passed on to the Invocation Framework as type. Example: "text/plain".

onclick {String}

It is ignored for WebWorks application. Instead, use onInvoked event handler, which will be triggered when the user opens the notification in UIB.

onshow {String}

It will be triggered if the notification is created successfully; or onerror callback will be triggered.

onerror {String}

It will be triggered if the notification could not be created; or onshow callback will be triggered.

onclose {String}

It is ignored for WebWorks application as it has no clear usage of it.

Example:

<script type="text/javascript">

  // Create the simplest notification
  new Notification("You have a simple notification");


  // Create a notification with body
  new Notification("The title", {body: "The body"});


  // Create a notification with events
  var title = "You have a notification";
  var options = {
      body : "Some details",
      onshow : function() { 
          alert("The notification was created successfully!"); 
      },
      onerror : function() { 
          alert("The notification could not be created!"); 
      }
  }
  var n = new Notification(title, options);


  // Create notifications with same tag for a chatroom session
  // Bob says "Hi"
  new Notification("Bob: Hi", { tag: 'chat_Bob' });

  // Bob says "Are you free this afternoon?"
  // As only one notification will exist, the application creates 
  // another notification with the combined message, using the same tag
  new Notification("Bob: Hi / Are you free this afternoon?", 
      { tag: 'chat_Bob' });


  // Create a notification with invocation information and use 
  // invoked event to determine and do something for that notification
  var title = "A notification for something";
  var options = {
      targetAction : "bb.action.DoSomethingForNotification", 
      // If no target is specified, it will invoke the current 
      //application
      payloadURI : "some link"
  }

  // Create the notification
  new Notification(title, options);

  // Register to listen to invoked event
  document.addEventListener("invoked", onInvoked);

  // Handle invoked event
  function onInvoked(onInvokedInfo) {
      // Do something if the action is 
      // "BB.action.DoSomethingForNotification"
      if(onInvokedInfo.action == "BB.action.DoSomethingForNotification") 
      {
          // onInvokedInfo.uri is "some link"
          doSomething(onInvokedInfo.uri);  
      }
  }


  // Create a notification with invocation information that invokes 
  // other application
  var title = "A notification will invoke browser";
  var options = {
      target : "sys.browser",
      targetAction : "bb.action.OPEN",
      payloadType : "text/html",
      payloadURI : "the link"
  }

  // Create the notification and when the user opens the 
  // notification item in UIB, it will invoke browser with "the link"
  new Notification(title, options);

</script>

remove()

This static method will delete the notification from the UIB notifications area automatically. UIB notifications will also be removed manually if the user clicks it.

Synopsis:

void Notification.remove(tag)

Parameters:

tag {String}

Required. Used as the Id of the notification for deleting it. tag is optional property of options object that is passed to Notification constructor; if it is omitted, the user won't be able to use this static function remove() to delete the notification.

Example:

<script type="text/javascript">

    new Notification("You have a tagged notification", 
        { tag: 'tagged_notification' });

    // Even the application is closed and the above object is destroyed,
    // you can still remove the notification
    Notification.remove('tagged_notification');

</script>

close()

This member method will delete the notification from the UIB notifications area automatically. UIB notifications will also be removed manually if the user clicks it.

Synopsis:

void blackberry.notification.close()

Example:

<script type="text/javascript">

    var n = new Notification("You have a simple notification");

    // Automatically close the notification after an hour
    setTimeout("n.close()", 1000 * 60 * 60);

</script>

requestPermission()

The w3c requestPermission function. As for a WebWorks application, permission is always granted, this function will just do nothing.

Synopsis:

void Notification.requestPermission(callback)

Parameters:

callback {Function}

The callback required by w3c requestPermission function. In WebWorks it is ignored.

permission

The w3c static permission attribute returns permission for showing notification for a given origin. As for a WebWorks application, permission is always granted, the value is always "granted".

Synopsis:

String blackberry.notification.permission = "granted"

Last modified: 2014-10-09



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus