BlackBerry WebWorks 2.2 Development Guide Published: 2015-03-13 SWD-20150313105458214 Contents Getting Started ........................................................................................................................................... 5 What's a BlackBerry WebWorks app?..............................................................................................................5 Components of the BlackBerry 10 WebWorks SDK..........................................................................................7 Setting up your system................................................................................................................................. 12 Creating a WebWorks project........................................................................................................................21 Creating your first app.................................................................................................................................. 24 Porting and Upgrading...............................................................................................................................27 Upgrading from WebWorks 1.0.....................................................................................................................27 Updating your WebWorks project................................................................................................................. 34 Porting from Cordova................................................................................................................................... 35 Porting to other platforms.............................................................................................................................37 Porting AIR apps to WebWorks..................................................................................................................... 38 Adding Features........................................................................................................................................ 43 Adding and removing plugins....................................................................................................................... 43 Using custom plugins...................................................................................................................................48 Modifying your app configuration..................................................................................................................56 Creating headless WebWorks apps............................................................................................................. 108 App integration.......................................................................................................................................... 114 BBM Social Platform.................................................................................................................................. 225 Payment Service........................................................................................................................................ 232 Push Service.............................................................................................................................................. 247 Frameworks.............................................................................................................................................267 jQuery ....................................................................................................................................................... 267 Sencha Touch 2.........................................................................................................................................270 Dojo Toolkit................................................................................................................................................272 Enyo 2.0.................................................................................................................................................... 275 Construct 2................................................................................................................................................277 bbUI toolkit................................................................................................................................................ 281 Building and Testing................................................................................................................................ 283 Setting up test targets................................................................................................................................ 283 Previewing your app in a browser................................................................................................................286 Building your app in debug mode............................................................................................................... 286 Deploying your app to a simulator...............................................................................................................287 Deploying your app to a device................................................................................................................... 289 Debugging using Web Inspector................................................................................................................. 292 Testing and debugging apps in the work space .......................................................................................... 315 Building and signing your completed app................................................................................................... 316 Distributing your app..................................................................................................................................321 Best Practices......................................................................................................................................... 323 UI guidelines..............................................................................................................................................323 Personally identifiable information..............................................................................................................323 HTML best practices.................................................................................................................................. 324 CSS best practices..................................................................................................................................... 331 JavaScript best practices........................................................................................................................... 336 Legal notice............................................................................................................................................. 347 Getting Started Learn what HTML5 and the Cordova for BlackBerry platform have to offer, and build your first app. In this section, you can find resources to help you get started developing applications for the BlackBerry WebWorks platform. What's a BlackBerry WebWorks app? A BlackBerry WebWorks app is a web application that runs on a BlackBerry device. As of BlackBerry WebWorks 2.0, the BlackBerry 10 WebWorks SDK is now built on Apache Cordova, an open- source development framework that lets you create applications using web technologies. Be sure to check out some of the BlackBerry WebWorks Samples. Although adopting Cordova as the development standard has resulted in some changes to the way WebWorks applications are structured, the process is not complicated. Creating a BlackBerry WebWorks app involves the following high-level steps: 1. Create your project: Use the BlackBerry 10 WebWorks SDK web tool or the command line tool to create the folder structure and template files for your new WebWorks project. 2. Design and develop your app logic and resources: Create the HTML, CSS, JavaScript files and other resources, or reuse existing ones, and save them in the appropriate locations in your project's /www folder. 3. Add the required plugins: A plugin represents a set of APIs that allow your app to access the features of the platform by binding the JavaScript functions to the native methods of the device code. 4. Build and test your app: Use the web tool or the command line to test your app in a simulator or on a device. 5. Distribute your app: Build and sign your completed app and submit it to BlackBerry World. Why create a BlackBerry WebWorks app? Some reasons to consider are: • portability • integration with core BlackBerry apps • ease of access, even when users do not have an Internet connection available Portability Because you create them using common web standards, BlackBerry WebWorks apps are not platform- dependent. When you port to other mobile platforms, such as iOS or Android, you can reuse many of your existing web assets. By aligning with Apache Cordova for BlackBerry WebWorks 2.0, your WebWorks apps will now have an even greater level of compatibility. Cordova provides a common development layer, and makes adapting the output Getting Started 5 to multiple mobile platforms much simpler. You create an app using the languages you know, and Cordova handles the bindings to the native layer of the various platforms. You can also take advantage of popular mobile web frameworks, such as Sencha Touch, jQuery Mobile, Dojo, and others. These frameworks provide a wide range of useful APIs