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!



Cool post. Need more like it to drive some more people to becoming devs.

Posted via CB10

Jeandry Brito

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


I'm embarrassed

Posted via CB10

Plazmic Flame

You've learned something new. Nothing wrong with learning.



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


That's what she said (almost)

Posted via CB10

Brian Scheirer

Sorry it is just small on the app, only way to show code in plain text. Looks fine on the desktop site.


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


Is that a pink Z10? How do you have that?

Posted via CB10


sure that is the red limited edition developers device. and thanks for the post brian.


Reading this, I'm assuming that developers have a harder time doing this with iDroid?


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



Seriously great job on the series so far bro!

Brian Scheirer

Shhh don't give away the truth on how business deals are really done, lol


I want to start coding.

Posted via CB10


I can read it u must of had q10's as z10 was fine for that post, strange

Posted via CB10


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

Brian Scheirer

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.


Awesome!! Getting this working in my app just made me do cartwheels LOL.. Thanks Brian! :)