In-App Purchases Made Simple

The process of adding in-app purchases to a Cascades app has proven daunting for many of you out there, but today I will attempt to make life easier for all of you.  About 6 months ago, when I first attempted to add in-app purchases to a Cascades app, there was a lot of head scratching and staring at the screen, but eventually it clicked well enough for me to implement.  After that, I spent a lot of time really wrapping my head around the code, and I am finally at a point where I can simplify the presentation of this code. Interested? Keep reading...


Basic Web Browser in Cascades

So, it's been a while since I have been able to get any code together for you guys, but now that MockIt! has launched officially, I should have time to get some posts together (big post coming within a few days!).  Also, Brandon Orr (@elbranduco) will be getting some awesome tutorials together for you Cascades devs.

Today, I made a small project for a friend of mine, and thought some of you might find it helpful.  The app is a simple one page web browser built in Cascades.


JavaScript Functions and Preserving Data

Cascades is a framework built on top of Qt, a C++ application framework. Qt allows for fantastic user interfaces with a custom language based on JavaScript called QML, or Qt Modeling Language. Not only is QML based on the structure of JavaScript, but it allows us to use JavaScript in our code.

Coming from a web design background, I have almost ZERO experience with C++. I'm not saying it's difficult to use or challenging, I'm just personally not use to it. When I learned that I can opt for JavaScript to do simple functions instead of C++ I was ecstatic, I just wasn't sure where to start.

In this tutorial I'm going to walk you through making a random number generator using some JavaScript MATH functions as well as creating our own.


Keeping it pithy: Toasts in Cascades

What is a toast? Well according to BlackBerry...

"A SystemToast displays a small message that expires and disappears after a predefined amount of time. This message provides users with information and allows them to continue with the application after the toast expires."

You've seen toasts when you clear your browser history or delete an attachment from a BBM and in many other places throughout BlackBerry 10. When dealing with toasts and any other user prompts, developers need to be cognizant of the user experience and of the fact that users typically do not want to be interrupted (at least not too frequently).


Getting Started with BBUI.js



In this tutorial, we will get to know the basic structure of BBUI.js. Recently, I developed an app, Crochet Buddy HD, for PlayBook using BBUI.js for UI elements. to developp the app, I essentially only used the actionbarlist,&nbspbuttons, andscreen;elements when creating the UI.  Below, we will create a sample BBUI.js app using some of these elements

Before diving in, it is important to become familiar with some of the main features of BBUI.js. First, the action bar...

UI Elements: The ‘Action Bar’

The Action Bar in BBUI.js

The action bar is the primary navigation "dock" for the typical BBUI.js based app.  Buttons, tabs, and other elements can be placed on the action bar and various actions can be assigned to the action bar elements.

In Crochet Buddy HD, I created four action bar buttons. Each panel/page in my app resides in it's own .htm file.  To keep everything contained within the BBUI framework, each button does not simply link to the .htm file of the corresponding page. Each item on the action bar is defined as a data-bb-type="action", so look at the code below:


<div data-bb-type="screen" data-bb-scroll-effect="on"> [Page HTML code goes here] <div data-bb-type="action-bar"> <div data-bb-type="action" data-bb-style="button" data-bb-img="images/actionBar/cog_dark_theme.png" onclick="bb.pushScreen('HTML_File.htm');" data-bb-title="Action Title">Text Under Button</div> </div>


In the code sample above, you have one panel of an app. just before closing the div, you can see we inserted an action bar and defined one button, that when activated  will load 'HTML_file.htm'.

The code in 'HTML_file.htm' will look very similar to the code above, but I will change the action bar.  See code sample below:


<div data-bb-type="screen" data-bb-scroll-effect="on"> [Page HTML code goes here] <div data-bb-type="action-bar"> <div data-bb-type="action-bar" data-bb-back-caption="Back"></div> </div>


When you define data-bb-back-caption="Back" in the action bar as we did in the above sample, the result is a blank action bar with a functioning back button (see image below)

Action bar with 'back' button

So, as you would expect, when the 'back' button is tapped, you will return to the previous panel.

UI Elements: Lists

There are 2 lists types that can be called within BBUI,js:

  • Arrow Lists
  • Image Lists
  • Grid Lists

