Author: bhiggins
Date: Tue Jul 30 03:35:29 2013
New Revision: 1508285
URL: http://svn.apache.org/r1508285
Log:
[CB-4347] Update bb10 platform guide
Modified:
cordova/site/public/docs/en/3.0.0/guide_platforms_blackberry10_index.md.html
cordova/site/public/docs/en/edge/guide_platforms_blackberry10_index.md.html
Modified:
cordova/site/public/docs/en/3.0.0/guide_platforms_blackberry10_index.md.html
URL:
http://svn.apache.org/viewvc/cordova/site/public/docs/en/3.0.0/guide_platforms_blackberry10_index.md.html?rev=1508285&r1=1508284&r2=1508285&view=diff
==============================================================================
---
cordova/site/public/docs/en/3.0.0/guide_platforms_blackberry10_index.md.html
(original)
+++
cordova/site/public/docs/en/3.0.0/guide_platforms_blackberry10_index.md.html
Tue Jul 30 03:35:29 2013
@@ -17,16 +17,18 @@
specific language governing permissions and limitations
under the License.
--><html lang="en">
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
-<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0,
user-scalable=no, width=device-width">
-<meta name="generator" content="joDoc">
-<title>Apache Cordova API Documentation</title>
-<link rel="stylesheet" type="text/css" href="index.css">
-<link rel="stylesheet" type="text/css" href="mobile.css" media="only screen
and (max-device-width: 1024px)">
-<link rel="stylesheet" type="text/css" href="prettify/prettify.css">
-</head>
-<body>
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+ <meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0,
user-scalable=no, width=device-width">
+ <meta name="generator" content="joDoc">
+
+ <title>Apache Cordova API Documentation</title>
+
+ <link rel="stylesheet" type="text/css" href="index.css">
+ <link rel="stylesheet" type="text/css" href="mobile.css" media="only
screen and (max-device-width: 1024px)">
+ <link rel="stylesheet" type="text/css" href="prettify/prettify.css">
+ </head>
+ <body>
<div id="header">
<h1><a href="index.html">Apache <strong>Cordova</strong>
Documentation</a></h1>
<small>
@@ -77,18 +79,21 @@
<option value="1.8.1">1.8.1</option>
<option value="1.7.0">1.7.0</option>
</optgroup>
-<optgroup label="Korean" value="kr"><option
value="2.0.0">2.0.0</option></optgroup></select></small>
+<optgroup label="Korean" value="kr"><option
value="2.0.0">2.0.0</option></optgroup></select>
+ </small>
</div>
<div id="subheader">
<h1>BlackBerry 10 Platform Guide</h1>
<small><select><option
value="BlackBerry%252010%2520Platform%2520Guide">BlackBerry 10 Platform
Guide</option>
<option value="BlackBerry%2010%20Platform%20Guide_requirements">Â Â Â Â Â Â -
Requirements</option>
-<option
value="BlackBerry%2010%20Platform%20Guide_setting_up_your_signing_keys">Â Â Â Â
  - Setting up your signing keys</option>
-<option value="BlackBerry%2010%20Platform%20Guide_creating_your_project">Â Â Â
   - Creating your project</option>
-<option
value="BlackBerry%2010%20Platform%20Guide_adding_and_managing_targets">Â Â Â Â
  - Adding and managing targets</option>
-<option value="BlackBerry%2010%20Platform%20Guide_building_your_app">Â Â Â Â Â
 - Building your app</option>
-<option value="BlackBerry%2010%20Platform%20Guide_deploying_an_app">Â Â Â Â Â
 - Deploying an app</option>
-<option
value="BlackBerry%2010%20Platform%20Guide_adding_and_managing_plugins">Â Â Â Â
  - Adding and managing plugins</option></select></small>
+<option
value="BlackBerry%2010%20Platform%20Guide_install_the_blackberry_native_sdk">Â
     - Install the BlackBerry Native SDK</option>
+<option value="BlackBerry%2010%20Platform%20Guide_set_up_for_signing">Â Â Â Â
  - Set up for Signing</option>
+<option value="BlackBerry%2010%20Platform%20Guide_create_a_project">Â Â Â Â Â
 - Create a Project</option>
+<option value="BlackBerry%2010%20Platform%20Guide_deploy_to_emulator">Â Â Â Â
  - Deploy to Emulator</option>
+<option value="BlackBerry%2010%20Platform%20Guide_deploy_to_device">Â Â Â Â Â
 - Deploy to Device
+</option>
+<option
value="BlackBerry%2010%20Platform%20Guide_debugging_with_webinspector">Â Â Â Â
  - Debugging with WebInspector</option>
+<option
value="BlackBerry%2010%20Platform%20Guide_building_a_release_version">Â Â Â Â Â
 - Building a Release Version</option></select></small>
