Profile Box

Provides access to the current user's profile box.

A box for this application that appears in the current user's profile. Each box contains a list of items, each composed of text and an optional icon. There is a maximum of 3 items; as more are added, older items will be removed automatically.

This box can be viewed by the current user and their contacts, and is editable by the current user and the owning application (on this device). The current user can only remove items.

Permission Model

The user must manually show the profile box via the "activities" option in the BBM options screen for the application. The application can add items whether or not this option is enabled.

The application can read profileboxEnabled to determine if the user is showing the profile box, and prompt them to enable it with blackberry.bbm.platform.showBBMAppOptions.

Icon recommendations

  • Recommended icon size is 100x100, regardless of device.
  • Icons should be square.
  • Alpha is supported.
  • Animating icons are not supported. Only the first frame will be used.

Launching your application from the profile box

The user can invoke an application through its profile box items in their profile or a contact's profile. The application will be brought to the foreground and/or launched if not yet running. The invoking profile box item can be obtained by assigning a callback to blackberry.bbm.platform.onappinvoked.


Supported Platform(s)

Configuration Document Settings

To use all of the API described for this object, you must ensure the following settings are in your configuration document:

You must declare the feature element(s) below in your configuration document:

Feature IDBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
<feature id="blackberry.bbm.platform" /> Y Y Y     Y 

Permission Elements (PlayBook and BlackBerry 10+)
This API does not require a <permission> element to be declared in the configuration document of your BlackBerry WebWorks Application.


Functions

static void blackberry.bbm.platform.self.profilebox.addItem (options : Object, onSuccess: function(item : blackberry.bbm.platform.self.profilebox.ProfileBoxItem), onError: function(error : String))


Adds an item to the top of the user's profile box.

Icons are optional and must be registered before an item is added.


Supported Platforms
 - BlackBerry 10


Parameters
options The options.

text: The text of the item.
cookie: The customizable cookie string.
iconId: Optional The icon ID of a previously registered icon.
onSuccess Invoked when the item has been removed.

item: The new item.
onError Invoked when when there was an error removing the item.

error: Contains error message.

Code Example:
<script type="text/javascript">
// Add an item with icon, text, and a cookie
var options = {text: "Planted an apple orchard on 10 acres!", icon: "local:///smiley.jpg", cookie: "10acres"};
blackberry.bbm.platform.self.profilebox.addItem(options, function (item) {
           // do something with the item
       }), function (error) {
           alert(error);
       });
</script>

static blackberry.bbm.platform.self.profilebox.ProfileBoxItem blackberry.bbm.platform.self.profilebox.addItem (options : Object)


Adds an item to the top of the user's profile box.

Icons are optional and are provided via a fully-qualified URI. Non-local URIs must be whitelisted in the application's configuration file. Examples:

  • Locally from within the widget package (e.g. "local:///smiley.jpg")
  • From the file system of the device (e.g. "file:///SDCard/BlackBerry/pictures/smiley.jpg")


Supported Platforms
 - BlackBerry OS 5.0+


Parameters
options The options.

text: The text of the item.
icon: Optional The URI of the icon to use. If not provided, no icon is used.
cookie: Optional The customizable cookie.

Throws
UserProfileBoxAccessException If the profile box is inaccessible.

Return:

The new item.



Code Example:
<script type="text/javascript">
// Add an item with icon, text, and a cookie
var options = {text:"Planted an apple orchard on 10 acres!", icon:"local:///smiley.jpg", cookie:"10acres"};
blackberry.bbm.platform.self.profilebox.addItem(options);
</script>
<script type="text/javascript">
// Add an item with text
var options = {text:"Bought a 100 acre farm!"};
blackberry.bbm.platform.self.profilebox.addItem(options);
</script>

static void blackberry.bbm.platform.self.profilebox.clearItems ()


Removes all items.


Supported Platforms
 - BlackBerry OS 5.0+


Throws
UserProfileBoxAccessException If the profile box is inaccessible.

static void blackberry.bbm.platform.self.profilebox.clearItems ()


Removes all items.


Supported Platforms
 - BlackBerry 10

static void blackberry.bbm.platform.self.profilebox.registerIcon (options : Object, onSuccess: function(iconId : Object), onError: function(error : String))


Registers an icon for use with user's profile box.

Icons are provided via a fully-qualified URI. Non-local URIs must be whitelisted in the application's configuration file. Examples:

  • Locally from within the widget package (e.g. "local:///smiley.jpg")
  • From the file system of the device (e.g. "file:///SDCard/BlackBerry/pictures/smiley.jpg")


Supported Platforms
 - BlackBerry 10


Parameters
options The options.

icon: The URI of the icon to register.
iconId: An icon ID for the icon, this number must be unique.
onSuccess Invoked when the icon has been registered.

iconId: The icon ID of the registered icon.
onError Invoked when when there was an error registering the icon.

error: Contains error message.

Code Example:
<script type="text/javascript">
// Register an icon
var options = {icon: "local:///smiley.jpg", iconId: 1337};
blackberry.bbm.platform.self.profilebox.registerIcon(options, function (icon) {
           // do something
           alert("Registered " + icon.iconId)
       }), function (error) {
           alert(error);
       });
</script>

static void blackberry.bbm.platform.self.profilebox.removeItem (item : blackberry.bbm.platform.self.profilebox.ProfileBoxItem, onSuccess: function(item : blackberry.bbm.platform.self.profilebox.ProfileBoxItem), onError: function(error : String))


Removes an item.


Supported Platforms
 - BlackBerry 10


Parameters
item The item to remove.
onSuccess Invoked when the item has been removed.

item: The item that was removed.
onError Invoked when when there was an error removing the item.

error: Contains error message.

static void blackberry.bbm.platform.self.profilebox.removeItem (item : blackberry.bbm.platform.self.profilebox.ProfileBoxItem)


Removes an item.


Supported Platforms
 - BlackBerry OS 5.0+


Parameters
item The item to remove.

Throws
UserProfileBoxAccessException If the profile box is inaccessible.

Properties

static readonly Boolean accessible


true if the profile box is accessible and can be updated; false otherwise. The profile box is not accessible when the device is in mass storage mode.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry 10

static readonly blackberry.bbm.platform.self.profilebox.ProfileBoxItem[] items


The profile box items. undefined if the device is in mass storage mode.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry 10

Documentation generated by JsDoc Toolkit 2.4.0 on Mon Feb 11 2013 14:51:09 GMT-0500 (EST)