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)

- BlackBerry OS 5.0+
View Supported Platform Table
APIBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
blackberry.bbm.platform.self.profilebox.addItem Y Y Y       
blackberry.bbm.platform.self.profilebox.clearItems Y Y Y       
blackberry.bbm.platform.self.profilebox.removeItem Y Y Y       
accessible Y Y Y       
items Y Y Y       

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       

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 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.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+

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+

Documentation generated by JsDoc Toolkit 2.4.0 on Sun Dec 30 2012 18:15:42 GMT-0500 (EST)