One of the core developing principles for BlackBerry 10 apps is the ability for the app to be social. The easiest way to implement this is to use the invocation framework to call the share card. The beauty of using a share card is most of the work is done for you.

The designers of BlackBerry 10 and Cascades wanted an experience where the user never leaves an app, rather flows from one application to another and that is exactly what cards do for your apps.

So as an app developer all you need to do is call the card and pass any information you want to share. This can be illustrated with a simple example.

In this example we will set up the ability to share text, some provided by the user and some prefilled out by the app. Let’s start by making a simple UI with two Labels and two TextFields. It is important to give our TextFields id's because we will need that to call them from the invocation framework:

import bb.cascades 1.0 Page { Container { Label { text: "What is your favorite food?" } TextField { id: field1 } Label { text: "What is your favorite drink?" } TextField { id: field2 } } }

Now let's create the call the the share card. We'll make that call by creating an action on the Action Bar (black bar of icons on the bottom of the screen):

import bb.cascades 1.0 Page { //... actions: [ ActionItem { title: "share" imageSource: "asset:///images/share.png" ActionBar.placement: ActionBarPlacement.OnBar attachedObjects: [ Invocation { id: invoke query: InvokeQuery { id: invq mimeType: "text/plain" invokeActionId: "bb.action.SHARE" invokerIncluded: true data: "My favorite meal is " + field1.text + " and " + field2.text + "! Shared using Brian's Example app!" onQueryChanged: invq.updateQuery() } } ] onTriggered: { invoke.trigger("bb.action.SHARE") } } ] }

So what we have above is an ActionItem with a title of "share" and an image of a the share icon and that Action will appear on the action Bar. The default is to show in the overflow menu (3 dots on the far right of the action bar). Then the attached object of the action defines the Invocation. Inside of it we have a few parameters setup in the query. Setting the mimeType to “text/plain” will invoke any card that is of that type.  This mimeType will call cards for apps such as SMS (text), email, BBM, BBM Group, Facebook, Twitter, etc. It will even call 3rd party apps that have defined a card with this type such as Blaq and What's App (only if the user has those apps installed of course). Then the invokeActionId calls for the SHARE type of card. Next, data will grab some plain text (the stuff in the quotes) and info from the field1.text and field2.text. Finally, onQureryChanged makes sure the data is updated each time the user calls the invoke. And all of this is called from the onTriggered signal of the ActionItem.

Running the code and following through the invocation share menu, the BBM card, and posting the message you should get the following workflow. The last picture showing the message sent to my Bold 9900:

Once the user is finished they can click the back button and return to where they were in the app:

That about does it for basic sharing functions for your app. You do not need to include any permissions in the bar-descriptor.xml as you are calling (invoking) a card of another app. Go ahead and get creative of things to share from you app: high scores, favorite something, links to somewhere, important messages, etc... Most importantly now that you know how easy this is, be sure to add share functionality to all your apps!

Read more