</div>
<div id="sidebar">
@@ -131,208 +136,174 @@
<div id="content">
<h1><a name="BlackBerry%2010%20Platform%20Guide">BlackBerry 10
Platform Guide</a></h1>
-<p>This guide shows how to set up your SDK development environment to
-deploy Cordova apps for BlackBerry 10 devices. See the following for more
-detailed platform-specific information:</p>
+<p>This guide shows how to set up your development environment to build and
deploy Cordova apps for BlackBerry 10 devices.</p>
-<ul>
-<li><a
href="guide_platforms_blackberry10_plugin.md.html#BlackBerry%2010%20Plugins">BlackBerry
10 Plugins</a></li>
-<li><a
href="guide_platforms_blackberry10_tools.md.html#BlackBerry%2010%20Command-line%20Tools">BlackBerry
10 Command-line Tools</a></li>
-</ul>
-<p>The command-line tools above refer to versions prior to Cordova 3.0.
-See The Cordova Command-line Interface for information about the
-current interface.</p>
-
-<h2>
-<a name="BlackBerry%2010%20Platform%20Guide_requirements">Requirements</a>
-</h2>
+<p>For previous versions of BlackBerry, you need to use a different set of
command-line tools, described in <a
href="guide_platforms_blackberry_index.md.html#BlackBerry%20Platform%20Guide">BlackBerry
Platform Guide</a>.</p>
-<p>Cordova for BlackBerry has the following software requirements:</p>
+<h2><a
name="BlackBerry%2010%20Platform%20Guide_requirements">Requirements</a></h2>
-<ul>
-<li>Windows XP (32-bit) or Windows 7 (32-bit and 64-bit) or Mac OSX
10.6.4+</li>
-<li>node.js (> 0.9.9) <a class="external"
href="http://nodejs.org/";>Download node.js now</a>
-</li>
-<li>BlackBerry 10 Native SDK. <a class="external"
href="http://developer.blackberry.com/native/download/";>Download the BlackBerry
10 Native SDK now.</a>
-</li>
-</ul>
-<h2>
-<a
name="BlackBerry%2010%20Platform%20Guide_setting_up_your_signing_keys">Setting
up your signing keys</a>
-</h2>
+<p>The development environment is available on Windows, Mac and Linux.</p>
-<p>Before starting development, you'll need to register for your code signing
key and debug token. The signing key allows you to sign your completed app so
that you can distribute it through BlackBerry World. The debug token allows you
to test an unsigned app on a BlackBerry 10 device. You do not need to create
and install the debug token yourself; if you supply the keystore password, the
build script will create and install the debug token for you.</p>
+<p>Developers should use the <code>cordova</code> utility in conjunction with
the Blackberry Native SDK. See <a
href="guide_cli_index.md.html#The%20Command-line%20Interface">The Command-line
Interface</a> for information how to install <code>cordova</code>, add
projects, then build and deploy.</p>
-<ul>
-<li><a class="external"
href="https://www.blackberry.com/SignedKeys/codesigning.html";>Register for your
code signing key now.</a></li>
-<li><a class="external"
href="http://developer.blackberry.com/html5/documentation/set_up_for_signing.html";>Set
your computer up for code signing. </a></li>
-<li><a class="external"
href="http://developer.blackberry.com/html5/documentation/running_your_bb10_app_2008471_11.html";>Learn
more about debug tokens.</a></li>
-</ul>
-<h2>
-<a name="BlackBerry%2010%20Platform%20Guide_creating_your_project">Creating
your project</a>
-</h2>
+<h2><a
name="BlackBerry%2010%20Platform%20Guide_install_the_blackberry_native_sdk">Install
the BlackBerry Native SDK</a></h2>
-<p>To create a new project, you use the <code>create</code> command to set up
the folder structure for your app.</p>
+<p>The BlackBerry Native SDK is available from <a class="external"
href="http://developer.blackberry.com/native/download/";>developer.blackberry.com</a>.</p>
-<ol>
-<li>On the command line, navigate to the folder where you extracted
Cordova.</li>
-<li>
-<p>Run the <code>create</code> command using the following syntax:</p>
+<p>After installing the BlackBerry Native SDK, its tools must be added to your
system path.</p>
-<pre class="prettyprint"><code>bin/create <path-to-project>
+<h3>Windows</h3>
+
+<p>Go to My Computer â Properties â Advanced â Environment <a
href="plugin_ref_spec.md.html#Variables">Variables</a></p>
+
+<p>Append to PATH based on where you installed the Native SDK, for example:</p>
+
+<pre class="prettyprint"><code>;C:\bbndk\host_10_1_0_132\darwin\x86\usr\bin\
</code></pre>
-</li>
-</ol>
-<p>This command creates the folder structure for your project at the specified
location. All of your project resource files should be stored in the
<em><path-to-project></path-to-project></em>/www folder, or in a subfolder
within it.</p>
-<h2>
-<a
name="BlackBerry%2010%20Platform%20Guide_adding_and_managing_targets">Adding
and managing targets</a>
-</h2>
+<h3>Mac/Linux</h3>
-<p>A target refers to a BlackBerry device or emulator that you will use to
test your app. Targets are added directly to your project; you can add multiple
targets to your project, each with a unique name. Then, when you want to deploy
your app to a particular target, you can simply refer to that target by name
when you run your script.</p>
+<p>Edit the ~/.bash_profile file, adding a line such as the following,
depending on where the Native SDK was installed:</p>
-<h3>Add a target</h3>
+<pre class="prettyprint"><code>$ export
PATH=${PATH}:/Applications/bbndk/host_10_1_0_132/darwin/x86/usr/bin/
+</code></pre>
-<p>To add a target, on the command line, type the following command:</p>
+<p>Then run the following to apply the change immidiately:</p>
-<pre class="prettyprint"><code> <path-to-project>/cordova/target add
<name> <ip-address> [-t | --type <device | simulator>] [-p |
--password <password>] [--pin <device-pin>]
+<pre class="prettyprint"><code>$ source ~/.bash_profile
</code></pre>
-<p>where</p>
+<h2><a name="BlackBerry%2010%20Platform%20Guide_set_up_for_signing">Set up for
Signing</a></h2>
+
+<p>If you wish to test on a device or distribute apps through BlackBerry
World, your system must be setup for code signing.</p>
+
+<p>To obtain a signing key, go to the BlackBerry website and make sure to
retain the password you specify. Then run the <code>blackberry-signer</code>
utility that is included with the BlackBerry Native SDK.</p>
+
+<p>Detailed instuctions can be found here:</p>
<ul>
-<li>
-<code><name></code> specifies a unique name for the target.</li>
-<li>
-<code><ip-address></code> specifies the ip address of the BlackBerry
device or emulator.</li>
-<li>
-<code>-t <device | simulator></code> specifies the target type. If not
provided, the default value is device.</li>
-<li>
-<code>-p|--password <password></code> specifies the password for the
device or emulator. This is required only if the device or emulator is password
protected.</li>
-<li>
-<code>--pin <device-pin></code> specifies the PIN of the BlackBerry
device, which identifies that device as a valid host for the debug token. This
argument is required only if you are creating a debug token.</li>
+<li><a class="external"
href="https://www.blackberry.com/SignedKeys/codesigning.html";>Register for your
code signing key.</a></li>
+<li><a class="external"
href="https://developer.blackberry.com/html5/documentation/signing_setup_bb10_apps_2008396_11.html";>Set
up your system for code signing.</a></li>
</ul>
-<h3>Remove a target</h3>
-<p>To remove a target, on the command line, type the following command:</p>
+<h2><a name="BlackBerry%2010%20Platform%20Guide_create_a_project">Create a
Project</a></h2>
+
+<p>Use the <code>cordova</code> utility to set up a new project, as described
in <a href="guide_cli_index.md.html#The%20Command-line%20Interface">The
Command-line Interface</a>. For example, in a source-code
+directory:</p>
-<pre class="prettyprint"><code> <path-to-project>/cordova/target
remove <name>
+<pre class="prettyprint"><code>$ cordova create hello com.example.hello
+$ cd hello
+$ cordova platform add blackberry10
+$ cordova build
</code></pre>
-<h3>Set a target as the default</h3>
+<h2><a name="BlackBerry%2010%20Platform%20Guide_deploy_to_emulator">Deploy to
Emulator</a></h2>
-<p>To specify a specific target as the default, on the command line, type the
following command:</p>
+<p>If you wish to run a device emulator, download and install the BlackBerry
10 Simulator.</p>
-<pre class="prettyprint"><code> <path-to-project>/cordova/target
default <name>
-</code></pre>
+<ul>
+<li><a class="external"
href="http://developer.blackberry.com/native/download/";>Download</a></li>
+<li><a class="external"
href="http://developer.blackberry.com/devzone/develop/simulator/blackberry_10_simulator_start.html";>Getting
Started</a></li>
+</ul>
-<h2>
-<a name="BlackBerry%2010%20Platform%20Guide_building_your_app">Building your
app</a>
-</h2>
+<p>Before testing an app on either an emulator or a device, you need to add a
<em>target</em> to your project. Each is identified with a unique name, and
associated with an IP address. You need to get the IP address from the emulator
before you use it to view apps.</p>
-<p>To build your app, run the build script. You can build the app in either
release mode or in debug mode.</p>
+<p>Launch the emulator image, then choose <strong>Settings</strong> from the
home screen:</p>
-<ul>
-<li>When you build the app in release mode, you are preparing it for
distribution through BlackBerry World. The script packages your app resources
and plugins together in a .bar file, then signs the app.</li>
-<li>
-<p>When you build the app in debug mode, you are preparing it to be tested.
The script packages your app resources and plugins together in a .bar file, but
does not sign it. The script can also deploy the app onto a previously defined
target. If you have not already created and installed a debug token, you can
supply the keystore password, and the build script will create and install the
debug token for you as well.</p>
+<p><img src="img/guide/platforms/blackberry10/bb_home.png" alt="" title=""></p>
-<p>Debug mode also enables Web Inspector for the app, which allows you to
remotely inspect the source code. A prompt displays the URL that you can use to
connect to and inspect your app. For more information on using Web Inspector,
see <a class="external"
href="http://developer.blackberry.com/html5/documentation/web_inspector_overview_1553586_11.html";>Debugging
using Web Inspector</a>.</p>
-</li>
-</ul>
-<h3>Build your app in release mode</h3>
+<p>Navigate to the <strong>Security and Privacy â Development Mode</strong>
section, enable the option, and obtain the IP address:</p>
+
+<p><img src="img/guide/platforms/blackberry10/bb_devel.png" alt=""
title=""></p>
+
+<p>An additional set of command-line utilities are included when you set up
the BlackBerry 10 platform for your project. The following command, in this
case invoked from the project top-level directory, associates a target named
<em>emu</em> with the IP address displayed above.</p>
-<p>To build your app in release mode, on the command line, type the following
command:</p>
+<p>Windows</p>
-<pre class="prettyprint"><code> <path-to-project>/cordova/build
release -k|--keystorepass <password> [-b|--buildId <number>]
[-p|--params <params-JSON-file>]
+<pre class="prettyprint"><code>$ platforms\blackberry10\cordova\target.bat add
emu 169.254.0.1 -t simulator
</code></pre>
-<p>where</p>
+<p>Mac/Linux</p>
-<ul>
-<li>
-<code>-k|--keystorepass <password></code> specifies the password you
defined when you configured your computer to sign applications.</li>
-<li>
-<code>-b|--buildId <number></code> specifies the build version number
of your application. Typically, this number should be incremented from the
previous signed version. This argument is optional.</li>
-<li>
-<code>-p|--params <params-JSON-file></code> specifies a JSON file
containing additional parameters to pass to downstream tools. This argument is
optional.</li>
-</ul>
-<h3>Build your app in debug mode</h3>
+<pre class="prettyprint"><code>$ platforms/blackberry10/cordova/target add emu
169.254.0.1 -t simulator
+</code></pre>
-<p>To build your app in release mode, on the command line, type the following
command:</p>
+<p>Then, run the <code>emulate</code> command to view the app:</p>
-<pre class="prettyprint"><code> <path-to-project>/cordova/build debug
[<target>] [-k|--keystorepass <password>] [-p|--params
<params-JSON-file>] [-ll|--loglevel <error|warn|verbose>]
+<pre class="prettyprint"><code>$ cordova emulate blackberry10
</code></pre>
-<p>where</p>
+<h2><a name="BlackBerry%2010%20Platform%20Guide_deploy_to_device">Deploy to
Device
+</a></h2>
-<ul>
-<li>
-<code><target></code> specifies the name of a previously added target.
If <code><target></code> is not specified, the default target is used,
if one has been created. This argument is only required if you want the script
to deploy your app to a BlackBerry device or emulator and you have not created
a default target. Additionally, if <code><target></code> is a device,
then that device must be connected to your computer by USB connection or be
connected to the same Wi-Fi network as your computer.</li>
-<li>
-<code>-k|--keystorepass <password></code> specifies the password you
defined when you configured your computer to sign applications. This password
is also used to create your debug token. This argument is only required if you
want the script to create and install the debug token for you.</li>
-<li>
-<code>-p|--params <params-JSON-file></code> specifies a JSON file
containing additional parameters to pass to downstream tools.</li>
-<li>
-<code>-ll|--loglevel <level></code> specifies the log level. The log
level may be one of <code>error</code>, <code>warn</code>, or
<code>verbose</code>.</li>
-</ul>
-<p>Note that all of these parameters are optional. If you have previously
defined a default target (and installed a debug token, if that target is a
BlackBerry device), you can run the script with no arguments, and the script
will package your app and deploy it to the default target. For example:</p>
+<p>To deploy to a device, make sure it is plugged into your computer. Enable
development mode and obtain the IP address as desribed in the emulator section
above. You will also need to obtain the PIN from the the
<strong>Settings</strong> application under <strong>About â
Hardware</strong>.</p>
-<pre class="prettyprint"><code> <path-to-project>/cordova/build debug
-</code></pre>
+<p><img src="img/guide/platforms/blackberry10/bb_pin.png" alt="" title=""></p>
-<h2>
-<a name="BlackBerry%2010%20Platform%20Guide_deploying_an_app">Deploying an
app</a>
-</h2>
+<p>Run the target command-line utility to associate a name with an IP address,
device password and PIN.</p>
-<p>You can test your app using either a BlackBerry device or an emulator.
Before deploying your app, you must first create a target for the device or
emulator you want to deploy your app to.</p>
+<p>Windows</p>
-<p>The run script will first build your app. If you intend to deploy an app
to a physical device for testing, you must first install a debug token on that
device. If you specify the <code>--keystorepass <password></code>
argument when running the run script, the script will create and install the
debug token for you. You do not need a debug token to test your app on an
emulator, even if that app is unsigned.</p>
+<pre class="prettyprint"><code>$ platforms\blackberry10\cordova\target.bat add
mydevice 169.254.0.1 -t device --password 123456 --pin FFFF972E
+</code></pre>
-<p>To deploy your app to a device or emulator, on a command line type the
following command:</p>
+<p>Mac/Linux</p>
-<pre class="prettyprint"><code> <path-to-project>/cordova/run
<target> [--no-build]
+<pre class="prettyprint"><code>$ platforms/blackberry10/cordova/target add
mydevice 169.254.0.1 -t device --password 123456 --pin FFFF972E
</code></pre>
-<p>where
-- <code><target></code> specifies the name of a previously added
target. If <code><target></code> is a device, then that device must be
connected to your computer by USB connection or be connected to the same Wi-Fi
network as your computer.</p>
+<p>--password refers to the password to unlock the device</p>
-<ul>
-<li>
-<code>-no--build</code> will use the most recently built version of the
application rather than re-building. This is useful to test an application in
release mode.</li>
-</ul>
-<h2>
-<a
name="BlackBerry%2010%20Platform%20Guide_adding_and_managing_plugins">Adding
and managing plugins</a>
-</h2>
+<p>--pin refers to the device PIN obtained from the Settings application</p>
-<p>To add additional functionality that is outside of the core features of
Cordova, you'll need to add plugins. A plugin represents a set of APIs that
provide access to additional features of the platform.</p>
+<p>Then, run the <code>run</code> command to view the app:</p>
-<p>In order to use a plugin, you must first add it into your project. Once
added into your project, the plugin will be bundled with your project during
the build process, to ensure that your app has access to all the APIs it
needs.</p>
+<pre class="prettyprint"><code>$ cordova run blackberry10
+</code></pre>
-<h3>Add a plugin</h3>
+<p>If a debug token has not yet been created for this device, an error message
will prompt you to use the platform run script with the password you provided
when registering for signing keys.</p>
-<p>To add a plugin, on the command line, type the following command:</p>
+<p>Windows</p>
-<pre class="prettyprint"><code> <path-to-project>/cordova/plugin add
<path to plugin>
+<pre class="prettyprint"><code>$ platforms\blackberry10\cordova\run.bat
--device --keystorepass mysecret
</code></pre>
-<h3>Remove a plugin</h3>
-
-<p>To remove a plugin, on the command line, type the following command:</p>
+<p>Mac/Linux</p>
-<pre class="prettyprint"><code> <path-to-project>/cordova/plugin rm
<name>
+<pre class="prettyprint"><code>$ platforms/blackberry10/cordova/run --device
--keystorepass mysecret
</code></pre>
-<h3>View a list of installed plugins</h3>
+<h2><a
name="BlackBerry%2010%20Platform%20Guide_debugging_with_webinspector">Debugging
with WebInspector</a></h2>
-<p>To view a list of installed plugins, on the command line, type the
following command:</p>
+<p>When debugging on the device or a simulator, you may run WebInspector
remotely to view the application's internal state.</p>
-<pre class="prettyprint"><code> <path-to-project>/cordova/plugin ls
+<p>A prompt displays the URL that allows you to connect to your app with a
standard web browser.</p>
+
+<p>For more information, see <a class="external"
href="http://developer.blackberry.com/html5/documentation/web_inspector_overview_1553586_11.html";>Debugging
using WebInspector</a>.</p>
+
+<h2><a
name="BlackBerry%2010%20Platform%20Guide_building_a_release_version">Building a
Release Version</a></h2>
+
+<p>By default, running the <code>cordova build</code> command creates an
unsigned <em>.bar</em> package file suitable for testing on a device or
simulator.</p>
+
+<p>You need to run a different <code>build</code> command to create a release
version suitable for distribution through BlackBerry World. This command uses
the following syntax:</p>
+
+<p>Windows</p>
+
+<pre class="prettyprint"><code>$ platforms\blackberry10\cordova\build.bat
--release --keystorepass mysecret
</code></pre>
+<p>Mac/Linux</p>
+
+<pre class="prettyprint"><code>$ platforms/blackberry10/cordova/build
--release --keystorepass mysecret
+</code></pre>
+
+<p>--keystorepass specifies the password you defined when you configured your
computer to sign applications.</p>
+
</div>
</div>
<!-- Functionality and Syntax Highlighting -->
- <script type="text/javascript" src="index.js"></script><script
type="text/javascript" src="prettify/prettify.js"></script>
-</body>
+ <script type="text/javascript" src="index.js"></script>
+ <script type="text/javascript" src="prettify/prettify.js"></script>
+ </body>
</html>
Modified:
cordova/site/public/docs/en/edge/guide_platforms_blackberry10_index.md.html
URL:
http://svn.apache.org/viewvc/cordova/site/public/docs/en/edge/guide_platforms_blackberry10_index.md.html?rev=1508285&r1=1508284&r2=1508285&view=diff
==============================================================================
--- cordova/site/public/docs/en/edge/guide_platforms_blackberry10_index.md.html
(original)
+++ cordova/site/public/docs/en/edge/guide_platforms_blackberry10_index.md.html
Tue Jul 30 03:35:29 2013
@@ -17,23 +17,25 @@
specific language governing permissions and limitations
under the License.
--><html lang="en">
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
-<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0,
user-scalable=no, width=device-width">
-<meta name="generator" content="joDoc">
-<title>Apache Cordova API Documentation</title>
-<link rel="stylesheet" type="text/css" href="index.css">
-<link rel="stylesheet" type="text/css" href="mobile.css" media="only screen
and (max-device-width: 1024px)">
-<link rel="stylesheet" type="text/css" href="prettify/prettify.css">
-</head>
-<body>
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+ <meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0,
user-scalable=no, width=device-width">
+ <meta name="generator" content="joDoc">
+
+ <title>Apache Cordova API Documentation</title>
+
+ <link rel="stylesheet" type="text/css" href="index.css">
+ <link rel="stylesheet" type="text/css" href="mobile.css" media="only
screen and (max-device-width: 1024px)">
+ <link rel="stylesheet" type="text/css" href="prettify/prettify.css">
+ </head>
+ <body>
<div id="header">
<h1><a href="index.html">Apache <strong>Cordova</strong>
Documentation</a></h1>
<small>
<select><optgroup label="English" value="en">
-<option selected value="edge">edge</option>
+<option value="edge">edge</option>
<option value="3.0.0rc1">3.0.0rc1</option>
-<option value="3.0.0">3.0.0</option>
+<option selected value="3.0.0">3.0.0</option>
<option value="2.9.0rc1">2.9.0rc1</option>
<option value="2.9.0">2.9.0</option>
<option value="2.8.0">2.8.0</option>
@@ -77,18 +79,21 @@
<option value="1.8.1">1.8.1</option>
<option value="1.7.0">1.7.0</option>
</optgroup>
-<optgroup label="Korean" value="kr"><option
value="2.0.0">2.0.0</option></optgroup></select></small>
+<optgroup label="Korean" value="kr"><option
value="2.0.0">2.0.0</option></optgroup></select>
+ </small>
</div>
<div id="subheader">
<h1>BlackBerry 10 Platform Guide</h1>
<small><select><option
value="BlackBerry%252010%2520Platform%2520Guide">BlackBerry 10 Platform
Guide</option>
<option value="BlackBerry%2010%20Platform%20Guide_requirements">Â Â Â Â Â Â -
Requirements</option>
-<option
value="BlackBerry%2010%20Platform%20Guide_setting_up_your_signing_keys">Â Â Â Â
  - Setting up your signing keys</option>