Each lists has it's own look and feel (see image below).

To use the various list type in your app, you simply create a div define the list type using the attribute bb-data-type="list type goes here" and create the items in the list. Check out the code sample below:

<div data-bb-type="text-arrow-list">  <div data-bb-type="item" onclick="alert('click')">Sleepy</div>  <div data-bb-type="item" onclick="alert('click')">Sneezy</div>  <div data-bb-type="item" onclick="alert('click')">Dopey</div>  <div data-bb-type="item" onclick="alert('click')">Grumpy</div>  <div data-bb-type="item" onclick="alert('click')">Doc</div>  <div data-bb-type="item" onclick="alert('click')">Bashful</div> <div data-bb-type="item" onclick="alert('click')">Happy</div> </div>

 In the above sample code, we created an arrow-list and the individual items contained within that list. With BBUI.js it really is simple to create UI elements.

Building a sample application

Now that the basics have been discussed, we can build a simple sample BBUI.js application.

Before getting started, there are a couple of things you will need:

  • Download BBUI.js from GitHub here
  • A good IDE or Editor. I prefer Notepad++ which can be downloaded here

Once you have BBUI.js downloaded, unzip the contents. Locate the 'samples' directory and copy and paste it into it's own directory outside of the BBUI.js directory (I copied the samples directory to MyDocuments\bbuiapp1).

Once you have the samples directory in the desired location open up the folder and locate the index.htm file with your favorite text editor.


<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"> <!-- * Copyright 2010-2011 Research In Motion Limited. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. --> <html>  <head> <meta name="x-blackberry-defaultHoverEffect" content="false" /> <meta name="viewport" content="initial-scale=1.0,width=device-width,user-scalable=no,target-densitydpi=device-dpi" /> <link  rel="stylesheet" type="text/css" href="/bbui-0.9.2.css"><link /> <script type="text/javascript" src="/bbui-0.9.2.js"></script> <script type="text/javascript"> // For some fun I did some random color scheme generation :o) var bb10HighlightColor, randomNumber; randomNumber=Math.floor(Math.random()*100); if (randomNumber > 60) {   bb10HighlightColor = '#BA55D3'; } else if (randomNumber > 30) {   bb10HighlightColor = '#00BC9F'; } else {   bb10HighlightColor = '#00A8DF'; } // You must call init on bbUI before any other code loads.   // If you want default functionality simply don't pass any parameters.. bb.init(); bb.init({bb10HighlightColor: bb10HighlightColor, bb10ActionBarDark: true, bb10ControlsDark: true, bb10ListsDark: false, bb10ForPlayBook: true, // Fires "before" styling is applied and "before" the screen is inserted in the DOM onscreenready: function(element, id) { if (id == 'dataOnLoad') { dataOnLoad_initialLoad(element); } // Remove all titles "except" input and pill buttons screen if running on BB10 if (bb.device.isBB10 && id != 'input' && id != 'pillButtons') { var titles = element.querySelectorAll('[data-bb-type=title]'); if (titles.length > 0) { titles[0].parentNode.removeChild(titles[0]); } } }, // Fires "after" styling is applied and "after" the screen is inserted in the DOM ondomready: function(element, id) { if (id == 'dataOnTheFly') { dataOnTheFly_initialLoad(element); } } }); </script> </head> <body onload="bb.pushScreen('menu.htm', 'menu');"> </body> </html>


You will notice that the index.htm file contains the standard <head> with stylesheets and javascript.

In the <body> of the document bb.pushScreen() is used to load the intital landing page for your app.

Now let's build a page.

