You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by mw...@apache.org on 2013/07/19 17:18:55 UTC
[04/12] Version 3.0.0
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/b00c364c/docs/en/3.0.0/guide/platforms/android/plugin.md
----------------------------------------------------------------------
diff --git a/docs/en/3.0.0/guide/platforms/android/plugin.md b/docs/en/3.0.0/guide/platforms/android/plugin.md
new file mode 100644
index 0000000..dba4f2d
--- /dev/null
+++ b/docs/en/3.0.0/guide/platforms/android/plugin.md
@@ -0,0 +1,192 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+---
+
+# Android Plugins
+
+Writing a plugin requires an understanding of the architecture of Cordova-Android. Cordova-Android consists
+of an Android WebView with hooks attached to it. These plugins are represented as class mappings in the config.xml
+file.
+
+A plugin consists of at least one Java class that extends the `CordovaPlugin` class. A plugin must override one
+of the `execute` methods from `CordovaPlugin`.
+As best practice, the plugin should handle `pause` and `resume` events, and any message passing between plugins.
+Plugins with long-running requests, background activity such as media payback, listeners, or internal state should implement the `onReset()` method as well. This method is run when the `WebView` navigates to a new page or refreshes, which reloads the JavaScript.
+
+## Plugin Class Mapping
+
+The JavaScript portion of a plugin always uses the `cordova.exec` method as follows:
+
+ exec(<successFunction>, <failFunction>, <service>, <action>, [<args>]);
+
+This marshals a request from the WebView to the Android native side,
+more or less boiling down to calling the `action` method on the
+`service` class, with the arguments passed in the `args` Array.
+
+Whether you distribute your plugin as Java file or as a JAR of its own, the plugin must be added to the `config.xml` file in your Cordova-Android application's `res/xml/` folder.
+
+ <plugin name="<service_name>" value="<full_name_including_namespace>"/>
+
+The service name should match the one used in the JavaScript `exec`
+call, and the value is the Java classes full name, including the
+namespace. Otherwise the plugin may compile but still be unreachable
+by Cordova.
+
+## Writing an Android Java Plugin
+
+JavaScript fires off a plugin request to the native side. The Android
+Java plugin is mapped properly via the `config.xml` file. So what
+does the final Android Java Plugin class look like?
+
+What gets dispatched to the plugin via JavaScript's `exec` function gets
+passed into the Plugin class's `execute` method. Most `execute`
+implementations look like this:
+
+ @Override
+ public boolean execute(String action, JSONArray args, CallbackContext callbackContext) throws JSONException {
+ if ("beep".equals(action)) {
+ this.beep(args.getLong(0));
+ callbackContext.success();
+ return true;
+ }
+ return false; // Returning false results in a "MethodNotFound" error.
+ }
+
+We compare the value of the `action` parameter, and dispatch the
+request off to a (private) method in the class, optionally passing
+some of the parameters to the method.
+
+When catching exceptions and returning errors, it's important for the
+sake of clarity that errors returned to JavaScript match Java's
+exception names as much as possible.
+
+### Threading
+
+JavaScript in the WebView does *not* run on the UI thread. It runs on
+the WebCore thread. The `execute` method also runs on the WebCore thread.
+
+If you need to interact with the UI, you should use the following:
+
+ @Override
+ public boolean execute(String action, JSONArray args, final CallbackContext callbackContext) throws JSONException {
+ if ("beep".equals(action)) {
+ final long duration = args.getLong(0);
+ cordova.getActivity().runOnUiThread(new Runnable() {
+ public void run() {
+ ...
+ callbackContext.success(); // Thread-safe.
+ }
+ });
+ return true;
+ }
+ return false;
+ }
+
+If you do not need to run on the UI thread, but do not want to block the WebCore thread:
+
+ @Override
+ public boolean execute(String action, JSONArray args, final CallbackContext callbackContext) throws JSONException {
+ if ("beep".equals(action)) {
+ final long duration = args.getLong(0);
+ cordova.getThreadPool().execute(new Runnable() {
+ public void run() {
+ ...
+ callbackContext.success(); // Thread-safe.
+ }
+ });
+ return true;
+ }
+ return false;
+ }
+
+### Echo Android Plugin Example
+
+Add the following to our `config.xml` file:
+
+ <plugin name="Echo" value="org.apache.cordova.plugin.Echo" />
+
+Then add the following file to
+`src/org/apache/cordova/plugin/Echo.java` inside our Cordova-Android
+application:
+
+ package org.apache.cordova.plugin;
+
+ import org.apache.cordova.api.CordovaPlugin;
+ import org.apache.cordova.api.PluginResult;
+ import org.json.JSONArray;
+ import org.json.JSONException;
+ import org.json.JSONObject;
+
+ /**
+ * This class echoes a string called from JavaScript.
+ */
+ public class Echo extends CordovaPlugin {
+ @Override
+ public boolean execute(String action, JSONArray args, CallbackContext callbackContext) throws JSONException {
+ if (action.equals("echo")) {
+ String message = args.getString(0);
+ this.echo(message, callbackContext);
+ return true;
+ }
+ return false;
+ }
+
+ private void echo(String message, CallbackContext callbackContext) {
+ if (message != null && message.length() > 0) {
+ callbackContext.success(message);
+ } else {
+ callbackContext.error("Expected one non-empty string argument.");
+ }
+ }
+ }
+
+Let's take a look at the code. The necessary `imports` are at
+the top. Our class extends from `CordovaPlugin`. We override the
+execute() method in order to recieve messages from exec(). Our method
+first compares against `action`: this plugin only supports one action,
+the `echo` action. Any other action returns false, which results in an
+error of type `INVALID_ACTION`, which translates into an error
+callback invocation on the JavaScript side. Next, we grab the echo
+string using the `getString` method on our `args`, telling it we want
+to get the 0th parameter in the parameter array. We do a bit of
+parameter checking: make sure it is not `null`, and make sure it is
+not a zero-length string. If it is, we call `callbackContext.error()`
+(which, by now, you should know invokes the error callback). If all of
+those checks pass, then we call `callbackContext.success()` and pass
+in the `message` string we received as a parameter. This finally
+translates into a success callback invocation on the JavaScript
+side. It also passes the `message` parameter as a parameter into the
+JavaScript success callback function.
+
+## Debugging Plugins
+
+Eclipse can be used to debug an Android project, and the plugins can be debugged if the Java source is included in the project. Only the latest version of the Android Developer Tools is known to allow source code attachment to JAR dependencies, so this is not fully supported at this time.
+
+## Common Pitfalls
+
+* Plugins have access to a `CordovaInterface` object. This object has access to the Android `Activity` that is running the application. This is the `Context` required to launch
+a new Android `Intent`. The `CordovaInterface` allows plugins to start an `Activity` for a result, and to set the callback plugin for when the `Intent` comes back to the application. This is important, since the
+`Intent`s system is how Android communicates between processes.
+* Plugins do not have direct access to the `Context` as they have in the past. The legacy `ctx` member is deprecated, and will be removed six months after 2.0 is released. All of `ctx` methods exist on the `Context`, so both `getContext()` and `getActivity()` are capable of returning the proper object required.
+
+## Use the Source
+
+One of the best ways to prepare yourself to write your own plugin is to
+[look over existing plugins](https://github.com/apache/cordova-android/tree/master/framework/src/org/apache/cordova).
+
+You should also read through the comments in [CordovaPlugin.java](https://github.com/apache/cordova-android/blob/master/framework/src/org/apache/cordova/api/CordovaPlugin.java).
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/b00c364c/docs/en/3.0.0/guide/platforms/android/tools.md
----------------------------------------------------------------------
diff --git a/docs/en/3.0.0/guide/platforms/android/tools.md b/docs/en/3.0.0/guide/platforms/android/tools.md
new file mode 100644
index 0000000..09fcfdc
--- /dev/null
+++ b/docs/en/3.0.0/guide/platforms/android/tools.md
@@ -0,0 +1,80 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+---
+
+# Android Command-line Tools
+
+The `cordova` command-line utility is a high-level tool that allows
+you to build applications across several platforms at once. An older
+version of the Cordova framework provides sets of command-line tools
+specific to each platform. To use them as an alternative to the CLI,
+you need to download this version of Cordova from
+[cordova.apache.org](http://cordova.apache.org). The download contains
+separate archives for each platform. Expand the platform you wish to
+target. The tools described here are typically available in the
+top-level `bin` directory, otherwise consult the __README__ file for
+more detailed directions.
+
+## Create a project
+
+Run the `create` command, specifying the existing path to the project,
+the reverse-domain-style package identifier, and the app's display
+name. Here is the syntax for both Mac and Windows:
+
+ $ /path/to/cordova-android/bin/create /path/to/project com.example.project_name ProjectName
+ $ C:\path\to\cordova-android\bin\create.bat C:\path\to\project com.example.project_name ProjectName
+
+## Build
+
+This cleans then builds a project.
+
+Debug, on Mac or Windows:
+
+ $ /path/to/project/cordova/build --debug
+ $ C:\path\to\project\cordova\build.bat --debug
+
+Release, on Mac or Windows:
+
+ $ /path/to/project/cordova/build --release
+ $ C:\path\to\project\cordova\build.bat --release
+
+## Run the App
+
+The `run` command accepts the following _optional_ parameters:
+
+* Target specification. This includes `--emulator`, `--device`, or `--target=<targetID>`.
+* Build specification. This includes `--debug`, `--release`, or `--nobuild`.
+
+ $ /path/to/project/cordova/run [Target] [Build]
+ $ C:\path\to\project\cordova\run.bat [Target] [Build]
+
+Make sure you create at least one Android Virtual Device, otherwise
+you're prompted to do so with the `android` command. If more than one
+AVD is available as a target, you're prompted to select one. By
+default the `run` command detects a connected device, or a currently
+running emulator if no device is found.
+
+## Logging
+
+ $ /path/to/project/cordova/log
+ $ C:\path\to\project\cordova\log.bat
+
+### Cleaning
+
+ $ /path/to/project/cordova/clean
+ $ C:\path\to\project\cordova\clean.bat
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/b00c364c/docs/en/3.0.0/guide/platforms/android/upgrading.md
----------------------------------------------------------------------
diff --git a/docs/en/3.0.0/guide/platforms/android/upgrading.md b/docs/en/3.0.0/guide/platforms/android/upgrading.md
new file mode 100644
index 0000000..64be68f
--- /dev/null
+++ b/docs/en/3.0.0/guide/platforms/android/upgrading.md
@@ -0,0 +1,268 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+---
+
+# Upgrading Android
+
+This guide shows how to modify Android 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
+Cordova Command-line Interface for information how to update the
+version of the CLI.
+
+## Upgrade to the CLI (3.0.0) from 2.9.0 ##
+
+1. Create a new Apache Cordova 3.0.0 project using the cordova CLI, as
+ described in The Cordova Command-line Interface.
+2. Add your platforms the the cordova project, for example: `cordova
+ platform add android`.
+3. Copy the contents of your project's `www` folder to the `www` folder
+ at the root of the cordova project you just created.
+4. Copy any native assets from your old project into the appropriate
+ directories under `platforms/android`: this directory is where your
+ native cordova-android project exists.
+5. 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.
+
+## Upgrade to 3.0.0 from 2.9.0 ##
+
+1. Create a new Apache Cordova Android project.
+2. Copy the contents of your `www` folder to the new project.
+3. Copy any native Android assets from your `res` folder to the new project.
+4. Copy over any plugins you installed from the `src` subdirectories into the new project.
+5. Make sure to upgrade any deprecated `<plugin>` references from your old `config.xml` file to the new `<feature>` specification.
+- __NOTE:__ all core APIs have been removed and must be installed as plugins. Please see the Using Plugman to Manage Plugins Guide for details.
+
+## Upgrade to 2.9.0 from 2.8.0
+1. Run `bin/update <project_path>`
+
+## Upgrade to 2.8.0 from 2.7.0 ##
+1. Remove `cordova-2.7.0.jar` from the project's `libs` directory
+2. Add `cordova-2.8.0.jar` to the project's `libs` directory
+3. If you are using Eclipse, please refresh your eclipse project and do a clean
+4. Copy the new cordova.js into your project
+5. Update your HTML to use the new cordova.js file
+6. Copy the `res/xml/config.xml` file to match `framework/res/xml/config.xml`
+7. Update `framework/res/xml/config.xml` to have similar settings as it did previously
+8. Copy files from `bin/templates/cordova` to the project's `cordova` directory
+
+## Upgrade to 2.7.0 from 2.6.0 ##
+1. Remove `cordova-2.6.0.jar` from the project's `libs` directory
+2. Add `cordova-2.7.0.jar` to the project's `libs` directory
+3. If you are using Eclipse, please refresh your eclipse project and do a clean
+4. Copy the new `cordova-2.7.0.js` into your project
+5. Update your HTML to use the new `cordova-2.7.0.js` file
+6. Copy the `res/xml/config.xml` to match `framework/res/xml/config.xml`
+7. Update `framework/res/xml/config.xml` to have similar settings as it did previously
+8. Copy files from `bin/templates/cordova` to the project's `cordova` directory
+
+## Upgrade to 2.6.0 from 2.5.0 ##
+1. Remove `cordova-2.5.0.jar` from the project's `libs` directory
+2. Add `cordova-2.6.0.jar` to the project's `libs` directory
+3. If you are using Eclipse, please refresh your eclipse project and do a clean
+4. Copy the new `cordova-2.6.0.js` into your project
+5. Update your HTML to use the new `cordova-2.6.0.js` file
+6. Copy the `res/xml/config.xml` to match `framework/res/xml/config.xml`
+7. Update `framework/res/xml/config.xml` to have similar settings as it did previously
+8. Copy files from `bin/templates/cordova` to the project's `cordova` directory
+
+Run `bin/update <project>` with the project path listed in the Cordova Source directory.
+
+## Upgrade to 2.5.0 from 2.4.0 ##
+
+1. Remove `cordova-2.4.0.jar` from the project's `libs` directory
+2. Add `cordova-2.5.0.jar` to the project's `libs` directory
+3. If you are using Eclipse, please refresh your eclipse project and do a clean
+4. Copy the new `cordova-2.5.0.js` into your project
+5. Update your HTML to use the new `cordova-2.5.0.js` file
+6. Copy the `res/xml/config.xml` to match `framework/res/xml/config.xml`
+7. Update `framework/res/xml/config.xml` to have similar settings as it did previously
+8. Copy files from `bin/templates/cordova` to the project's `cordova` directory
+
+## Upgrade to 2.4.0 from 2.3.0 ##
+
+1. Remove `cordova-2.3.0.jar` from the project's `libs` directory
+2. Add `cordova-2.4.0.jar` to the project's `libs` directory
+3. If you are using Eclipse, please refresh your eclipse project and do a clean
+4. Copy the new `cordova-2.4.0.js` into your project
+5. Update your HTML to use the new `cordova-2.4.0.js` file
+6. Copy the `res/xml/config.xml` to match `framework/res/xml/config.xml`
+7. Copy files from `bin/templates/cordova` to the project's `cordova` directory
+
+## Upgrade to 2.3.0 from 2.2.0 ##
+
+1. Remove `cordova-2.2.0.jar` from the project's `libs` directory
+2. Add `cordova-2.3.0.jar` to the project's `libs` directory
+3. If you are using Eclipse, please refresh your eclipse project and do a clean
+4. Copy the new `cordova-2.3.0.js` into your project
+5. Update your HTML to use the new `cordova-2.3.0.js` file
+6. Copy the `res/xml/config.xml` to match `framework/res/xml/config.xml`
+7. Copy files from `bin/templates/cordova` to the project's `cordova` directory
+
+## Upgrade to 2.2.0 from 2.1.0 ##
+
+1. Remove `cordova-2.1.0.jar` from the project's `libs` directory
+2. Add `cordova-2.2.0.jar` to the project's `libs` directory
+3. If you are using Eclipse, please refresh your eclipse project and do a clean
+4. Copy the new `cordova-2.2.0.js` into your project
+5. Update your HTML to use the new `cordova-2.2.0.js` file
+6. Copy the `res/xml/config.xml` to match `framework/res/xml/config.xml`
+7. Copy files from `bin/templates/cordova` to the project's `cordova` directory
+
+## Upgrade to 2.1.0 from 2.0.0 ##
+
+1. Remove `cordova-2.0.0.jar` from the project's `libs` directory
+2. Add `cordova-2.1.0.jar` to the project's `libs` directory
+3. If you are using Eclipse, please refresh your eclipse project and do a clean
+4. Copy the new `cordova-2.1.0.js` into your project
+5. Update your HTML to use the new `cordova-2.1.0.js` file
+6. Copy the `res/xml/config.xml` to match `framework/res/xml/config.xml`
+7. Copy files from `bin/templates/cordova` to the project's `cordova` directory
+
+## Upgrade to 2.0.0 from 1.9.0 ##
+
+1. Remove `cordova-1.9.0.jar` from the project's `libs` directory
+2. Add `cordova-2.0.0.jar` to the project's `libs` directory
+3. If you are using Eclipse, please refresh your eclipse project and do a clean
+4. Copy the new `cordova-2.0.0.js` into your project
+5. Update your HTML to use the new `cordova-2.0.0.js` file
+6. Copy the `res/xml/config.xml` to match `framework/res/xml/config.xml`
+
+### Notes about 2.0.0 release
+config.xml will be replacing cordova.xml and plugins.xml. This new file is a combination of the previous two. However, the
+old files are deprecated, and while currently still work, will cease working in a future release.
+
+## Upgrade to 1.9.0 from 1.8.1 ##
+
+1. Remove `cordova-1.8.0.jar` from the project's `libs` directory
+2. Add `cordova-1.9.0.jar` to the project's `libs` directory
+3. If you are using Eclipse, please refresh your eclipse project and do a clean
+4. Copy the new `cordova-1.9.0.js` into your project
+5. Update your HTML to use the new `cordova-1.9.0.js` file
+6. Update `res/xml/plugins.xml` to match `framework/res/xml/plugins.xml`
+
+### Notes about 1.9.0 release
+
+- Third-Party plugins may or may not work. This is because of the introduction of the CordovaWebView. These plugins need to get a context from the CordovaInterface using
+getContext() or getActivity(). If you are not an experienced Android developer, please contact the plugin maintainer and add this task to their bug tracker.
+
+## Upgrade to 1.8.0 from 1.8.0 ##
+
+1. Remove `cordova-1.8.0.jar` from the project's `libs` directory
+2. Add `cordova-1.8.1.jar` to the project's `libs` directory
+3. If you are using Eclipse, please refresh your eclipse project and do a clean
+4. Copy the new `cordova-1.8.1.js` into your project
+5. Update your HTML to use the new `cordova-1.8.1.js` file
+6. Update `res/xml/plugins.xml` to match `framework/res/xml/plugins.xml`
+
+## Upgrade to 1.8.0 from 1.7.0 ##
+
+1. Remove `cordova-1.7.0.jar` from the project's `libs` directory
+2. Add `cordova-1.8.0.jar` to the project's `libs` directory
+3. If you are using Eclipse, please refresh your eclipse project and do a clean
+4. Copy the new `cordova-1.8.0.js` into your project
+5. Update your HTML to use the new `cordova-1.8.0.js` file
+6. Update `res/xml/plugins.xml` to match `framework/res/xml/plugins.xml`
+
+## Upgrade to 1.8.0 from 1.7.0 ##
+
+1. Remove `cordova-1.7.0.jar` from the project's `libs` directory
+2. Add `cordova-1.8.0.jar` to the project's `libs` directory
+3. If you are using Eclipse, please refresh your eclipse project and do a clean
+4. Copy the new `cordova-1.8.0.js` into your project
+5. Update your HTML to use the new `cordova-1.8.0.js` file
+6. Update `res/xml/plugins.xml` to match `framework/res/xml/plugins.xml`
+
+## Upgrade to 1.7.0 from 1.6.1 ##
+
+1. Remove `cordova-1.6.1.jar` from the project's `libs` directory
+2. Add `cordova-1.7.0.jar` to the project's `libs` directory
+3. If you are using Eclipse, please refresh your eclipse project and do a clean
+4. Copy the new `cordova-1.7.0.js` into your project
+5. Update `res/xml/plugins.xml` to match `framework/res/xml/plugins.xml`
+
+## Upgrade to 1.6.1 from 1.6.0 ##
+
+1. Remove `cordova-1.6.0.jar` from the project's `libs` directory
+2. Add `cordova-1.6.1.jar` to the project's `libs` directory
+3. If you are using Eclipse, please refresh your eclipse project and do a clean
+4. Copy the new `cordova-1.6.1.js` into your project
+5. Update `res/xml/plugins.xml` to match `framework/res/xml/plugins.xml`
+
+## Upgrade to 1.6.0 from 1.5.0 ##
+1. Remove `cordova-1.5.0.jar` from the project's `libs` directory
+2. Add `cordova-1.6.0.jar` to the project's `libs` directory
+3. If you are using Eclipse, please refresh your eclipse project and do a clean
+4. Copy the new `cordova-1.6.0.js` into your project
+5. Update your HTML to use the new `cordova-1.6.0.js` file
+6. Update `res/xml/plugins.xml` to match `framework/res/xml/plugins.xml`
+7. Replace `res/xml/phonegap.xml` with `res/xml/cordova.xml` to match `framework/res/xml/cordova.xml`
+
+## Upgrade to 1.5.0 from 1.4.0##
+1. Remove `phonegap-1.4.0.jar` from the project's `libs` directory
+2. Add `cordova-1.5.0.jar` to the project's `libs` directory
+3. If you are using Eclipse, please refresh your eclipse project and do a clean
+4. Copy the new `cordova-1.5.0.js` into your project
+5. Update your HTML to use the new `cordova-1.5.0.js` file
+6. Update `res/xml/plugins.xml` to match `framework/res/xml/plugins.xml`
+7. Replace `res/xml/phonegap.xml` with `res/xml/cordova.xml` to match `framework/res/xml/cordova.xml`
+
+## Upgrade to 1.4.0 from 1.3.0 ##
+1. Remove `phonegap-1.3.0.jar` from the project's `libs` directory
+2. Add `phonegap-1.4.0.jar` to the project's `libs` directory
+3. If you are using Eclipse, please refresh your eclipse project and do a clean
+4. Copy the new `phonegap-1.4.0.js` into your project
+5. Update your HTML to use the new `phonegap-1.4.0.js` file
+6. Update `res/xml/plugins.xml` to match `framework/res/xml/plugins.xml`
+7. Update `res/xml/phonegap.xml` to match `framework/res/xml/phonegap.xml`
+
+## Upgrade to 1.3.0 from 1.2.0 ##
+1. Remove `phonegap-1.2.0.jar` from the project's `libs` directory
+2. Add `phonegap-1.3.0.jar` to the project's `libs` directory
+3. If you are using Eclipse, please refresh your eclipse project and do a clean
+4. Copy the new `phonegap-1.3.0.js` into your project
+5. Update your HTML to use the new `phonegap-1.2.0.js` file
+6. Update `res/xml/plugins.xml` to match `framework/res/xml/plugins.xml`
+7. Update `res/xml/phonegap.xml` to match `framework/res/xml/phonegap.xml`
+
+## Upgrade to 1.2.0 from 1.1.0 ##
+1. Remove `phonegap-1.1.0.jar` from the project's `libs` directory
+2. Add `phonegap-1.2.0.jar` to the project's `libs` directory
+3. If you are using Eclipse, please refresh your eclipse project and do a clean
+4. Copy the new `phonegap-1.2.0.js` into your project
+5. Update your HTML to use the new `phonegap-1.2.0.js` file
+6. Update `res/xml/plugins.xml` to match `framework/res/xml/plugins.xml`
+7. Update `res/xml/phonegap.xml` to match `framework/res/xml/phonegap.xml`
+
+## Upgrade to 1.1.0 from 1.0.0 ##
+1. Remove `phonegap-1.0.0.jar` from the project's `libs` directory
+2. Add `phonegap-1.1.0.jar` to the project's `libs` directory
+3. If you are using Eclipse, please refresh your eclipse project and do a clean
+4. Copy the new `phonegap-1.1.0.js` into your project
+5. Update your HTML to use the new `phonegap-1.1.0.js` file
+6. Update `res/xml/plugins.xml` to match `framework/res/xml/plugins.xml`
+
+## Upgrade to 1.0.0 from 0.9.6 ##
+1. Remove `phonegap-0.9.6.jar` from the project's `libs` directory
+2. Add `phonegap-1.0.0.jar` to the project's `libs` directory
+3. If you are using Eclipse, please refresh your eclipse project and do a clean
+4. Copy the new `phonegap-1.0.0.js` into your project
+5. Update your HTML to use the new `phonegap-1.0.0.js` file
+6. Add the `res/xml/plugins.xml` to match `framework/res/xml/plugins.xml`
+
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/b00c364c/docs/en/3.0.0/guide/platforms/android/webview.md
----------------------------------------------------------------------
diff --git a/docs/en/3.0.0/guide/platforms/android/webview.md b/docs/en/3.0.0/guide/platforms/android/webview.md
new file mode 100644
index 0000000..ece0458
--- /dev/null
+++ b/docs/en/3.0.0/guide/platforms/android/webview.md
@@ -0,0 +1,119 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+---
+
+# Android WebViews
+
+Beginning in Cordova 1.9, with the assistance of the
+`CordovaActivity`, you can use Cordova as a component in a larger
+native Android application. Android refers to this component as the
+`CordovaWebView`. New Cordova-based applications from 1.9 onwards use
+the `CordovaWebView` as its main view, regardless of whether the
+legacy `DroidGap` approach is used.
+
+If you're unfamiliar with Android application development, please read
+the Android Platform Guide to developing a Cordova Application before
+attempting to include a WebView. It's not the main way to author
+Android Cordova applications. These instructions are currently manual,
+but may be eventually be automated.
+
+## Prerequisites
+
+1. **Cordova 1.9** or greater
+2. Android SDK updated with 15
+
+## Guide to using CordovaWebView in an Android Project
+
+1. Use `bin/create` to fetch the `commons-codec-1.6.jar` file.
+2. `cd` into `/framework` and run `ant jar` to build the cordova jar. It creates the .jar file formed as `cordova-x.x.x.jar` in the `/framework` folder.
+3. Copy the cordova jar into your Android project's `/libs` directory.
+4. Edit your application's `main.xml` file (under `/res/xml`) to look like the following, with the `layout_height`, `layout_width` and `id` modified to suit your application:
+
+ <org.apache.cordova.CordovaWebView
+ android:id="@+id/tutorialView"
+ android:layout_width="match_parent"
+ android:layout_height="match_parent" />
+
+5. Modify your activity so that it implements the `CordovaInterface`. You should implement the included methods. You may wish to copy them from `/framework/src/org/apache/cordova/DroidGap.java`, or implement them on your own. The code fragment below shows a basic application that uses the interface. Note how the referenced view id matches the `id` attribute specified in the XML fragment shown above:
+
+ public class CordovaViewTestActivity extends Activity implements CordovaInterface {
+ CordovaWebView cwv;
+ /* Called when the activity is first created. */
+ @Override
+ public void onCreate(Bundle savedInstanceState) {
+ super.onCreate(savedInstanceState);
+ setContentView(R.layout.main);
+ cwv = (CordovaWebView) findViewById(R.id.tutorialView);
+ Config.init(this);
+ cwv.loadUrl(Config.getStartUrl());
+ }
+
+ If you use the camera, you should also implement this:
+
+ @Override
+ public void setActivityResultCallback(CordovaPlugin plugin) {
+ this.activityResultCallback = plugin;
+ }
+ /**
+ * Launch an activity for which you would like a result when it finished. When this activity exits,
+ * your onActivityResult() method is called.
+ *
+ * @param command The command object
+ * @param intent The intent to start
+ * @param requestCode The request code that is passed to callback to identify the activity
+ */
+ public void startActivityForResult(CordovaPlugin command, Intent intent, int requestCode) {
+ this.activityResultCallback = command;
+ this.activityResultKeepRunning = this.keepRunning;
+
+ // If multitasking turned on, then disable it for activities that return results
+ if (command != null) {
+ this.keepRunning = false;
+ }
+
+ // Start activity
+ super.startActivityForResult(intent, requestCode);
+ }
+
+ @Override
+ /**
+ * Called when an activity you launched exits, giving you the requestCode you started it with,
+ * the resultCode it returned, and any additional data from it.
+ *
+ * @param requestCode The request code originally supplied to startActivityForResult(),
+ * allowing you to identify who this result came from.
+ * @param resultCode The integer result code returned by the child activity through its setResult().
+ * @param data An Intent, which can return result data to the caller (various data can be attached to Intent "extras").
+ */
+ protected void onActivityResult(int requestCode, int resultCode, Intent intent) {
+ super.onActivityResult(requestCode, resultCode, intent);
+ CordovaPlugin callback = this.activityResultCallback;
+ if (callback != null) {
+ callback.onActivityResult(requestCode, resultCode, intent);
+ }
+ }
+
+ Finally, remember to add the thread pool, otherwise the plugins have no threads to run on:
+
+ @Override
+ public ExecutorService getThreadPool() {
+ return threadPool;
+ }
+
+6. Copy your application's HTML and JavaScript files to your Android project's `/assets/www` directory.
+7. Copy `cordova.xml` and `plugins.xml` from `/framework/res/xml` to your project's `/res/xml` folder.
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/b00c364c/docs/en/3.0.0/guide/platforms/blackberry/config.md
----------------------------------------------------------------------
diff --git a/docs/en/3.0.0/guide/platforms/blackberry/config.md b/docs/en/3.0.0/guide/platforms/blackberry/config.md
new file mode 100644
index 0000000..399b553
--- /dev/null
+++ b/docs/en/3.0.0/guide/platforms/blackberry/config.md
@@ -0,0 +1,26 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+---
+
+# BlackBerry Configuration
+
+BlackBerry fully supports the
+[W3C Widget Specification](http://www.w3.org/TR/widgets/)
+as well as proprietary RIM extensions. Please see the full
+[BlackBerry WebWorks documentation regarding config.xml](https://developer.blackberry.com/html5/documentation/working_with_config_xml_file_1866970_11.html)
+for details.
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/b00c364c/docs/en/3.0.0/guide/platforms/blackberry/index.md
----------------------------------------------------------------------
diff --git a/docs/en/3.0.0/guide/platforms/blackberry/index.md b/docs/en/3.0.0/guide/platforms/blackberry/index.md
new file mode 100644
index 0000000..07998ee
--- /dev/null
+++ b/docs/en/3.0.0/guide/platforms/blackberry/index.md
@@ -0,0 +1,212 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+---
+
+# BlackBerry Platform Guide
+
+This guide shows you how to set up an SDK environment to target
+applications for the BlackBerry platform prior to version 10. If you
+want to target the most recent version, see the BlackBerry 10 Platform
+Guide. See the following for more detailed platform-specific
+information:
+
+* BlackBerry Configuration
+* Upgrading BlackBerry
+* BlackBerry Plugins
+* BlackBerry Command-line Tools
+
+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.
+
+## Requirements and Support
+
+This version of BlackBerry is not supported by the `cordova` utility
+described in The Command-line Interface, but by a separate set of
+command-line tools. Download the Cordova distribution from
+[cordova.apache.org](http://cordova.apache.org/#download).
+
+Cordova for BlackBerry relies on the [BlackBerry WebWorks
+framework](https://bdsc.webapps.blackberry.com/html5), which is
+available for Windows XP (32-bit), Windows 7 (32-bit and 64-bit), and
+Mac (OS X 10.6.4+). WebWorks applications can _only_ be deployed on
+the following BlackBerry platforms:
+
+* BlackBerry OS 5.0 and higher
+* BlackBerry PlayBook
+* BlackBerry 10 (QNX)
+
+WebWorks requires the Java Development Kit (JDK). For Windows, use the
+32-bit version of
+[Oracle JDK](http://www.oracle.com/technetwork/java/javase/downloads/index.html#jdk).
+Java in installed by default on Mac OS X up to version 10.7, which
+requires
+[a separate installation](http://support.apple.com/kb/DL1421).
+It also requires Apache Ant, which on Mac is part of the Java
+installation. The Windows version is available from
+[ant.apache.org](http://ant.apache.org/bindownload.cgi).
+
+## Install the SDK
+
+Download and install the appropriate WebWorks SDK for your
+development. BlackBerry PlayBook and BlackBerry Smartphone WebWorks
+SDKs can be downloaded from the following locations.
+
+- [BlackBerry PlayBook SDK] (https://developer.blackberry.com/html5/download/#playbook) and [Adobe Air SDK](http://www.adobe.com/devnet/air/air-sdk-download.html)
+- [BlackBerry Smartphones SDK] (https://developer.blackberry.com/html5/download/#smartphones)
+
+## 3. Register for Signing Keys
+
+If you wish to publish your application on BlackBerry App World, or deploy on an actual device you’ll need to register for a set of free Code Signing Keys.
+
+To register for Signing Keys visit, and complete the [BlackBerry Keys Order Form](https://www.blackberry.com/SignedKeys).
+
+Once you receive your Signing Keys, they'll need to be setup. To learn how to setup your Signing Keys visit the [BlackBerry HTML5/WebWorks website](https://developer.blackberry.com/html5/documentation/signing_setup_bb10_apps_2008396_11.html).
+
+## 4. Install Cordova
+
+Download and extract the latest copy of [Cordova](http://cordova.apache.org/#download).
+
+## 5. Set up New Project
+
+- Open up a command-line terminal and navigate to where you extracted Cordova.
+- There is a directory for each platform that Cordova supports. CD into the `blackberry` directory.
+- The blackberry directory contains several directories. The `example` folder contains a complete Cordova project. Copy the `example` folder to another location on your computer.
+- Change to the newly created directory.
+- Open up the project.properties file with your favorite editor and edit the entries for the WebWorks SDKs you are using. For example...
+
+BlackBerry 10 (QNX)
+- `qnx.bbwp.dir=C:\\Program Files (x86)\\Research In Motion\\BlackBerry 10 WebWorks SDK 1.0.2.9`
+
+Along with the SDK, you also need to register for a code signing key
+and debug token. The signing key allows you to distribute apps through
+BlackBerry World. The debug token allows you to test unsigned apps on
+a BlackBerry emulator or device. You do not need to create and
+install the debug token yourself; if you supply the keystore password,
+the build script creates and installs the debug token for you. To set
+up the signing key, go to the Blackberry website to obtain it, making
+sure to retain the password you specify. Then run the
+`blackberry-signer` utility that is included with the SDK. Consult the
+following for more information:
+
+* [Register for your code signing key](https://www.blackberry.com/SignedKeys/codesigning.html)
+
+* [Set up your computer for code signing](http://developer.blackberry.com/html5/documentation/set_up_for_signing.html)
+
+Build the Cordova sample project by typing `./cordova/build <target>` in your command prompt while you are in your project's directory. Replace `<target>` with either `qnx` `playbook` or `blackberry`. For example...
+
+* [Comprehensive guide to setting up your SDK environment](http://developer.blackberry.com/native/documentation/bb10/com.qnx.doc.native_sdk.quickstart/topic/set_up_your_environment.html)
+
+## Set up a New Project
+
+* Open up a command-line terminal. From the directory where you
+ extracted Cordova, navigate to the `blackberry` subdirectory.
+
+* Copy the `blackberry` directory's `example` subdirectory to another
+ location on your computer and navigate there.
+
+* Edit the `project.properties` file to specify the WebWorks SDK you
+ are using. For example, here are the respective settings for
+ BlackBerry PlayBook or BlackBerry Smartphone (OS5-7):
+
+ playbook.bbwp.dir=C:\\Program Files\\Research In Motion\\BlackBerry WebWorks SDK for TabletOS 2.1.0.6\\bbwp
+ blackberry.bbwp.dir=C:\\Program Files\\Research In Motion\\BlackBerry WebWorks Packager
+
+These correspond to parameters you specify when building your project.
+The first time you run these commands, they generate a "Hello World"
+application:
+
+ cordova/build playbook
+ cordova/build blackberry
+
+## Deploy to Emulator
+
+BlackBerry smartphone emulators are only available on Windows.
+BlackBerry PlayBook emulators require VMWare Player (Windows) or
+VMWare Fusion (Mac OS X). The WebWorks SDK provides a default
+emulator, but additional emulators are [available through
+BlackBerry](http://us.blackberry.com/developers/resources/simulators.jsp).
+
+While in your project directory, in command prompt type `./cordova/run <target>`. Replace `<target>` with either `qnx`, `playbook`, or `blackberry`. Note, for BlackBerry 10 and PlayBook, the emulator virtual image must already be started. For example...
+
+* [BlackBerry PlayBook](https://developer.blackberry.com/html5/documentation/using_the_tablet_simulator_1866980_11.html)
+
+* [BlackBerry Smartphone](https://developer.blackberry.com/html5/documentation/run_your_app_on_smartphone_sim_1876976_11.html)
+
+For BlackBerry Playbook, edit the `project.properties` file to
+customize the `playbook.sim.ip` and `playbook.sim.password`
+properties. The emulator's IP address is available through the
+__Settings__ application on the home screen. Enable the __Security and
+Privacy → Development Mode__ option to display the address. The
+password can also be set in the __Security and Privacy__ tab.
+
+For BlackBerry Smartphone, edit the `project.properties` file to
+customize the `blackberry.sim.dir` and `blackberry.sim.bin`
+properties. You need to escape path delimiters when specifying
+directory paths on Windows, for example: `C:\\Program
+Files\\BlackBerry\\Simulator`.
+
+Once the emulator is installed and running, run either of the
+following to install an application to the home screen:
+
+ cordova/run playbook
+ cordova/run blackberry
+
+If you are prompted whether a device is connected to your computer,
+answer no.
+
+__NOTE:__ On BlackBerry OS 5, the application is installed in the
+`Downloads` folder.
+
+## Deploy to Device
+
+To deploy your app to a device, it must be connected, and you must be
+registered for code signing keys as described above. Also, to deploy
+apps on BlackBerry PlayBook, the __Settings → Security →
+Development Mode__ option must be enabled.
+
+On Blackberry PlayBook, edit the `project.properties` file and modify
+the following to reflect the device's IP and password as descibed
+above, along with the signing key password you set up:
+
+While in your project directory, in command prompt type `./cordova/run <target>`. Replace `<target>` with either `qnx`, `playbook`, or `blackberry`. For example...
+
+On BlackBerry Smartphone (OS5-7), specify the
+`blackberry.sigtool.password` property as the signing key password.
+
+Then from the project's directory, run either of the commands you
+would to view the app in an emulator:
+
+ cordova/run playbook
+ cordova/run blackberry
+
+If you are prompted whether a device is connected to your computer,
+answer yes.
+
+__NOTE:__ On BlackBerry OS 5, the application is installed in the
+`Downloads` folder.
+
+## Additional Information
+
+The following articles may help resolve common problems when
+developing applications built for the BlackBerry WebWorks framework:
+
+* [BlackBerry WebWorks Development Pitfalls](http://supportforums.blackberry.com/t5/Web-and-WebWorks-Development/Common-BlackBerry-WebWorks-development-pitfalls-that-can-be/ta-p/624712)
+
+* [Best practices for packaging WebWorks applications](https://bdsc.webapps.blackberrycom/html5/documentation/ww_developing/bestpractice_compiling_ww_apps_1873324_11.html)
+
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/b00c364c/docs/en/3.0.0/guide/platforms/blackberry/plugin.md
----------------------------------------------------------------------
diff --git a/docs/en/3.0.0/guide/platforms/blackberry/plugin.md b/docs/en/3.0.0/guide/platforms/blackberry/plugin.md
new file mode 100644
index 0000000..56ba5ac
--- /dev/null
+++ b/docs/en/3.0.0/guide/platforms/blackberry/plugin.md
@@ -0,0 +1,146 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+---
+
+# BlackBerry Plugins
+
+This guide shows how to develop an Echo plugin on BlackBerry. The
+Plugin Development Guide provides a broad overview with which you
+should already be familiar, and this guide picks up where it leaves
+off. In addition, download the [Cordova BlackBerry
+repository](https://git-wip-us.apache.org/repos/asf?p=cordova-blackberry-webworks.git;a=summary).
+
+The `Cordova-BlackBerry` project allows you to deploy to BlackBerry
+devices such as the Torch, Bold, and Playbook. The Playbook uses a
+different code base than other BlackBerry handheld devices, for which
+you need to duplicate your development efforts. This guide focuses on
+the handheld devices rather than tablets. (In the future, this guide
+should cover both platforms.)
+
+The Echo plugin essentially returns whatever message a user provides
+to the `window.echo` function:
+
+ window.echo = function(str, callback) {
+ cordova.exec(callback, function(err) {
+ callback('Nothing to echo.');
+ }, "Echo", "echo", [str]);
+ };
+
+## Modifying plugins.xml
+
+Your project's `www/plugins.xml` folder contains all of the necessary
+references to your Cordova project's plugins. Add an
+additional reference so that when `cordova.exec` is called, Cordova
+knows how to map the `Echo` argument of `cordova.exec` to the `Echo`
+class that we want to write natively:
+
+ <plugins>
+ ...
+ <plugin name="Echo" value="org.apache.cordova.echo.Echo"/>
+ ...
+ </plugins>
+
+## Adding Echo.java
+
+If you notice the structure of the value attribute, you'll see a
+defined path that leads to the Echo plugin. In the root folder of the
+Cordova BlackBerry WebWorks repo, look for a folder called framework.
+This folder contains all of the source code that runs natively on the
+BlackBerry. Navigate to `framework/ext/src/org/apache/cordova`. At
+this point, you'll see all of the plugin folders, inside of which is
+the source code. So add the folder echo to
+`framework/ext/src/org/apache/cordova/echo` and create a file called
+`Echo.java` at `framework/ext/src/org/apache/cordova/echo/Echo.java`.
+
+## Writing Echo.java
+
+The basic idea behind writing a plugin is to create a class that
+extends the Plugin class and have a method called `execute` to return
+a `PluginResult` class. Any call to `cordova.exec` passes in the
+action to execute within the class, as well as the arguments. In this
+case, "echo" is the action we want to execute within the class "Echo"
+and [str] are the arguments we are passing in.
+
+ package org.apache.cordova.echo;
+
+ import org.apache.cordova.api.Plugin;
+ import org.apache.cordova.api.PluginResult;
+ import org.apache.cordova.json4j.JSONArray;
+ import org.apache.cordova.json4j.JSONException;
+ import org.apache.cordova.json4j.JSONObject;
+ /**
+ * A simple plugin to demonstrate how to build a plugin for BlackBerry
+ * Basically echos back the msg that a user calls to this plugin
+ */
+ public final class Echo extends Plugin {
+
+ public static final String echo = "echo";
+
+ public PluginResult execute(String action, JSONArray args, String callbackId) {
+ PluginResult result = new PluginResult(PluginResult.Status.INVALID_ACTION, "Echo: Invalid action:" + action);
+ if(action.equals(echo)){
+ try {
+ String theMsg = args.getString(0);
+ if(theMsg!= null || theMsg.length()>0){
+ result = new PluginResult(PluginResult.Status.OK, theMsg);
+ }else{
+ result = new PluginResult(PluginResult.Status.ERROR, "Nothing to echo.");
+ }
+ } catch (JSONException e) {
+ result = new PluginResult(PluginResult.Status.JSON_EXCEPTION, e.getMessage());
+ }
+ }
+
+ return result;
+ }
+
+ }
+
+So if we look at the code above, we can see that within the execute
+method, we are first looking for what actions are coming in. The Echo
+plugin has only one action, `echo`, so we will be only checking for
+that. If our plugin had more actions, it's simply a matter of adding
+more conditional tests to check for those actions.
+
+We are then going to grab the message coming in from the arguments
+which is supplied by the args parameter. We can grab the first
+argument by simply doing `String theMsg = args.getString(0);`.
+
+We will do some error checking and if the message looks okay, we will
+instantiate a new PluginResult with an ok status:
+`PluginResult.Status.OK` and return the message: `theMsg`. After this,
+we return the result which to be passed back to JavaScript to be fired
+in the success callback. If something fails, we can return various
+status exceptions like `PluginResult.Status.ERROR`,
+`PluginResult.Status.JSON_EXCEPTION`, or
+`PluginResult.Status.INVALID_ACTION`. When passed back, these types of
+results fire the fail callback in JavaScript.
+
+## Updating the .jar in your project's www folder
+
+The added `Echo.java` needs to be updated in your project. To build
+the `.jar` file, Navigate to the BlackBerry WebWorks repo's root
+directory and run the `ant` command:
+
+ ant update -Dproject.path="~/path_to_my_project"
+
+This builds a new `.jar` file in the `build/ext` directory. Copy the
+`build/ext/cordova.jar` file into your `project/www/ext` directory.
+
+If all goes well, that allows you to use the Echo plugin in
+BlackBerry.
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/b00c364c/docs/en/3.0.0/guide/platforms/blackberry/tools.md
----------------------------------------------------------------------
diff --git a/docs/en/3.0.0/guide/platforms/blackberry/tools.md b/docs/en/3.0.0/guide/platforms/blackberry/tools.md
new file mode 100644
index 0000000..ee9f3b3
--- /dev/null
+++ b/docs/en/3.0.0/guide/platforms/blackberry/tools.md
@@ -0,0 +1,84 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+---
+
+# BlackBerry Command-line Tools
+
+The `cordova` command-line utility is a high-level tool that allows
+you to build applications across several platforms at once. An older
+version of the Cordova framework provides sets of command-line tools
+specific to each platform. To use them as an alternative to the CLI,
+you need to download this version of Cordova from
+[cordova.apache.org](http://cordova.apache.org). The download contains
+separate archives for each platform. Expand the platform you wish to
+target. The tools described here are typically available in the
+top-level `bin` directory, otherwise consult the __README__ file for
+more detailed directions.
+
+## Create a project
+
+Run the `create` command, specifying the existing path to the project,
+the reverse-domain-style package identifier, and the app's display
+name. Here is the syntax for both Mac and Windows:
+
+ $ /path/to/cordova-blackberry-webworks/bin/create /path/to/my_new_project com.example.project_name ProjectName
+ $ /path/to/cordova-blackberry-webworks/bin/create.bat /path/to/my_new_project com.example.project_name ProjectName
+
+__NOTE:__ The BlackBerry platform ignores the package name placeholder
+(`com.example.project_name`), but it's still required for use by
+cross-platform tools.
+
+## Build a project
+
+For BlackBerry projects, please make sure you customize the
+`project.properties` file in your Cordova project's root directory.
+You need to do so to supply your BlackBerry signing key password, and
+specify locations for the BlackBerry WebWorks SDK and BlackBerry
+emulator executables.
+
+ $ /path/to/my_new_project/cordova/build <platform>
+ $ /path/to/my_new_project/cordova/build.bat <platform>
+
+## Launch emulator
+
+For BlackBerry projects, please make sure you customize the
+`project.properties` file in the root of your Cordova project folder.
+You need to do so to supply your BlackBerry signing key password, and
+specify locations for the BlackBerry WebWorks SDK and BlackBerry
+emulator executables.
+
+ $ /path/to/my_new_project/cordova/run <platform>
+
+and then choose 'no' when prompted with:
+
+ Do you have a BlackBerry device connected to your computer? (y/n)
+ $ /path/to/my_new_project/cordova/run <platform>
+
+and then choose 'no' when prompted with:
+
+ Do you have a BlackBerry device connected to your computer? (y/n)
+
+## Logging
+
+Unfortunately, streaming logs directly from the device is currently
+unsupported. However, BlackBerry offers built-in Web Inspector support
+for Playbook and BlackBerry smartphone devices running BlackBerry OS
+7.0 and above. You can also access your application's logs (including
+any calls to `console.log`) on your device by holding down the ''ALT''
+key from the home screen and typing ''lglg'' keys.
+
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/b00c364c/docs/en/3.0.0/guide/platforms/blackberry/upgrading.md
----------------------------------------------------------------------
diff --git a/docs/en/3.0.0/guide/platforms/blackberry/upgrading.md b/docs/en/3.0.0/guide/platforms/blackberry/upgrading.md
new file mode 100644
index 0000000..8c17b29
--- /dev/null
+++ b/docs/en/3.0.0/guide/platforms/blackberry/upgrading.md
@@ -0,0 +1,310 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+---
+
+# Upgrading BlackBerry
+
+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
+Cordova Command-line Interface for information how to update the
+version of the CLI.
+
+## Upgrading 2.8.0 projects to 2.9.0 ##
+
+BlackBerry 10:
+
+1. **Download and extract the Cordova 2.9.0 source** to a **permanent folder location** on your hard drive (say to ~/Cordova-2.9.0)
+2. **Quit any running SDK tools**: Eclipse, Momentics and the like.
+3. **Navigate** to the directory where you put the downloaded source above, using a unix like terminal: **Terminal.app**, **Bash**, **Cygwin**, etc.
+4. **Create a new project**, as described in BlackBerry Command-line Tools. This becomes the home of your updated project.
+5. **Copy** your projects source from the old project's /www folder to the new project's /www folder
+6. **Update** the Cordova script reference in your **www/index.html** file (and any other files that contain the script reference) to point to the new **cordova.js** file
+
+### BlackBerryOS/Playbook ###
+
+1. **Download and extract the Cordova 2.9.0 source** to a **permanent folder location** on your hard drive (say to ~/Cordova-2.9.0)
+2. **Quit any running SDK tools**: Eclipse, Momentics and the like.
+3. **Navigate** to the directory where you put the downloaded source above, using a unix like terminal: **Terminal.app**, **Bash**, **Cygwin**, etc.
+4. **Create a new project**, as described in iOS Command-line Tools. You need the assets from this new project.
+5. **Copy** the **www/cordova.js** file from the new project into your **www** folder, and delete your **www/cordova.js** file
+6. **Update** the Cordova script reference in your **www/index.html** file (and any other files that contain the script reference) to point to the new **cordova.js** file
+7. **Copy** the **native** folder from the new project into the existing project, overwriting the old **native** folder
+8. **Copy** the **lib** folder from the new project into the existing project, overwriting the old **lib** folder
+9. **Copy** the **cordova** folder from the new project into the existing project, overwriting the old **cordova** folder
+
+## Upgrading 2.7.0 projects to 2.8.0 ##
+
+BlackBerry 10:
+
+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.
+
+1. **Download and extract the Cordova 2.8.0 source** to a **permanent folder location** on your hard drive (say to ~/Cordova-2.8.0)
+2. **Quit any running SDK tools**: Eclipse, Momentics and the like.
+3. **Navigate** to the directory where you put the downloaded source above, using a unix like terminal: **Terminal.app**, **Bash**, **Cygwin**, etc.
+4. **Create a new project**, as described in BlackBerry Command-line Tools. This becomes the home of your updated project.
+5. **Copy** your projects source from the old project's /www folder to the new project's /www folder
+6. **Update** the Cordova script reference in your **www/index.html** file (and any other files that contain the script reference) to point to the new **cordova.js** file
+
+BlackBerryOS/Playbook:
+
+1. **Download and extract the Cordova 2.8.0 source** to a **permanent folder location** on your hard drive (say to ~/Cordova-2.8.0)
+2. **Quit any running SDK tools**: Eclipse, Momentics and the like.
+3. **Navigate** to the directory where you put the downloaded source above, using a unix like terminal: **Terminal.app**, **Bash**, **Cygwin**, etc.
+4. **Create a new project**, as described in iOS Command-line Tools. You need the assets from this new project.
+5. **Copy** the **www/cordova.js** file from the new project into your **www** folder, and delete your **www/cordova.js** file
+6. **Update** the Cordova script reference in your **www/index.html** file (and any other files that contain the script reference) to point to the new **cordova.js** file
+7. **Copy** the **native** folder from the new project into the existing project, overwriting the old **native** folder
+8. **Copy** the **lib** folder from the new project into the existing project, overwriting the old **lib** folder
+9. **Copy** the **cordova** folder from the new project into the existing project, overwriting the old **cordova** folder
+
+## Upgrading 2.6.0 projects to 2.7.0 ##
+
+1. **Download and extract the Cordova 2.7.0 source** to a **permanent folder location** on your hard drive (say to ~/Cordova-2.7.0)
+2. **Quit any running SDK tools**: Eclipse, Momentics and the like.
+3. **Navigate** to the directory where you put the downloaded source above, using a unix like terminal: **Terminal.app**, **Bash**, **Cygwin**, etc.
+4. **Create a new project**, as described in BlackBerry Command-line Tools. You need the assets from this new project.
+5. **Copy** the **www/cordova-2.7.0.js** file from the new project into your **www** folder, and delete your **www/cordova-2.6.0.js** file
+6. **Update** the Cordova script reference in your **www/index.html** file (and any other files that contain the script reference) to point to the new **cordova-2.7.0.js** file
+7. **Copy** the **native** folder from the new project into the existing project, overwriting the old **native** folder
+8. **Copy** the **lib** folder from the new project into the existing project, overwriting the old **lib** folder
+9. **Copy** the **cordova** folder from the new project into the existing project, overwriting the old **cordova** folder
+
+## Upgrade to 2.6.0 from 2.5.0 ##
+
+Updating the PhoneGap download folder:
+
+It is recommended that you download a fresh copy of the entire folder.
+
+However, here are the new parts needed for the piecemeal update:
+1. Update the cordova.blackberry.js file in the ‘Phonegap-2.6.0/lib/blackberry/javascript’ folder
+2. Update the ‘ext’, ‘ext-air’, and ‘ext-qnx’ in the ‘Phonegap-2.6.0/lib/blackberry/framework’ folder
+3. Update the ‘build.xml’ file in the ‘Phonegap-2.6.0/lib/blackberry’ folder
+4. Update the ‘Phonegap-2.6.0/lib/blackberry/bin’ folder
+5. Update the ‘VERSION’ file in the ‘Phonegap-2.6.0/lib/blackberry’ folder
+
+Updating the example/ folder or migrating an existing project:
+
+1. Open your `www/` folder, which contains your app.
+2. Remove and update the .jar file in the `ext/` folder.
+3. Update the contents of the `ext-air/` folder.
+4. Update the contents of the `ext-qnx/` folder.
+4. Copy the new `cordova-2.6.0.js` into your project.
+5. 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 folder:
+
+It is recommended that you download a fresh copy of the entire folder.
+
+However, here are the new parts needed for the piecemeal update:
+1. Update the cordova.blackberry.js file in the ‘Phonegap-2.5.0/lib/blackberry/javascript’ folder
+2. Update the ‘ext’, ‘ext-air’, and ‘ext-qnx’ in the ‘Phonegap-2.5.0/lib/blackberry/framework’ folder
+3. Update the ‘build.xml’ file in the ‘Phonegap-2.5.0/lib/blackberry’ folder
+4. Update the ‘Phonegap-2.5.0/lib/blackberry/bin’ folder
+5. Update the ‘VERSION’ file in the ‘Phonegap-2.5.0/lib/blackberry’ folder
+
+Updating the example/ folder or migrating an existing project:
+
+1. Open your `www/` folder, which contains your app.
+2. Remove and update the .jar file in the `ext/` folder.
+3. Update the contents of the `ext-air/` folder.
+4. Update the contents of the `ext-qnx/` folder.
+4. Copy the new `cordova-2.5.0.js` into your project.
+5. 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` folder:
+
+1. Open your `www/` folder, which contains your app.
+2. Remove and update the .jar file in the `ext/` folder.
+3. Update the contents of the `ext-air/` folder.
+4. Copy the new `cordova-2.4.0.js` into your project.
+ - If playbook, then update the .js file in the `playbook/` folder.
+ - If BlackBerry 10, then update the .js file in the `qnx/` folder.
+5. Update your HTML to use the new `cordova-2.4.0.js` file.
+
+Updating the sample folder (ie, updating using the ant tools):
+
+1. Open the `sample/lib/` folder.
+2. Update the .jar file in the `cordova.2.3.0/ext/` folder.
+3. Update the contents of the `cordova.2.3.0/ext-air/` folder.
+4. Update the contents of the `cordova.2.3.0/ext-qnx/` folder.
+5. Update the .js file in the `cordova.2.3.0/javascript/` folder.
+6. Open the `sample/lib/` folder and rename the `cordova.2.3.0/` folder to `cordova.2.4.0/`.
+7. Type `ant blackberry build` or `ant playbook build` to update the `www/` folder with updated Cordova.
+8. Open the `www/` folder and update your HTML to use the new `cordova-2.4.0.js` file
+
+## Upgrade to 2.3.0 from 2.2.0 ##
+
+Updating just the `www` folder:
+
+1. Open your `www/` folder, which contains your app.
+2. Remove and update the .jar file in the `ext/` folder.
+3. Update the contents of the `ext-air/` folder.
+4. Copy the new `cordova-2.3.0.js` into your project.
+ - If playbook, then update the .js file in the `playbook/` folder.
+ - If BlackBerry 10, then update the .js file in the `qnx/` folder.
+5. Update your HTML to use the new `cordova-2.3.0.js` file.
+
+Updating the sample folder (ie, updating using the ant tools):
+
+1. Open the `sample/lib/` folder.
+2. Update the .jar file in the `cordova.2.2.0/ext/` folder.
+3. Update the contents of the `cordova.2.2.0/ext-air/` folder.
+4. Update the contents of the `cordova.2.2.0/ext-qnx/` folder.
+5. Update the .js file in the `cordova.2.2.0/javascript/` folder.
+6. Open the `sample/lib/` folder and rename the `cordova.2.2.0/` folder to `cordova.2.3.0/`.
+7. Type `ant blackberry build` or `ant playbook build` to update the `www/` folder with updated Cordova.
+8. Open the `www/` folder and update your HTML to use the new `cordova-2.3.0.js` file
+
+## Upgrade to 2.2.0 from 2.1.0 ##
+
+Updating just the www folder:
+
+1. Open your `www/` folder, which contains your app.
+2. Remove and update the .jar file in the `ext/` folder.
+3. Update the contents of the `ext-air/` folder.
+4. Copy the new `cordova-2.2.0.js` into your project.
+ - If playbook, then update the .js file in the `playbook/` folder.
+ - If BlackBerry 10, then update the .js file in the `qnx/` folder.
+5. Update your HTML to use the new `cordova-2.2.0.js` file.
+
+Updating the sample folder (ie, updating using the ant tools):
+
+1. Open the `sample/lib/` folder.
+2. Update the .jar file in the `cordova.2.1.0/ext/` folder.
+3. Update the contents of the `cordova.2.1.0/ext-air/` folder.
+4. Update the contents of the `cordova.2.1.0/ext-qnx/` folder.
+5. Update the .js file in the `cordova.2.1.0/javascript/` folder.
+6. Open the `sample/lib/` folder and rename the `cordova.2.1.0/` folder to `cordova.2.2.0/`.
+7. Type `ant blackberry build` or `ant playbook build` to update the `www/` folder with updated Cordova.
+8. Open the `www/` folder and update your HTML to use the new `cordova-2.2.0.js` file.
+
+## Upgrade to 2.1.0 from 2.0.0 ##
+
+Updating just the `www` folder:
+
+1. Open your `www/` folder, which contains your app.
+2. Remove and update the .jar file in the `ext/` folder.
+3. Update the contents of the `ext-air/` folder.
+4. Copy the new `cordova-2.1.0.js` into your project.
+ - If playbook, then update the .js file in the `playbook/` folder.
+5. Update your HTML to use the new `cordova-2.1.0.js` file.
+
+Updating the sample folder (ie, updating using the ant tools):
+
+1. Open the `sample/lib/` folder.
+2. Update the .jar file in the `cordova.2.0.0/ext/` folder.
+3. Update the contents of the `cordova.2.0.0/ext-air/` folder.
+4. Update the .js file in the `cordova.2.0.0/javascript/` folder.
+5. Open the `sample/lib/` folder and rename the `cordova.2.0.0/` folder to `cordova.2.1.0/`.
+6. Type `ant blackberry build` or `ant playbook build` to update the `www/` folder with updated Cordova.
+7. Open the `www/` folder and update your HTML to use the new `cordova-2.1.0.js` file.
+
+## Upgrade to 2.0.0 from 1.9.0 ##
+
+Updating just the `www` folder:
+
+1. Open your `www/` folder, which contains your app.
+2. Remove and update the .jar file in the `ext/` folder.
+3. Update the contents of the `ext-air/` folder.
+4. Copy the new `cordova-2.0.0.js` into your project.
+ - If playbook, then update the .js file in the `playbook/` folder.
+5. Update your HTML to use the new `cordova-2.0.0.js` file.
+6. Update your `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 folder (ie, updating using the ant tools):
+
+1. Open the `sample/lib/` folder.
+2. Update the .jar file in the `cordova.1.9.0/ext/` folder.
+3. Update the contents of the `cordova.1.9.0/ext-air/` folder.
+4. Update the .js file in the `cordova.1.9.0/javascript/` folder.
+5. Open the `sample/lib/` folder and rename the `cordova.1.9.0/` folder to `cordova.2.0.0/`.
+6. Type `ant blackberry build` or `ant playbook build` to update the `www/` folder with updated Cordova.
+7. Open the `www/` folder and update your HTML to use the new `cordova-2.0.0.js` file.
+8. Open the `www/` folder and update the `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"/>
+
+- 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` folder:
+
+1. Open your `www/` folder, which contains your app.
+2. Remove and update the .jar file in the `ext/` folder.
+3. Update the contents of the `ext-air/` folder.
+4. Copy the new `cordova-1.8.0.js` into your project.
+ - If playbook, then update the .js file in the `playbook/` folder.
+5. Update your HTML to use the new `cordova-1.8.0.js` file.
+6. Update your `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 folder (ie, updating using the ant tools):
+
+1. Open the `sample/lib/` folder.
+2. Update the .jar file in the `cordova.1.7.0/ext/` folder.
+3. Update the contents of the `cordova.1.7.0/ext-air/` folder.
+4. Update the .js file in the `cordova.1.7.0/javascript/` folder.
+5. Open the `sample/lib/` folder and rename the `cordova.1.7.0/` folder to `cordova.1.8.0/`.
+6. Type `ant blackberry build` or `ant playbook build` to update the `www/` folder with updated Cordova.
+7. Open the `www/` folder and update your HTML to use the new `cordova-1.8.0.js` file.
+8. Open the `www/` folder and update the `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"/>
+
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/b00c364c/docs/en/3.0.0/guide/platforms/blackberry10/index.md
----------------------------------------------------------------------
diff --git a/docs/en/3.0.0/guide/platforms/blackberry10/index.md b/docs/en/3.0.0/guide/platforms/blackberry10/index.md
new file mode 100644
index 0000000..f3c35cf
--- /dev/null
+++ b/docs/en/3.0.0/guide/platforms/blackberry10/index.md
@@ -0,0 +1,165 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+---
+
+# BlackBerry 10 Platform Guide
+
+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:
+
+* BlackBerry 10 Plugins
+* BlackBerry 10 Command-line Tools
+
+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.
+
+## Requirements
+
+Cordova for BlackBerry has the following software requirements:
+
+- Windows XP (32-bit) or Windows 7 (32-bit and 64-bit) or Mac OSX 10.6.4+
+- node.js (> 0.9.9) [Download node.js now](http://nodejs.org/)
+- BlackBerry 10 Native SDK. [Download the BlackBerry 10 Native SDK now.](http://developer.blackberry.com/native/download/)
+
+## Setting up your signing keys
+
+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.
+
+- [Register for your code signing key now.](https://www.blackberry.com/SignedKeys/codesigning.html)
+- [Set your computer up for code signing. ](http://developer.blackberry.com/html5/documentation/set_up_for_signing.html)
+- [Learn more about debug tokens.](http://developer.blackberry.com/html5/documentation/running_your_bb10_app_2008471_11.html)
+
+## Creating your project
+
+To create a new project, you use the `create` command to set up the folder structure for your app.
+
+1. On the command line, navigate to the folder where you extracted Cordova.
+2. Run the `create` command using the following syntax:
+
+ bin/create <path-to-project>
+
+This command creates the folder structure for your project at the specified location. All of your project resource files should be stored in the *<path-to-project>*/www folder, or in a subfolder within it.
+
+## Adding and managing targets
+
+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.
+
+###Add a target
+
+To add a target, on the command line, type the following command:
+
+ <path-to-project>/cordova/target add <name> <ip-address> [-t | --type <device | simulator>] [-p | --password <password>] [--pin <device-pin>]
+
+where
+
+- `<name>` specifies a unique name for the target.
+- `<ip-address>` specifies the ip address of the BlackBerry device or emulator.
+- `-t <device | simulator>` specifies the target type. If not provided, the default value is device.
+- `-p|--password <password>` specifies the password for the device or emulator. This is required only if the device or emulator is password protected.
+- `--pin <device-pin>` 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.
+
+###Remove a target
+
+To remove a target, on the command line, type the following command:
+
+ <path-to-project>/cordova/target remove <name>
+
+###Set a target as the default
+
+To specify a specific target as the default, on the command line, type the following command:
+
+ <path-to-project>/cordova/target default <name>
+
+## Building your app
+
+To build your app, run the build script. You can build the app in either release mode or in debug mode.
+
+- 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.
+- 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.
+
+ 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 [Debugging using Web Inspector](http://developer.blackberry.com/html5/documentation/web_inspector_overview_1553586_11.html).
+
+###Build your app in release mode
+
+To build your app in release mode, on the command line, type the following command:
+
+ <path-to-project>/cordova/build release -k|--keystorepass <password> [-b|--buildId <number>] [-p|--params <params-JSON-file>]
+
+where
+
+- `-k|--keystorepass <password>` specifies the password you defined when you configured your computer to sign applications.
+- `-b|--buildId <number>` specifies the build version number of your application. Typically, this number should be incremented from the previous signed version. This argument is optional.
+- `-p|--params <params-JSON-file>` specifies a JSON file containing additional parameters to pass to downstream tools. This argument is optional.
+
+###Build your app in debug mode
+
+To build your app in release mode, on the command line, type the following command:
+
+ <path-to-project>/cordova/build debug [<target>] [-k|--keystorepass <password>] [-p|--params <params-JSON-file>] [-ll|--loglevel <error|warn|verbose>]
+
+where
+
+- `<target>` specifies the name of a previously added target. If `<target>` 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 `<target>` 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.
+- `-k|--keystorepass <password>` 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.
+- `-p|--params <params-JSON-file>` specifies a JSON file containing additional parameters to pass to downstream tools.
+- `-ll|--loglevel <level>` specifies the log level. The log level may be one of `error`, `warn`, or `verbose`.
+
+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:
+
+ <path-to-project>/cordova/build debug
+
+## Deploying an app
+
+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.
+
+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 `--keystorepass <password>` 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.
+
+To deploy your app to a device or emulator, on a command line type the following command:
+
+ <path-to-project>/cordova/run <target> [--no-build]
+
+where
+- `<target>` specifies the name of a previously added target. If `<target>` 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.
+
+- `-no--build` will use the most recently built version of the application rather than re-building. This is useful to test an application in release mode.
+
+## Adding and managing plugins
+
+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.
+
+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.
+
+###Add a plugin
+
+To add a plugin, on the command line, type the following command:
+
+ <path-to-project>/cordova/plugin add <path to plugin>
+
+###Remove a plugin
+
+To remove a plugin, on the command line, type the following command:
+
+ <path-to-project>/cordova/plugin rm <name>
+
+###View a list of installed plugins
+
+To view a list of installed plugins, on the command line, type the following command:
+
+ <path-to-project>/cordova/plugin ls