Working with the user profile

The BBM Social Platform provides both read and write access to a user’s BlackBerry Messenger profile. Your app can access the personal message, display name, status, status message, and display picture.

You can update the user's BBM profile by using the update methods in the UserProfile API. When you invoke the API, a dialog appears prompting the user to accept or reject the change.

When a user or a contact changes their BBM profile, a signal is emitted that returns the new value for the property that was changed. See BBM Social Platform events for more information about event handling.

Updating a user's BBM profile

The following code samples show you how to read from and write to a user's BlackBerry Messenger profile by using QML to create the UI and C++ to handle the business logic. These code samples are taken from the Cascades bbmprofile sample application. If you want to see the complete source code for the finished app, you can download the sample app from GitHub.

The bbmprofile sample app registers with the BBM Social Platform, reads a user's BBM profile data, displays it, and then handles the input and update of new values. You can update a user's BBM status, status message, display picture, or personal message.

Begin by creating a new UserProfile object (m_userProfile) by calling UserProfile() and passing in the BBM context object (m_context). The context object is an instance of the Context class and provides access to BBM social platform functionality.

m_userProfile = new bb::platform::bbm::UserProfile(m_context, this);

Next, create a ProfileEditor object for this profile (m_profileEditor), passing in the user profile (m_userProfile). ProfileEditor is a class (defined in the sample app) that you use to save the updated profile values.

m_profileEditor = new ProfileEditor(m_userProfile, this);

Next, load profile.qml, which defines the UI and displays the user's current BBM profile data.

// Load the QML
QmlDocument *qml = QmlDocument::create
                   ("asset:///profile.qml").parent(this);
        

To access the profile object in QML, you must first expose it to QML by using setContextProperty().

// Expose the object to QML
qml->setContextProperty("_profile", this);

The user's existing profile data can then be accessed in profile.qml by invoking the C++ UserProfile functions (for example, personalMessage()):

Field {
   title: qsTr("personal message")
   value: _profile.personalMessage
}

Then, create the root object, and display the UI using setScene():

// Retrieve root object for the UI
AbstractPane *root = qml->createRootObject<AbstractPane>();
//  Display UI
Application::instance()->setScene(root);
 

Screen showing the UI defined in profile.qml.

Here's what the profile.qml file looks like.

import bb.cascades 1.0

NavigationPane {
    id: navigationPane

    onPopTransitionEnded: page.destroy()

    Page {
        actions: [
            ActionItem {
              title: qsTr("Update profile")

              onTriggered: {
                navigationPane.push(updateProfilePage.createObject())
              }
            }
        ]
        BbmProfileScrollView {

            Container {
                layout: DockLayout {
                }

                ImageView {
                  horizontalAlignment: HorizontalAlignment.Fill
                  verticalAlignment: VerticalAlignment.Fill

                  imageSource: "asset:///images/background_blurred.png"
                }

                Container {
                    horizontalAlignment: HorizontalAlignment.Fill
                    verticalAlignment: VerticalAlignment.Fill

                    topPadding: 20
                    leftPadding: 20
                    rightPadding: 20

                    Container {
                        layout: StackLayout {
                            orientation: LayoutOrientation.LeftToRight
                        }

                        ImageView {
                            preferredHeight: 300
                            preferredWidth: 300

                            image: _profile.displayPicture
                        }

                        Button {
                            text: qsTr("Get Avatar")
                            onClicked: {
                                _profile.requestDisplayPicture()
                            }
                        }
                    }

                    Divider {
                    }

                    Container {
                        minHeight: 50

                        layout: StackLayout {
                            orientation: LayoutOrientation.LeftToRight
                        }

                        ImageView {
                            verticalAlignment: VerticalAlignment.Center

                            imageSource: "images/busy.png"
                            visible: _profile.busy
                        }

                        Label {
                            layoutProperties: StackLayoutProperties {
                                spaceQuota: 1
                            }

                            text: _profile.displayName
                            textStyle {
                                color: Color.White
                                fontWeight: FontWeight.Bold
                            }
                        }
                    }

                    Field {
                        title: qsTr("status message")
                        value: _profile.statusMessage
                    }

                    Field {
                        title: qsTr("personal message")
                        value: _profile.personalMessage
                    }

                    Field {
                        title: qsTr("pp id")
                        value: _profile.ppid
                    }

                    Field {
                        title: qsTr("app version")
                        value: _profile.appVersion
                    }

                    Field {
                        title: qsTr("handle")
                        value: _profile.handle
                    }

                    Field {
                        title: qsTr("platform version")
                        value: _profile.platformVersion
                    }
                }
            }
        }
    }

    // 
    attachedObjects: [  // attach custom component to visual element
        ComponentDefinition { // define custom component
            id: updateProfilePage 
            source: "UpdateProfile.qml" // Define the content
        }
    ]
}

