Cordova BlackBerry Distribution
===============================

Cordova BlackBerry is a framework that allows for Cordova based projects to be built for the [BlackBerry WebWorks Platform](https://bdsc.webapps.blackberry.com/html5/). Cordova based applications are, at the core, an application written with web technology: HTML, CSS and JavaScript.  The Cordova BlackBerry project allows web developers to develop applications targeting BlackBerry OS 5.0+ and PlayBook devices using the common [Cordova API](http://docs.phonegap.com).

Apache Cordova is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by the Apache Incubator project. Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF.

Pre-requisites
--------------

- Windows XP (32-bit) or Windows 7 (32-bit and 64-bit) or Mac OSX 10.6.4+
- Java JDK 1.5
- Apache ANT
- [BlackBerry WebWorks SDK](https://bdsc.webapps.blackberry.com/html5/download/sdk)
- PlayBook development requires [Adobe Air SDK](http://www.adobe.com/devnet/air/air-sdk-download.html)

Directory Structure
-------------------

    sample/ ... Ready-to-run sample project
    www/ ...... Barebones project assets

### Ready-to-Run Sample Project

The quickest way to get started with Cordova BlackBerry is to make a copy of the `sample` folder. The `sample` folder is a complete Cordova BlackBerry project including build scripts. Copy the `sample` folder to a desired location to create a new Cordova BlackBerry project.

#### Building and Deploying a Project

The build scripts included in the `sample` folder automate common tasks, such as compiling your project, and deploying it to simulators or devices.  To see what options are available, use:

    $ cd C:\development\my_new_project
    $ ant help

Every command is in the form `ant TARGET COMMAND [options]`, where
target is either `blackberry` or `playbook`.

To build your project into a deployable application (.cod/.jad) file:

    $ ant TARGET build

To build your project and load it in a BlackBerry simulator:

    $ ant TARGET load-simulator

To build your project and load it onto a USB-attached device:

    $ ant TARGET load-device

### Barebones Project Assets

The `www` folder contains the Cordova specific assets that must be available in a BlackBerry WebWorks project.  If you have an existing BlackBerry WebWorks project, copy/merge these files into your project to enable the project for Cordova.

    ext/cordova.jar     - Native Cordova API implementations for smartphones.
    ext-air/            - PlayBook Adobe Air extensions for Cordova API.
    playbook/cordova.js - PlayBook Cordova JavaScript API.
    cordova.js          - Smartphone Cordova JavaScript API.
    config.xml          - BlackBerry WebWorks configuration file.
    plugins.xml         - Cordova plugin configuration file.

`config.xml` is a sample that you are free to alter or merge with an existing BlackBerry WebWorks configuration file. The necessary Cordova sections are contained in the `<feature>` and `<access>` sections:

    <!-- Cordova API -->
    <feature ... />
    <feature ... />
    
    <!-- Cordova API -->
    <access ... />
    <access ... />

Frequently Asked Questions
--------------------------

__Q: My simulator screen is not refreshing and I see blocks on a clicked position.__

__A:__ Windows 7 and the simulator's graphics acceleration do not mix. On the simulator, set View -> Graphics Acceleration to Off.

__Q: When I use the Cordova [Camera.getPicture API](http://docs.phonegap.com/phonegap_camera_camera.md.html#camera.getPicture) on my device, the camera never returns to my application.  Why does this happen?__

__A:__ Cordova uses a JavaScript Extension to invoke the native camera application so the user can take a picture.  When the picture is taken, Cordova will close the native camera application by emulating a key injection (pressing the back/escape button).  On a physical device, users will have to set permissions to allow the application to simulate key injections.  Setting application permissions is device-specific.  On a Storm2 (9550), for example, select the BlackBerry button from the Home screen to get to All Applications screen, then Options > Applications > Your Application.  Then select Edit Default Permissions > Interactions > Input Simulation and set it to 'Allow'.  Save your changes.

__Q: None of the Cordova APIs are working, why is that?__

__A:__ You probably need to update your plugins.xml file in the root of your application.

Additional Information
----------------------
- [Cordova home](http://incubator.apache.org/cordova/)
- [Cordova Documentation](http://docs.phonegap.com)
- [Cordova Issue Tracker](https://issues.apache.org/jira/browse/CB)
- [BlackBerry WebWorks Framework](https://bdsc.webapps.blackberry.com/html5/)