-<option value="BlackBerry%2010%20Platform%20Guide_creating_your_project">Â Â Â
   - Creating your project</option>
-<option
value="BlackBerry%2010%20Platform%20Guide_adding_and_managing_targets">Â Â Â Â
  - Adding and managing targets</option>
-<option value="BlackBerry%2010%20Platform%20Guide_building_your_app">Â Â Â Â Â
 - Building your app</option>
-<option value="BlackBerry%2010%20Platform%20Guide_deploying_an_app">Â Â Â Â Â
 - Deploying an app</option>
-<option
value="BlackBerry%2010%20Platform%20Guide_adding_and_managing_plugins">Â Â Â Â
  - Adding and managing plugins</option></select></small>
+<option
value="BlackBerry%2010%20Platform%20Guide_install_the_blackberry_native_sdk">Â
     - Install the BlackBerry Native SDK</option>
+<option value="BlackBerry%2010%20Platform%20Guide_set_up_for_signing">Â Â Â Â
  - Set up for Signing</option>
+<option value="BlackBerry%2010%20Platform%20Guide_create_a_project">Â Â Â Â Â
 - Create a Project</option>
+<option value="BlackBerry%2010%20Platform%20Guide_deploy_to_emulator">Â Â Â Â
  - Deploy to Emulator</option>
