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+
API | OS 5.0 | OS 6.0 | OS 7.0 | PlayBook | Ripple |
---|---|---|---|---|---|
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 ID | OS 5.0 | OS 6.0 | OS 7.0 | PlayBook | Ripple |
---|---|---|---|---|---|
<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. |
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>