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.
Functions:
void addItem()
void clearItems()
void registerIcon()
void removeItem()
Properties:
Boolean accessible
ProfileBoxItem items

addItem()

Adds an item to the top of the user's profile box. Icons are optional and must be registered before an item is added.

Synopsis:

void blackberry.bbm.platform.self.profilebox.addItem(options, onSuccess, onError)

Parameters:

options {Object}

The options.

text {String}

The text of the item.

cookie {String}

The customizable cookie string.

iconID Optional {Number}

The icon ID of a previously registered icon.

onSuccess {Function}

Invoked when the item has been added.

item {ProfileBoxItem}

The new item.

onError {Function}

Invoked when there was an error adding the item.

error {String}

Contains the error message.

Example:

<script type="text/javascript">

    // Add an item with icon, text, and a cookie

    var options = {text: "Planted an apple orchard on 10 acres!", 
        iconId: 1337, cookie: "10acres"};
    blackberry.bbm.platform.self.profilebox.addItem(options, 
       function (item) {
        // do something with the item
    }, function (error) {
        alert(error);
    });

</script>
            

clearItems()

Removes all items.

Synopsis:

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

registerIcon()

Registers an icon for use with user's profile box. Note that the icon cannot exceed 32KB.

Icons are provided via a fully qualified URI. Nonlocal 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")

Synopsis:

void blackberry.bbm.platform.self.profilebox.registerIcon(options, onSuccess, onError)

Parameters:

options {Object}

The options.

icon {String}

The URI of the icon to register.

iconID {Number}

An icon ID for the icon, this number must be unique.

onSuccess {Function}

Invoked when the icon has been registered.

iconId {Object}

The icon ID of the registered icon.

onError {Function}

Invoked when there was an error registering the icon.

error {String}

Contains the error message.

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>
            

removeItem()

Removes an item.

Synopsis:

void blackberry.bbm.platform.self.profilebox.removeItem(item, onSuccess, onError)

Parameters:

item {ProfileBoxItem}

The item to remove.

onSuccess {Function}

Invoked when the item has been removed.

item {ProfileBoxItem}

The item that was removed.

onError {Function}

Invoked when there was an error removing the item.

error {String}

Contains the error message.

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.

Synopsis:

readOnly
Boolean blackberry.bbm.platform.self.profilebox.accessible

items

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

Synopsis:

readOnly
ProfileBoxItem blackberry.bbm.platform.self.profilebox.items

Last modified: 2014-05-14



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

comments powered by Disqus