Weekend Coder: Invoke the share card

By Brian Scheirer on 26 May 2013 05:28 pm EDT

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!

Reader comments

Weekend Coder: Invoke the share card


Is their a possibility that we BlackBerry 10 are going to have the feature in Facebook that a BUBBLE appear when someone send you a msg? Like in iOS or like the new Facebook Home?

Posted via CB10 on Z10

That's what the blinking led light, hub and ability to swipe and multitask and send messages is for, all without ever leaving your app. No need for childish bubbles. It's the whole premise behind the new os.

Posted via CB10


But more than that is a solid recommendation of where people can go to understand the basics of the code to start from scratch.

Posted via CB10

But the code is in a screen shot so it's too small to view in Cb10 app. Using plain test like the rest of your article is best.

Come to think about it, is there a standard CODE box similar to what quotes does on this and many other sites that is standard?

Great article and keep these basics coming please. I'm now inspired. I have the SDK installed on my Mac, but I need a grasp on the basics. I have no photo shop skills to create color backgrounds and banners and icons and such unfortunately.

Posted via CB10

I believe BBM Channels will be the 4th shared standard to Facebook , Twitter , and Linked In, not the 4th place but The Fourth Shared Standard. Plus sharing on my Z10 is just awesome very very smooth vs iOS and Droid !

The ease of sharing is one of my favorite most productive features of BB10

From my sweet BB10 Neutrino powered Z10 :D

That really was a good idea taking you to  CB NYC HQ huh Brian!



Seriously great job on the series so far bro!

Hey, Brian! Thanks again. If anyone is to write the first cascades book in publication, it'll be you. Need more C++/Qt Stuff, though. I'm all over QML, suits most of my needs (including SQLite3 now, thankfully!).

Surprisingly, no C++/Qt for BlackBerry content nearly anywhere. It's like the powerful and smart cousin no one likes, no one invites over, for fear of feeling less intelligent.

Posted via CB10

I've toyed with the idea of a book, we shall see though.... On the note of C++ and Qt... There's not much of a reason to use C++ for anything unless it absolutely can't be done in QML or Qt. So honestly I don't use it much either. For Qt, there's a few classes that I use and I will work them into some tutorials coming up. Because it is really powerful and pretty easy to use.