Upgrading BlackBerry 10
This guide shows how to modify BlackBerry projects to upgrade from older versions of Cordova.
Most of these instructions apply to projects created with an older set
of command-line tools that precede the cordova
CLI utility. See The Command-Line Interface for information how to update the
version of the CLI.
Upgrading 3.6.0 Projects to 4.0.0
For non-CLI projects, run:
bin/update path/to/project
For CLI projects:
-
Update the
cordova
CLI version. See The Command-Line Interface. -
Run
cordova platform update blackberry
in your existing projects.
Upgrading to 3.2.0 from 3.1.0
For projects that were created with the cordova CLI:
-
Update the
cordova
CLI version. See The Command-Line Interface. -
Run
cordova platform update blackberry
For projects not created with the cordova CLI, run:
bin/update <project_path>
Upgrade to 3.1.0 from 3.0.0
-
Create a new Apache Cordova 3.1.0 project using the cordova CLI, as described in The Command-Line Interface.
-
Add your platforms to the cordova project, for example:
cordova platform add blackberry10
. -
Copy the contents of the original project's
www
directory to thewww
directory at the root of the cordova project you just created. -
Copy or overwrite any native assets from your original project (
Resources
, etc.) -
Copy the
config.xml
file into thewww
directory, and remove any plugin definitions. You need to modify settings here rather than within the platform directory. -
Use the cordova CLI tool to install any plugins you need. Note that the CLI handles all core APIs as plugins, so they may need to be added. Only plugins marked 3.0.0 and above are compatible with the CLI.
-
Build and test.
Please note that the CLI supports the BlackBerry10 platform exclusively. For PlayBook and BBOS, please see Cordova version 2.9.0 and below.
Upgrade to the CLI (3.0.0) from 2.9.0
-
Create a new Apache Cordova 3.0.0 project using the cordova CLI, as described in The Command-Line Interface.
-
Add your platforms to the cordova project, for example:
cordova platform add blackberry10
. -
Copy the contents of the original project's
www
directory to thewww
directory at the root of the cordova project you just created. -
Copy or overwrite any native assets from your original project (
Resources
, etc.) -
Copy the
config.xml
file into thewww
directory, and remove any plugin definitions. You need to modify settings here rather than within the platform directory. -
Use the cordova CLI tool to install any plugins you need. Note that the CLI handles all core APIs as plugins, so they may need to be added. Only 3.0.0 plugins are compatible with the CLI.
-
Build and test.
Upgrading 2.8.0 Projects to 2.9.0
For BlackBerry 10:
-
Download and extract the Cordova 2.9.0 source to a permanent directory location on your hard drive, for example to
~/Cordova-2.9.0
. -
Quit any running SDK tools: Eclipse, Momentics and the like.
-
Navigate to the directory where you put the downloaded source above, using a unix like terminal: Terminal.app, Bash, Cygwin, etc.
-
Create a new project, as described in BlackBerry Shell Tool Guide. This becomes the home of your updated project.
-
Copy your projects source from the old project's
/www
directory to the new project's/www
directory. -
Update the Cordova script reference in the
www/index.html
file (and any other files that contain the script reference) to point to the newcordova.js
file.
For BlackBerryOS/Playbook:
-
Download and extract the Cordova 2.9.0 source to a permanent directory location on your hard drive, for example to
~/Cordova-2.9.0
. -
Quit any running SDK tools: Eclipse, Momentics and the like.
-
Navigate to the directory where you put the downloaded source above, using a unix like terminal: Terminal.app, Bash, Cygwin, etc.
-
Create a new project, as described in BlackBerry Shell Tool Guide. You need the assets from this new project.
-
Copy the
www/cordova.js
file from the new project into thewww
directory, and delete thewww/cordova.js
file. -
Update the Cordova script reference in the
www/index.html
file (and any other files that contain the script reference) to point to the newcordova.js
file. -
Copy the
native
directory from the new project into the existing project, overwriting the oldnative
directory. -
Copy the
lib
directory from the new project into the existing project, overwriting the oldlib
directory. -
Copy the
cordova
directory from the new project into the existing project, overwriting the oldcordova
directory.
Upgrading 2.7.0 Projects to 2.8.0
BlackBerry 10 uses the new CLI tooling and manages core APIs as plugins. The instructions migrate your project to a new project, rather than updating an existing project, due to the complexity of updating an old project. Also note that the cordova js script file is now called 'cordova.js' and no longer contains a version string.
-
Download and extract the Cordova 2.8.0 source to a permanent directory location on your hard drive, for example to
~/Cordova-2.8.0
. -
Quit any running SDK tools: Eclipse, Momentics and the like.
-
Navigate to the directory where you put the downloaded source above, using a unix like terminal: Terminal.app, Bash, Cygwin, etc.
-
Create a new project, as described in BlackBerry Shell Tool Guide. This becomes the home of your updated project.
-
Copy your projects source from the old project's
/www
directory to the new project's/www
directory. -
Update the Cordova script reference in the
www/index.html
file (and any other files that contain the script reference) to point to the newcordova.js
file.
For BlackBerryOS/Playbook:
-
Download and extract the Cordova 2.8.0 source to a permanent directory location on your hard drive, for example to
~/Cordova-2.8.0
. -
Quit any running SDK tools: Eclipse, Momentics and the like.
-
Navigate to the directory where you put the downloaded source above, using a unix like terminal: Terminal.app, Bash, Cygwin, etc.
-
Create a new project, as described in iOS Shell Tool Guide. You need the assets from this new project.
-
Copy the
www/cordova.js
file from the new project into thewww
directory, and delete thewww/cordova.js
file. -
Update the Cordova script reference in the
www/index.html
file (and any other files that contain the script reference) to point to the newcordova.js
file. -
Copy the
native
directory from the new project into the existing project, overwriting the oldnative
directory. -
Copy the
lib
directory from the new project into the existing project, overwriting the oldlib
directory. -
Copy the
cordova
directory from the new project into the existing project, overwriting the oldcordova
directory.
Upgrading 2.6.0 Projects to 2.7.0
-
Download and extract the Cordova 2.7.0 source to a permanent directory location on your hard drive, for example to
~/Cordova-2.7.0
. -
Quit any running SDK tools: Eclipse, Momentics and the like.
-
Navigate to the directory where you put the downloaded source above, using a unix like terminal: Terminal.app, Bash, Cygwin, etc.
-
Create a new project, as described in BlackBerry Shell Tool Guide. You need the assets from this new project.
-
Copy the
www/cordova-2.7.0.js
file from the new project into thewww
directory, and delete thewww/cordova-2.6.0.js
file. -
Update the Cordova script reference in the
www/index.html
file (and any other files that contain the script reference) to point to the newcordova-2.7.0.js
file. -
Copy the
native
directory from the new project into the existing project, overwriting the oldnative
directory. -
Copy the
lib
directory from the new project into the existing project, overwriting the oldlib
directory. -
Copy the
cordova
directory from the new project into the existing project, overwriting the oldcordova
directory.
Upgrade to 2.6.0 from 2.5.0
Updating the PhoneGap download directory:
It is recommended that you download a fresh copy of the entire directory.
However, here are the new parts needed for the piecemeal update:
-
Update the cordova.blackberry.js file in the
Phonegap-2.6.0/lib/blackberry/javascript
directory. -
Update the
ext
,ext-air
, andext-qnx
in thePhonegap-2.6.0/lib/blackberry/framework
directory. -
Update the
build.xml
file in thePhonegap-2.6.0/lib/blackberry
directory. -
Update the
Phonegap-2.6.0/lib/blackberry/bin
directory. -
Update the
VERSION
file in thePhonegap-2.6.0/lib/blackberry
directory.
Updating the example/ directory or migrating an existing project:
-
Open the
www
directory, which contains the app. -
Remove and update the .jar file in the
ext/
directory. -
Update the contents of the
ext-air/
directory. -
Update the contents of the
ext-qnx/
directory. -
Copy the new
cordova-2.6.0.js
into your project. -
Update your HTML to use the new
cordova-2.6.0.js
file.
Upgrade to 2.5.0 from 2.4.0
Updating the PhoneGap download directory:
It is recommended that you download a fresh copy of the entire directory.
However, here are the new parts needed for the piecemeal update:
-
Update the cordova.blackberry.js file in the
Phonegap-2.5.0/lib/blackberry/javascript
directory. -
Update the
ext
,ext-air
, andext-qnx
in thePhonegap-2.5.0/lib/blackberry/framework
directory. -
Update the
build.xml
file in thePhonegap-2.5.0/lib/blackberry
directory. -
Update the
Phonegap-2.5.0/lib/blackberry/bin
directory. -
Update the
VERSION
file in thePhonegap-2.5.0/lib/blackberry
directory.
Updating the example/ directory or migrating an existing project:
-
Open the
www
directory, which contains the app. -
Remove and update the .jar file in the
ext/
directory. -
Update the contents of the
ext-air/
directory. -
Update the contents of the
ext-qnx/
directory. -
Copy the new
cordova-2.5.0.js
into your project. -
Update your HTML to use the new
cordova-2.5.0.js
file.
Upgrade to 2.4.0 from 2.3.0
Updating just the www
directory:
-
Open the
www
directory, which contains the app. -
Remove and update the .jar file in the
ext/
directory. -
Update the contents of the
ext-air/
directory. - Copy the new
cordova-2.4.0.js
into your project.- If playbook, then update the .js file in the
playbook/
directory. - If BlackBerry 10, then update the .js file in the
qnx/
directory.
- If playbook, then update the .js file in the
- Update your HTML to use the new
cordova-2.4.0.js
file.
Updating the sample directory (i.e., updating using the ant tools):
-
Open the
sample/lib/
directory. -
Update the .jar file in the
cordova.2.3.0/ext/
directory. -
Update the contents of the
cordova.2.3.0/ext-air/
directory. -
Update the contents of the
cordova.2.3.0/ext-qnx/
directory. -
Update the .js file in the
cordova.2.3.0/javascript/
directory. -
Open the
sample/lib/
directory and rename thecordova.2.3.0/
directory tocordova.2.4.0/
. -
Type
ant blackberry build
orant playbook build
to update thewww
directory with updated Cordova. -
Open the
www
directory and update your HTML to use the newcordova-2.4.0.js
file.
Upgrade to 2.3.0 from 2.2.0
Updating just the www
directory:
-
Open the
www
directory, which contains the app. -
Remove and update the .jar file in the
ext/
directory. -
Update the contents of the
ext-air/
directory. - Copy the new
cordova-2.3.0.js
into your project.- If playbook, then update the .js file in the
playbook/
directory. - If BlackBerry 10, then update the .js file in the
qnx/
directory.
- If playbook, then update the .js file in the
- Update your HTML to use the new
cordova-2.3.0.js
file.
Updating the sample directory (i.e., updating using the ant tools):
-
Open the
sample/lib/
directory. -
Update the .jar file in the
cordova.2.2.0/ext/
directory. -
Update the contents of the
cordova.2.2.0/ext-air/
directory. -
Update the contents of the
cordova.2.2.0/ext-qnx/
directory. -
Update the .js file in the
cordova.2.2.0/javascript/
directory. -
Open the
sample/lib/
directory and rename thecordova.2.2.0/
directory tocordova.2.3.0/
. -
Type
ant blackberry build
orant playbook build
to update thewww
directory with updated Cordova. -
Open the
www
directory and update your HTML to use the newcordova-2.3.0.js
file.
Upgrade to 2.2.0 from 2.1.0
Updating just the www directory:
-
Open the
www
directory, which contains the app. -
Remove and update the .jar file in the
ext/
directory. -
Update the contents of the
ext-air/
directory. - Copy the new
cordova-2.2.0.js
into your project.- If playbook, then update the .js file in the
playbook/
directory. - If BlackBerry 10, then update the .js file in the
qnx/
directory.
- If playbook, then update the .js file in the
- Update your HTML to use the new
cordova-2.2.0.js
file.
Updating the sample directory (i.e., updating using the ant tools):
-
Open the
sample/lib/
directory. -
Update the .jar file in the
cordova.2.1.0/ext/
directory. -
Update the contents of the
cordova.2.1.0/ext-air/
directory. -
Update the contents of the
cordova.2.1.0/ext-qnx/
directory. -
Update the .js file in the
cordova.2.1.0/javascript/
directory. -
Open the
sample/lib/
directory and rename thecordova.2.1.0/
directory tocordova.2.2.0/
. -
Type
ant blackberry build
orant playbook build
to update thewww
directory with updated Cordova. -
Open the
www
directory and update your HTML to use the newcordova-2.2.0.js
file.
Upgrade to 2.1.0 from 2.0.0
Updating just the www
directory:
-
Open the
www
directory, which contains the app. -
Remove and update the .jar file in the
ext/
directory. -
Update the contents of the
ext-air/
directory. - Copy the new
cordova-2.1.0.js
into your project.- If playbook, then update the .js file in the
playbook/
directory.
- If playbook, then update the .js file in the
- Update your HTML to use the new
cordova-2.1.0.js
file.
Updating the sample directory (i.e., updating using the ant tools):
-
Open the
sample/lib/
directory. -
Update the .jar file in the
cordova.2.0.0/ext/
directory. -
Update the contents of the
cordova.2.0.0/ext-air/
directory. -
Update the .js file in the
cordova.2.0.0/javascript/
directory. -
Open the
sample/lib/
directory and rename thecordova.2.0.0/
directory tocordova.2.1.0/
. -
Type
ant blackberry build
orant playbook build
to update thewww
directory with updated Cordova. -
Open the
www
directory and update your HTML to use the newcordova-2.1.0.js
file.
Upgrade to 2.0.0 from 1.9.0
Updating just the www
directory:
-
Open the
www
directory, which contains the app. -
Remove and update the .jar file in the
ext/
directory. -
Update the contents of the
ext-air/
directory. - Copy the new
cordova-2.0.0.js
into your project.- If playbook, then update the .js file in the
playbook/
directory.
- If playbook, then update the .js file in the
-
Update your HTML to use the new
cordova-2.0.0.js
file. -
Update the
www/plugins.xml
file. Two plugins changed their namespace/service label. Change the old entries for the Capture and Contact plugins from:<plugin name="Capture" value="org.apache.cordova.media.MediaCapture"/> <plugin name="Contact" value="org.apache.cordova.pim.Contact"/>
To:
<plugin name="Capture" value="org.apache.cordova.capture.MediaCapture"/> <plugin name="Contacts" value="org.apache.cordova.pim.Contact"/>
Updating the sample directory (i.e., updating using the ant tools):
-
Open the
sample/lib/
directory. -
Update the .jar file in the
cordova.1.9.0/ext/
directory. -
Update the contents of the
cordova.1.9.0/ext-air/
directory. -
Update the .js file in the
cordova.1.9.0/javascript/
directory. -
Open the
sample/lib/
directory and rename thecordova.1.9.0/
directory tocordova.2.0.0/
. -
Type
ant blackberry build
orant playbook build
to update thewww
directory with updated Cordova. -
Open the
www
directory and update your HTML to use the newcordova-2.0.0.js
file. -
Open the
www
directory and update theplugins.xml
file. Two plugins changed their namespace/service label. Change the old entries for the Capture and Contact plugins from:<plugin name="Capture" value="org.apache.cordova.media.MediaCapture"/> <plugin name="Contact" value="org.apache.cordova.pim.Contact"/>
To:
<plugin name="Capture" value="org.apache.cordova.capture.MediaCapture"/> <plugin name="Contacts" value="org.apache.cordova.pim.Contact"/>
- To upgrade to 1.8.0, please go from 1.7.0
Upgrade to 1.8.0 from 1.7.0
Updating just the www
directory:
-
Open the
www
directory, which contains the app. -
Remove and update the .jar file in the
ext/
directory. -
Update the contents of the
ext-air/
directory. - Copy the new
cordova-1.8.0.js
into your project.- If playbook, then update the .js file in the
playbook/
directory.
- If playbook, then update the .js file in the
-
Update your HTML to use the new
cordova-1.8.0.js
file. -
Update the
www/plugins.xml
file. Two plugins changed their namespace/service label. Change the old entries for the Capture and Contact plugins from:<plugin name="Capture" value="org.apache.cordova.media.MediaCapture"/> <plugin name="Contact" value="org.apache.cordova.pim.Contact"/>
To:
<plugin name="Capture" value="org.apache.cordova.capture.MediaCapture"/> <plugin name="Contacts" value="org.apache.cordova.pim.Contact"/>
Updating the sample directory (i.e., updating using the ant tools):
-
Open the
sample/lib/
directory. -
Update the .jar file in the
cordova.1.7.0/ext/
directory. -
Update the contents of the
cordova.1.7.0/ext-air/
directory. -
Update the .js file in the
cordova.1.7.0/javascript/
directory. -
Open the
sample/lib/
directory and rename thecordova.1.7.0/
directory tocordova.1.8.0/
. -
Type
ant blackberry build
orant playbook build
to update thewww
directory with updated Cordova. -
Open the
www
directory and update your HTML to use the newcordova-1.8.0.js
file. -
Open the
www
directory and update theplugins.xml
file. Two plugins changed their namespace/service label. Change the old entries for the Capture and Contact plugins from:<plugin name="Capture" value="org.apache.cordova.media.MediaCapture"/> <plugin name="Contact" value="org.apache.cordova.pim.Contact"/>
To:
<plugin name="Capture" value="org.apache.cordova.capture.MediaCapture"/> <plugin name="Contacts" value="org.apache.cordova.pim.Contact"/>