+<option value="BlackBerry%2010%20Platform%20Guide_deploy_to_device">Â Â Â Â Â
 - Deploy to Device
+</option>
+<option
value="BlackBerry%2010%20Platform%20Guide_debugging_with_webinspector">Â Â Â Â
  - Debugging with WebInspector</option>
+<option
value="BlackBerry%2010%20Platform%20Guide_building_a_release_version">Â Â Â Â Â
 - Building a Release Version</option></select></small>
</div>
<div id="sidebar">
@@ -131,208 +136,174 @@
<div id="content">
<h1><a name="BlackBerry%2010%20Platform%20Guide">BlackBerry 10
Platform Guide</a></h1>
-<p>This guide shows how to set up your SDK development environment to
-deploy Cordova apps for BlackBerry 10 devices. See the following for more
-detailed platform-specific information:</p>
+<p>This guide shows how to set up your development environment to build and
deploy Cordova apps for BlackBerry 10 devices.</p>
-<ul>
-<li><a
href="guide_platforms_blackberry10_plugin.md.html#BlackBerry%2010%20Plugins">BlackBerry
10 Plugins</a></li>
-<li><a
href="guide_platforms_blackberry10_tools.md.html#BlackBerry%2010%20Command-line%20Tools">BlackBerry
10 Command-line Tools</a></li>
-</ul>
-<p>The command-line tools above refer to versions prior to Cordova 3.0.
-See The Cordova Command-line Interface for information about the
-current interface.</p>
-
-<h2>
-<a name="BlackBerry%2010%20Platform%20Guide_requirements">Requirements</a>
-</h2>
+<p>For previous versions of BlackBerry, you need to use a different set of
command-line tools, described in <a
href="guide_platforms_blackberry_index.md.html#BlackBerry%20Platform%20Guide">BlackBerry
Platform Guide</a>.</p>
-<p>Cordova for BlackBerry has the following software requirements:</p>
+<h2><a
name="BlackBerry%2010%20Platform%20Guide_requirements">Requirements</a></h2>
-<ul>
-<li>Windows XP (32-bit) or Windows 7 (32-bit and 64-bit) or Mac OSX
10.6.4+</li>
-<li>node.js (> 0.9.9) <a class="external"
href="http://nodejs.org/";>Download node.js now</a>
-</li>
-<li>BlackBerry 10 Native SDK. <a class="external"
href="http://developer.blackberry.com/native/download/";>Download the BlackBerry
10 Native SDK now.</a>
-</li>
-</ul>
-<h2>
-<a
name="BlackBerry%2010%20Platform%20Guide_setting_up_your_signing_keys">Setting
up your signing keys</a>
-</h2>
+<p>The development environment is available on Windows, Mac and Linux.</p>
-<p>Before starting development, you'll need to register for your code signing
key and debug token. The signing key allows you to sign your completed app so
that you can distribute it through BlackBerry World. The debug token allows you
to test an unsigned app on a BlackBerry 10 device. You do not need to create
and install the debug token yourself; if you supply the keystore password, the
build script will create and install the debug token for you.</p>
+<p>Developers should use the <code>cordova</code> utility in conjunction with
the Blackberry Native SDK. See <a
href="guide_cli_index.md.html#The%20Command-line%20Interface">The Command-line
Interface</a> for information how to install <code>cordova</code>, add
projects, then build and deploy.</p>
-<ul>
-<li><a class="external"
href="https://www.blackberry.com/SignedKeys/codesigning.html";>Register for your
code signing key now.</a></li>
-<li><a class="external"
href="http://developer.blackberry.com/html5/documentation/set_up_for_signing.html";>Set
your computer up for code signing. </a></li>
-<li><a class="external"
href="http://developer.blackberry.com/html5/documentation/running_your_bb10_app_2008471_11.html";>Learn
more about debug tokens.</a></li>
-</ul>
-<h2>
-<a name="BlackBerry%2010%20Platform%20Guide_creating_your_project">Creating
your project</a>
-</h2>
+<h2><a
name="BlackBerry%2010%20Platform%20Guide_install_the_blackberry_native_sdk">Install
the BlackBerry Native SDK</a></h2>
-<p>To create a new project, you use the <code>create</code> command to set up
the folder structure for your app.</p>
+<p>The BlackBerry Native SDK is available from <a class="external"
href="http://developer.blackberry.com/native/download/";>developer.blackberry.com</a>.</p>
-<ol>
-<li>On the command line, navigate to the folder where you extracted
Cordova.</li>
-<li>
-<p>Run the <code>create</code> command using the following syntax:</p>
+<p>After installing the BlackBerry Native SDK, its tools must be added to your
system path.</p>
-<pre class="prettyprint"><code>bin/create <path-to-project>
+<h3>Windows</h3>
+
+<p>Go to My Computer â Properties â Advanced â Environment <a
href="plugin_ref_spec.md.html#Variables">Variables</a></p>
+
+<p>Append to PATH based on where you installed the Native SDK, for example:</p>
+
+<pre class="prettyprint"><code>;C:\bbndk\host_10_1_0_132\darwin\x86\usr\bin\
</code></pre>
-</li>
-</ol>
-<p>This command creates the folder structure for your project at the specified
location. All of your project resource files should be stored in the
<em><path-to-project></path-to-project></em>/www folder, or in a subfolder
within it.</p>
-<h2>
-<a
name="BlackBerry%2010%20Platform%20Guide_adding_and_managing_targets">Adding
and managing targets</a>
-</h2>
+<h3>Mac/Linux</h3>
-<p>A target refers to a BlackBerry device or emulator that you will use to
test your app. Targets are added directly to your project; you can add multiple
targets to your project, each with a unique name. Then, when you want to deploy
your app to a particular target, you can simply refer to that target by name
when you run your script.</p>
+<p>Edit the ~/.bash_profile file, adding a line such as the following,
depending on where the Native SDK was installed:</p>
-<h3>Add a target</h3>
+<pre class="prettyprint"><code>$ export
PATH=${PATH}:/Applications/bbndk/host_10_1_0_132/darwin/x86/usr/bin/
+</code></pre>
-<p>To add a target, on the command line, type the following command:</p>
+<p>Then run the following to apply the change immidiately:</p>
-<pre class="prettyprint"><code> <path-to-project>/cordova/target add
<name> <ip-address> [-t | --type <device | simulator>] [-p |
--password <password>] [--pin <device-pin>]
+<pre class="prettyprint"><code>$ source ~/.bash_profile
</code></pre>
-<p>where</p>
+<h2><a name="BlackBerry%2010%20Platform%20Guide_set_up_for_signing">Set up for
Signing</a></h2>
+
+<p>If you wish to test on a device or distribute apps through BlackBerry
World, your system must be setup for code signing.</p>
+
+<p>To obtain a signing key, go to the BlackBerry website and make sure to
retain the password you specify. Then run the <code>blackberry-signer</code>
utility that is included with the BlackBerry Native SDK.</p>
+
+<p>Detailed instuctions can be found here:</p>
<ul>
-<li>
-<code><name></code> specifies a unique name for the target.</li>
-<li>
-<code><ip-address></code> specifies the ip address of the BlackBerry
device or emulator.</li>
-<li>
-<code>-t <device | simulator></code> specifies the target type. If not
provided, the default value is device.</li>
-<li>
-<code>-p|--password <password></code> specifies the password for the
device or emulator. This is required only if the device or emulator is password
protected.</li>
-<li>
-<code>--pin <device-pin></code> specifies the PIN of the BlackBerry
device, which identifies that device as a valid host for the debug token. This
argument is required only if you are creating a debug token.</li>
+<li><a class="external"
href="https://www.blackberry.com/SignedKeys/codesigning.html";>Register for your
code signing key.</a></li>
+<li><a class="external"
href="https://developer.blackberry.com/html5/documentation/signing_setup_bb10_apps_2008396_11.html";>Set
up your system for code signing.</a></li>
</ul>
-<h3>Remove a target</h3>
-<p>To remove a target, on the command line, type the following command:</p>
+<h2><a name="BlackBerry%2010%20Platform%20Guide_create_a_project">Create a
Project</a></h2>
+
+<p>Use the <code>cordova</code> utility to set up a new project, as described
in <a href="guide_cli_index.md.html#The%20Command-line%20Interface">The
Command-line Interface</a>. For example, in a source-code
+directory:</p>
-<pre class="prettyprint"><code> <path-to-project>/cordova/target
remove <name>
+<pre class="prettyprint"><code>$ cordova create hello com.example.hello
+$ cd hello
+$ cordova platform add blackberry10
+$ cordova build
</code></pre>
-<h3>Set a target as the default</h3>
+<h2><a name="BlackBerry%2010%20Platform%20Guide_deploy_to_emulator">Deploy to
Emulator</a></h2>
-<p>To specify a specific target as the default, on the command line, type the
following command:</p>
+<p>If you wish to run a device emulator, download and install the BlackBerry
10 Simulator.</p>
-<pre class="prettyprint"><code> <path-to-project>/cordova/target
default <name>
-</code></pre>
+<ul>
+<li><a class="external"
href="http://developer.blackberry.com/native/download/";>Download</a></li>
+<li><a class="external"
href="http://developer.blackberry.com/devzone/develop/simulator/blackberry_10_simulator_start.html";>Getting
Started</a></li>
+</ul>
-<h2>
-<a name="BlackBerry%2010%20Platform%20Guide_building_your_app">Building your
app</a>
-</h2>
+<p>Before testing an app on either an emulator or a device, you need to add a
<em>target</em> to your project. Each is identified with a unique name, and
associated with an IP address. You need to get the IP address from the emulator
before you use it to view apps.</p>
-<p>To build your app, run the build script. You can build the app in either
release mode or in debug mode.</p>
+<p>Launch the emulator image, then choose <strong>Settings</strong> from the
home screen:</p>
-<ul>
-<li>When you build the app in release mode, you are preparing it for
distribution through BlackBerry World. The script packages your app resources
and plugins together in a .bar file, then signs the app.</li>
-<li>
-<p>When you build the app in debug mode, you are preparing it to be tested.
The script packages your app resources and plugins together in a .bar file, but
does not sign it. The script can also deploy the app onto a previously defined
target. If you have not already created and installed a debug token, you can
supply the keystore password, and the build script will create and install the
debug token for you as well.</p>
+<p><img src="img/guide/platforms/blackberry10/bb_home.png" alt="" title=""></p>
-<p>Debug mode also enables Web Inspector for the app, which allows you to
remotely inspect the source code. A prompt displays the URL that you can use to
connect to and inspect your app. For more information on using Web Inspector,
see <a class="external"
href="http://developer.blackberry.com/html5/documentation/web_inspector_overview_1553586_11.html";>Debugging
using Web Inspector</a>.</p>
-</li>
-</ul>
-<h3>Build your app in release mode</h3>
+<p>Navigate to the <strong>Security and Privacy â Development Mode</strong>
section, enable the option, and obtain the IP address:</p>
+
+<p><img src="img/guide/platforms/blackberry10/bb_devel.png" alt=""
title=""></p>
+
+<p>An additional set of command-line utilities are included when you set up
the BlackBerry 10 platform for your project. The following command, in this
case invoked from the project top-level directory, associates a target named
<em>emu</em> with the IP address displayed above.</p>
-<p>To build your app in release mode, on the command line, type the following
command:</p>
+<p>Windows</p>
-<pre class="prettyprint"><code> <path-to-project>/cordova/build
release -k|--keystorepass <password> [-b|--buildId <number>]
[-p|--params <params-JSON-file>]
+<pre class="prettyprint"><code>$ platforms\blackberry10\cordova\target.bat add
emu 169.254.0.1 -t simulator
</code></pre>
-<p>where</p>
+<p>Mac/Linux</p>
-<ul>
-<li>
-<code>-k|--keystorepass <password></code> specifies the password you
defined when you configured your computer to sign applications.</li>
-<li>
-<code>-b|--buildId <number></code> specifies the build version number
of your application. Typically, this number should be incremented from the
previous signed version. This argument is optional.</li>
-<li>
-<code>-p|--params <params-JSON-file></code> specifies a JSON file
containing additional parameters to pass to downstream tools. This argument is
optional.</li>
-</ul>
-<h3>Build your app in debug mode</h3>
+<pre class="prettyprint"><code>$ platforms/blackberry10/cordova/target add emu
169.254.0.1 -t simulator
+</code></pre>
-<p>To build your app in release mode, on the command line, type the following
command:</p>
+<p>Then, run the <code>emulate</code> command to view the app:</p>
-<pre class="prettyprint"><code> <path-to-project>/cordova/build debug
[<target>] [-k|--keystorepass <password>] [-p|--params
<params-JSON-file>] [-ll|--loglevel <error|warn|verbose>]
+<pre class="prettyprint"><code>$ cordova emulate blackberry10
</code></pre>
-<p>where</p>
+<h2><a name="BlackBerry%2010%20Platform%20Guide_deploy_to_device">Deploy to
Device
+</a></h2>
-<ul>
-<li>
-<code><target></code> specifies the name of a previously added target.
If <code><target></code> is not specified, the default target is used,
if one has been created. This argument is only required if you want the script
to deploy your app to a BlackBerry device or emulator and you have not created
a default target. Additionally, if <code><target></code> is a device,
then that device must be connected to your computer by USB connection or be
connected to the same Wi-Fi network as your computer.</li>
-<li>
-<code>-k|--keystorepass <password></code> specifies the password you
defined when you configured your computer to sign applications. This password
is also used to create your debug token. This argument is only required if you
want the script to create and install the debug token for you.</li>
-<li>
-<code>-p|--params <params-JSON-file></code> specifies a JSON file
containing additional parameters to pass to downstream tools.</li>
-<li>
-<code>-ll|--loglevel <level></code> specifies the log level. The log
level may be one of <code>error</code>, <code>warn</code>, or
<code>verbose</code>.</li>
-</ul>
-<p>Note that all of these parameters are optional. If you have previously
defined a default target (and installed a debug token, if that target is a
BlackBerry device), you can run the script with no arguments, and the script
will package your app and deploy it to the default target. For example:</p>
+<p>To deploy to a device, make sure it is plugged into your computer. Enable
development mode and obtain the IP address as desribed in the emulator section
above. You will also need to obtain the PIN from the the
<strong>Settings</strong> application under <strong>About â
Hardware</strong>.</p>
-<pre class="prettyprint"><code> <path-to-project>/cordova/build debug
-</code></pre>
+<p><img src="img/guide/platforms/blackberry10/bb_pin.png" alt="" title=""></p>
-<h2>
-<a name="BlackBerry%2010%20Platform%20Guide_deploying_an_app">Deploying an
app</a>
-</h2>
+<p>Run the target command-line utility to associate a name with an IP address,
device password and PIN.</p>
-<p>You can test your app using either a BlackBerry device or an emulator.
Before deploying your app, you must first create a target for the device or
emulator you want to deploy your app to.</p>
+<p>Windows</p>
-<p>The run script will first build your app. If you intend to deploy an app
to a physical device for testing, you must first install a debug token on that
device. If you specify the <code>--keystorepass <password></code>
argument when running the run script, the script will create and install the
debug token for you. You do not need a debug token to test your app on an
emulator, even if that app is unsigned.</p>
+<pre class="prettyprint"><code>$ platforms\blackberry10\cordova\target.bat add
mydevice 169.254.0.1 -t device --password 123456 --pin FFFF972E
+</code></pre>
-<p>To deploy your app to a device or emulator, on a command line type the
following command:</p>
+<p>Mac/Linux</p>
-<pre class="prettyprint"><code> <path-to-project>/cordova/run
<target> [--no-build]
+<pre class="prettyprint"><code>$ platforms/blackberry10/cordova/target add
mydevice 169.254.0.1 -t device --password 123456 --pin FFFF972E
</code></pre>
-<p>where
-- <code><target></code> specifies the name of a previously added
target. If <code><target></code> is a device, then that device must be
connected to your computer by USB connection or be connected to the same Wi-Fi
network as your computer.</p>
+<p>--password refers to the password to unlock the device</p>
-<ul>
-<li>
-<code>-no--build</code> will use the most recently built version of the
application rather than re-building. This is useful to test an application in
release mode.</li>
-</ul>
-<h2>
-<a
name="BlackBerry%2010%20Platform%20Guide_adding_and_managing_plugins">Adding
and managing plugins</a>
-</h2>
+<p>--pin refers to the device PIN obtained from the Settings application</p>
-<p>To add additional functionality that is outside of the core features of
Cordova, you'll need to add plugins. A plugin represents a set of APIs that
provide access to additional features of the platform.</p>
+<p>Then, run the <code>run</code> command to view the app:</p>
-<p>In order to use a plugin, you must first add it into your project. Once
added into your project, the plugin will be bundled with your project during
the build process, to ensure that your app has access to all the APIs it
needs.</p>
+<pre class="prettyprint"><code>$ cordova run blackberry10
+</code></pre>
-<h3>Add a plugin</h3>
+<p>If a debug token has not yet been created for this device, an error message
will prompt you to use the platform run script with the password you provided
when registering for signing keys.</p>
-<p>To add a plugin, on the command line, type the following command:</p>
+<p>Windows</p>
-<pre class="prettyprint"><code> <path-to-project>/cordova/plugin add
<path to plugin>
+<pre class="prettyprint"><code>$ platforms\blackberry10\cordova\run.bat
--device --keystorepass mysecret
</code></pre>
-<h3>Remove a plugin</h3>
-
-<p>To remove a plugin, on the command line, type the following command:</p>
+<p>Mac/Linux</p>
-<pre class="prettyprint"><code> <path-to-project>/cordova/plugin rm
<name>
+<pre class="prettyprint"><code>$ platforms/blackberry10/cordova/run --device
--keystorepass mysecret
</code></pre>
-<h3>View a list of installed plugins</h3>
+<h2><a
name="BlackBerry%2010%20Platform%20Guide_debugging_with_webinspector">Debugging
with WebInspector</a></h2>
-<p>To view a list of installed plugins, on the command line, type the
following command:</p>
+<p>When debugging on the device or a simulator, you may run WebInspector
remotely to view the application's internal state.</p>
-<pre class="prettyprint"><code> <path-to-project>/cordova/plugin ls
+<p>A prompt displays the URL that allows you to connect to your app with a
standard web browser.</p>
+
+<p>For more information, see <a class="external"
href="http://developer.blackberry.com/html5/documentation/web_inspector_overview_1553586_11.html";>Debugging
using WebInspector</a>.</p>
+
+<h2><a
name="BlackBerry%2010%20Platform%20Guide_building_a_release_version">Building a
Release Version</a></h2>
+
+<p>By default, running the <code>cordova build</code> command creates an
unsigned <em>.bar</em> package file suitable for testing on a device or
simulator.</p>
+
+<p>You need to run a different <code>build</code> command to create a release
version suitable for distribution through BlackBerry World. This command uses
the following syntax:</p>
+
+<p>Windows</p>
+
+<pre class="prettyprint"><code>$ platforms\blackberry10\cordova\build.bat
--release --keystorepass mysecret
</code></pre>
+<p>Mac/Linux</p>
+
+<pre class="prettyprint"><code>$ platforms/blackberry10/cordova/build
--release --keystorepass mysecret
+</code></pre>
+
+<p>--keystorepass specifies the password you defined when you configured your
computer to sign applications.</p>
+
</div>
</div>
<!-- Functionality and Syntax Highlighting -->
- <script type="text/javascript" src="index.js"></script><script
type="text/javascript" src="prettify/prettify.js"></script>
-</body>
+ <script type="text/javascript" src="index.js"></script>
+ <script type="text/javascript" src="prettify/prettify.js"></script>
+ </body>
</html>
