For Mac users looking to get into developing WebWorks 2.0 and Cordova plugins for BlackBerry 10, this guide written by one of our students from the UCOSP program will get you started. Although this tutorial is written for OSX users, most of the information found here can be applied to other platforms as well. This is the first in a series of three articles on writing plugins for the new WebWorks 2.0 SDK. Next will be for the Linux platform, and the final one will be about writing plugins on Windows.
Step 1: Install the required tools
To begin developing plugins for the BlackBerry 10 Cordova platform, you will need the following tools:
- BlackBerry10 Webworks 2 SDK
- VMware Fusion (only if you want to run a simulator) (optional; paid/demo)
- Momentics IDE for BlackBerry 10
- git
- SourceTree (git GUI for OSX) (optional; free)
Step 2: Get a signing key and developer certificate, and sign the contributor agreement
You will need to request a signing key from BlackBerry if you plan on publishing an application to BlackBerry World or run an application on a real device (required to generate a debug token). You will find a tutorial on how to accomplish this on the BlackBerry Developer website. Note: a Developer Certificate can be generated from Momentics if you have it installed under “Momentics > Preferences > BlackBerry > Signing.” You still need to request a signing key from BlackBerry, but using Momentics makes it easier to manage your key and debug token.
To contribute to BlackBerry’s open source projects, you need to sign a Contributor’s agreement (required PDFs are available as links in the Code Contributions section). This is an agreement regarding code property, licensing and other legal matters. You should see your name appear on the Approved Signatories page soon after you sent the signed agreement back to BlackBerry.
Step 3: Learn about the development process of a BlackBerry 10 application
Understanding the development process of an application using Cordova and WebWorks is essential before you begin to develop plugins. There is a complete step-by-step tutorial available on the BlackBerry Developer website.
Step 4: Learn how to use Git and GitHub
BlackBerry maintains a public repository called WebWorks-Community-APIs on GitHub. This is where you will want to upload your plugins once they are completed, so you will need to use Git and GitHub. If you do not have a GitHub account, go ahead and create one.
For the rest, here are a few tutorials about Git and GitHub. You do not need to master every detail about Git, but a basic knowledge is required in order to work efficiently:
- Git Documentation
- GitHub Help
- Git – Tutorial
- Got 15 minutes and want to learn Git?
- GitHub & Git Video Tutorials
Step 5: Analyze the Blackberry 10 Cordova plugin template and get it to run
Tim Windsor from BlackBerry developed a template for BlackBerry 10 Cordova plugins. It is a basic plugin and sample application that is meant to be used as the foundation of every new plugin developed for BlackBerry 10 Cordova. The Readme contains a lot of information, shows the end-to-end communication process and, most importantly, it is kept up to date.
Step 6: Know where to find information
You are almost ready to develop your first plugin with just one more crucial piece: documentation. Since there are two completely separated sides to a plugin (Cordova/Javascript and Native/C++) joined by a communication framework (JNEXT), documentation will be found in different places.
- BlackBerry development
- Information can be found on BlackBerry’s github.io page
- #BlackBerryDev on irc.freenode.net
- Cordova/Webworks
- Cordova is owned by the Apache Foundation and is completely open-source. The platform used to be called PhoneGap before it was given to the Apache Foundation. PhoneGap still exists today, so make sure that you the information you find is about Cordova and not PhoneGap.
- The Cordova official documentation is well written, but at times can be incomplete.
- The Cordova Plugin Development Guide is a must-read and must-use for anything moderately complex. The BlackBerry part of the guide is the most relevant for us.
- The BlackBerry APIs reference is where you will find the documentation about the BlackBerry WebWorks APIs as well as Cordova APIs.
- Take a look at the WebWorks 2.0 Sample applications, complete with source code.
- Native
- BlackBerry Native SDK Core APIs reference
- Take a look at the BlackBerry Native SDK Sample Apps
- JNEXT
- Unfortunately, documentation for JNEXT is very scarce and hard to find. Fortunately, pretty much everything you will ever need from JNEXT is documented and implemented in the Template.
Step 7: Plugin structure: end-to-end communication
Plugins, as you probably know by now, have two aspects: a Cordova/Webworks part and a Native part. If you need some inspiration on how to get started, the Template and the other plugins present in the BB10-Cordova repository are where you will find the best samples available.
The end-to-end communication requires some time to get used to as multiple layers are involved. Keep the following important files in sight:
1. Javascript file(s) at the application layer, usually found at “sample/www/js/index.js”
a. This is where you will put your scripts that interact with the DOM and call the different plugins you have included in your application. This is the first layer of the front-end. Since this is located at the application layer, this file will most likely be heavily customized in every application the plugin is used to, so do not put any plugin logic in that file.
2. Javascript file used to expose the API of the plugin, must be found at “plugin/www/client.js”
a. This is where the plugin front-end representation is created and registered the plugin with Cordova, which in turns makes it available to the application.
b. This is also where you will use the Cordova bridge (through the “exec” function) to make calls to the last Javascript layer.
3. Javascript file used to map Javascript function calls to Native function calls. Must be found at “plugin/src/blackberry10/index.js”. This file contains two parts:
a. A part where the receiving end of every function that needs to be called using the Cordova “exec” function is defined
b. A part where JNEXT is used to map every function call to a native call
4. Compiled native plugin, usually found at “plugin/src/blackberry10/native/[device|simulator]/libPluginName.so
a. libPluginName.so is a name format encouraged by the Template. The actual .so file name and path are defined in a configuration file (see Step 8), so it could really be named anything and located elsewhere. However, always keep in mind that standard names and paths are a good thing.
b. This .so file is compiled from 2 C++ files and their associated header file:
i. pluginname_js.cpp and pluginname_js.hpp
1. Implements the native side of the JNEXT function calls. Used as a bridge between the Javascript side of JNEXT and the native side of the plugin
2. Also creates a WebWorks Logger object if needed. Very useful to debug runtime errors
ii. pluginname_ndk.cpp and pluginname_ndk.hpp
1. This is where is implemented the native side of the plugin
So to resume all of the layers:
Step 8: Plugin structure: configuration fileUnderstanding exactly how the layers interact with one another is probably the biggest part of learning how to develop plugins for Cordova. However, once you have an understanding of this, working with the different layers is fairly straightforward and there is no ambiguity as to where a piece of code should go.
Every plugin contains a configuration file called plugin.xml. This xml file is used by Cordova to correctly load the plugin and its dependencies. Information about the plugin.xml file can be found on the Cordova Plugin Specification page.
An application that wants to use a plugin needs to specifically reference it in its config.xml file, along with the special features and permissions required. These permissions and features should be provided by the plugin’s developers.
Step 9: Debugging: Native
To debug a native application at runtime, the best tool to use the Logger class, which is available in the Template (Logger.hpp and Logger.cpp). The Logger class is defined in the pluginname_js.hpp file, and is instantiated in the pluginname_js.cpp file. A helper method called “getLog” is also created to allow access from the plugin’s native side.
To see the Logger output, you need to have Momentics installed. Within Momentics, open the “Target Navigator” panel found in “Window > Show View > Target Navigator.” Then, right click on the target you are using and click “Connect.” Finally, right click on the target and click “Open Device Log.”
Step 10: Debugging: JavaScript
It is possible to debug the JavaScript side of an application or of a plugin through web consoles. Simply open a web browser and enter the device’s IP address (available at the bottom left of the screen for a simulator, and from the “Development Mode” menu for a real device) followed by “:1337”. So, for example, if my device’s IP address (while connected through USB to my computer) is 169.254.0.1, I would access its web consoles from http://169.254.0.1:1337.
Note that an application must be running for this to work. Three consoles should then be available, each one logging a different layer of the JavaScript side. The consoles do not have to be closed when an application is reloaded, but the windows need to be refreshed.
Step 11: Final tips
When developing a plugin in parallel with a sample application, it is important to keep in mind that the plugin needs to be reimported in the sample application every time a change occurs inthe native, the JavaScript or the xml files. If you use the “webworks” or the “cordova” command line interface, you can create a simple script that removes the plugin, adds it and then runs the application. It takes only a few seconds to create and saves a lot of time in the long run.
The creation process of a run script looks something like this:
Create run file in the “sample” folder:
“touch run”
Edit file and add commands:
“webworks plugins remove community.templateplugin”
“webworks plugins add ../plugin”
“webworks run”
Change file permissions to make it executable:
“chmod u+x run”
Execute the run script :
“./run”
You should now have all the tools you need to begin plugin development for BlackBerry 10 using Cordova and WebWorks APIs on OSX.
If you’re interested in contributing to our BlackBerry repositories on GitHub, we’d appreciate your input. Contact me to get started at @timothywindsor or on GitHub.