Browse back to the 'samples' directory containing the index.htm and delete all other .htm files except for index.htm (don't worry these files are still on your HDD in the BBUI.js directory you extracted earlier) IMPORTANT: Only delete the .htm files, leaving the directories, CSS, and JS files untouched.

Open your favorite text editor and create a new .htm file in the samples directory with the name: home.htm (this will be the very first screen visible when your application is launched)

The structure of each page will be similar, for home.htm use the following:


<div data-bb-type="screen" data-bb-effect="fade"> <div style="height:175px; width:550px;margin: 0px auto 0px auto;"> <h1 style="height:12%; text-align:center; padding-top:3%;">App Title or Image</h1> </div> <h2>Please choose an item below</h2> <div data-bb-type="image-list" data-bb-image-effect="fade"> <div data-bb-type="item" onclick="bb.pushScreen('calculator.htm', 'calculator');"data-bb-img="images/icons/icon4.png" data-bb-title="Calculator">A simple function calculator</div> <div data-bb-type="item" onclick="bb.pushScreen('slider.htm', 'slider');" data-bb-img="images/icons/icon3.png" data-bb-title="Slider">Example of a Slider</div>  <div data-bb-type="item" onclick="bb.pushScreen('table.htm', 'table');"data-bb-img="images/icons/icon2.png" data-bb-title="Table Example">An example of a formatted table</div> </div> <div data-bb-type="action-bar"> <div data-bb-type="action" data-bb-style="button" data-bb-img="images/actionBar/cog_dark_theme.png" onclick="bb.pushScreen('action1.htm', 'action1');">Action 1</div> <div data-bb-type="action" data-bb-style="button" data-bb-img="images/actionBar/cog_dark_theme.png" onclick="alert('You clicked Action 2. This could trigger an alert or load a page, or any other action you wish');">Action 2</div> </div> </div>


Save this file in the root directory (same directory as index.htm).

Now that we have a landing/home page for our app, we need to open index.htm and have it point to the home page.

In index.htm change


<body onload="bb.pushScreen('menu.htm', 'menu');"> </body>




<body onload="bb.pushScreen('home.htm', 'home');"> </body>


Now, save and close index.htm

Once the app is packaged, the steps above will result in the following (click image for larger view):


Adding Content

Within the code in home.htm, you will notice that some of the buttons and list items point to .htm files we have not yet created. Each of those pages can contain any HTML code you wish, but should follow the structure below:


<div data-bb-type="screen" data-bb-effect="fade"> {your html code here} <div data-bb-type="action-bar" data-bb-back-caption="Back"></div> </div>


 The content should be wrapped in <div data-bb-type="screen"> </div>. Essentially,  each .htm page will be treated as a <div> within index.htm.  So, when you use onclick="bb.pushScreen();" the content of that page is loaded within the BBUI.js wrapper.

Other than the index.htm and home.htm files we have already discussed, the following pages need to be created:

In the above bullet list, click any of the pages to see the associated code.

Prior to being able to package your app, you will need to creat a config.xml file.

More information about the config.xml file can be found here.

The config.xml should be formatted as follows:


<?xml version="1.0" encoding="utf-8"?> <!-- * Copyright 2010-2011 Research In Motion Limited. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. --> <widget xmlns=""         xmlns:rim=""         version="" id="bbuijssample">   <name>Sample BBUI app</name>   <description>App description</description>   <author>Your Name</author>   <icon src="/images/icon.png" />     <rim:permissions> <rim:permit>access_shared</rim:permit> </rim:permissions>   <rim:orientation mode="portrait" />   <content src="/index.htm" />            <feature id="" required="true" version="1.0.0" />    <feature id="blackberry.invoke" required="true" version="1.0.0"/>    <feature id="blackberry.identity" required="true" version="1.0.0"/>    <feature id="blackberry.ui.dialog" required="true" version="1.0.0"/>    <feature id="blackberry.ui.dialog"/>    <feature id="" required="true" version=""/>    <access subdomains="true" uri="*"/>   </widget>


 Included in the assests archive (available for download at the end of this post) are all the files that we create in this tutorial--including and icon. However, if you wish you can create and 86 x 86 PNG icon and save it as "icon.png" in the "images" directory for the app.

Important: For the purposes of this tutorial, many images and other files were not removed from the original BBUI.js files downloaded earlier in the tutorial. Many of these files are not needed, but for the purposes of this tutorial there really is no harm in leaving those files in place.  

With all the files in place you can now package this app. Since we are targeting PlayBook with this app, the Tablet OS Webworks packager should be used.

Note: Included in the assets archive (available for download below) is a presigned .bar file that can be sideloaded onto your PlayBook. I included this to provide a reference for how the app created in this tutorial should look and function.

For help compiling and installing this application on your PlayBook, please see the following information from RIM: HERE

To download all the files used in this tutorial click the button below:


Subscribe to this RSS feed
Subscribe to the official OSBB BBM Channel!



Back to top