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.

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

Supported Platform(s)

- BlackBerry OS 5.0+

View Supported Platform Table

APIOS 5.0OS 6.0OS 7.0PlayBookRipple
addItem Y Y Y   
clearItems Y Y Y   
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 IDOS 5.0OS 6.0OS 7.0PlayBookRipple
<feature id="blackberry.bbm.platform" /> Y Y Y   

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

API Summary



Properties

addItem


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

Supported Platform(s)

 - BlackBerry OS 5.0+

Description

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

Icons are optional and are provided via 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 filesystem of the device (e.g. "file:///SDCard/BlackBerry/pictures/smiley.jpg")



Returns

the new item.

Parameter Type Description
options Object The options.

text: The text of the item.
icon: Optional The URI of the icon to use. If not provided then no icon will be used.
cookie: Optional The customizable cookie.

Throws Description
UserProfileBoxAccessException If the profile box is inaccessible.

Code Example(s)

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

clearItems


static void clearItems()

Supported Platform(s)

 - BlackBerry OS 5.0+

Description

Removes all items.



Throws Description
UserProfileBoxAccessException If the profile box is inaccessible.

removeItem


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

Supported Platform(s)

 - BlackBerry OS 5.0+

Description

Removes an item.



Parameter Type Description
item blackberry.bbm.platform.self.profilebox.ProfileBoxItem The item to remove.

Throws Description
UserProfileBoxAccessException If the profile box is inaccessible.

Properties:


Property Type Description Supported Platform(s)
accessible Static
Boolean
readonly
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.
 - BlackBerry OS 5.0+
items Static
blackberry.bbm.platform.self.profilebox.ProfileBoxItem[]
readonly
The profile box items. undefined if the device is in mass storage mode.
 - BlackBerry OS 5.0+

Code Example(s)


<script type="text/javascript">
// Trigger an action in the application when a profile box item is selected
blackberry.bbm.platform.onAppInvoked = function(reason, param) {
    if(reason == "profilebox") {
        var boxItem = param;
        var achievementID = boxItem.cookie;
        // Take action based on profile box item...
    }
};
</script>

Documentation generated by JsDoc Toolkit 2.4.0 on Sun Dec 30 2012 13:31:19 GMT-0500 (EST)