Now that the main screen displays the user's existing profile data, the next step is to display the Update Profile screen, which allows the user to enter new values for the profile. In profile.qml, the Update Profile screen is defined using the attachedObjects property of NavigationPane. The page is defined as a custom QML component in UpdateProfile.qml that is created dynamically by using a ComponentDefinition object called updateProfilePage.

attachedObjects: [
    ComponentDefinition {
        id: updateProfilePage
        source: "UpdateProfile.qml"
    }
]

The Update Profile screen appears when the Update Profile button is tapped.

ActionItem {
    title: qsTr("Update profile")
        onTriggered: {
        navigationPane.push(updateProfilePage.createObject())
    }
}

Screen showing the Update profile button.

Screen showing the Update Profile UI.

Here's what the UpdateProfile.qml file looks like.

import bb.cascades 1.0

NavigationPane {
    id: navigationPane

    onPopTransitionEnded: page.destroy()

    Page {
        actions: [
            ActionItem {
                title: qsTr("Update profile")

               onTriggered: {
                 navigationPane.push(updateProfilePage.createObject())
               }
            }
        ]
        BbmProfileScrollView {

            Container {
                layout: DockLayout {
                }

                ImageView {
                  horizontalAlignment: HorizontalAlignment.Fill
                  verticalAlignment: VerticalAlignment.Fill

                  imageSource: "asset:///images/background_blurred.png"
                }

                Container {
                    horizontalAlignment: HorizontalAlignment.Fill
                    verticalAlignment: VerticalAlignment.Fill

                    topPadding: 20
                    leftPadding: 20
                    rightPadding: 20

                    Container {
                        layout: StackLayout {
                            orientation: LayoutOrientation.LeftToRight
                        }

                        //! [1]
                        ImageView {
                            preferredHeight: 300
                            preferredWidth: 300

                            image: _profile.displayPicture
                        }

                        Button {
                            text: qsTr("Get Avatar")
                            onClicked: {
                                _profile.requestDisplayPicture()
                            }
                        }
                    }

                    Divider {
                    }

                    Container {
                        minHeight: 50

                        layout: StackLayout {
                            orientation: LayoutOrientation.LeftToRight
                        }

                        ImageView {
                            verticalAlignment: VerticalAlignment.Center

                            imageSource: "images/busy.png"
                            visible: _profile.busy
                        }

                        Label {
                            layoutProperties: StackLayoutProperties {
                                spaceQuota: 1
                            }

                            text: _profile.displayName
                            textStyle {
                                color: Color.White
                                fontWeight: FontWeight.Bold
                            }
                        }
                    }

                    Field {
                        title: qsTr("status message")
                        value: _profile.statusMessage
                    }

                    Field {
                        title: qsTr("personal message")
                        value: _profile.personalMessage
                    }

                    Field {
                        title: qsTr("pp id")
                        value: _profile.ppid
                    }

                    Field {
                        title: qsTr("app version")
                        value: _profile.appVersion
                    }

                    Field {
                        title: qsTr("handle")
                        value: _profile.handle
                    }

                    Field {
                        title: qsTr("platform version")
                        value: _profile.platformVersion
                    }
                }
            }
        }
    }

    attachedObjects: [
        ComponentDefinition {
            id: updateProfilePage
            source: "UpdateProfile.qml"
        }
    ]
}

After the new values are entered, tapping the Save button invokes the associated save function that's defined in ProfileEditor(), and then pops the Update Profile screen off the NavigationPane stack, revealing the updated values displayed by profile.qml. The code for the Save button is defined in UpdateProfile.qml.

Button {
    horizontalAlignment: HorizontalAlignment.Right

    text: qsTr("Save")

    onClicked: {
        _profile.editor.savePersonalMessage(personalMessage.text)
        navigationPane.pop()
    }
}

For example, in the code sample above, saving the personal message invokes profileEditor::savePersonalMessage(). The savePersonalMessage() function invokes requestUpdatePersonalMessage(), which displays a dialog box that prompts the user to accept or reject the change.

void ProfileEditor::savePersonalMessage(const QString &personalMessage)
{
    if (!m_userProfile) // Check that the pointer is still valid
        return;
    // Ask the user if it's OK to update their personal message.
    m_userProfile->requestUpdatePersonalMessage(personalMessage);
}

If the user accepts the change, the new value is written to the profile, and profile.qml displays it.


Screen showing the BBM Profile Update confirmation dialog.

Screen showing the updated personal message.

Last modified: 2014-05-14



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

comments powered by Disqus