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/04 20:19:50 UTC
[15/20] docs commit: [CB-3827] move platform-specific files within
platforms dir; rename dirs within platforms
[CB-3827] move platform-specific files within platforms dir; rename dirs within platforms
Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/610314b2
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/610314b2
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/610314b2
Branch: refs/heads/master
Commit: 610314b2746ab2f429b7c7fbc24629f46b7dc702
Parents: cfebdc3
Author: Mike Sierra <le...@gmail.com>
Authored: Thu Jul 4 13:25:18 2013 -0400
Committer: Mike Sierra <le...@gmail.com>
Committed: Thu Jul 4 13:25:18 2013 -0400
----------------------------------------------------------------------
docs/en/edge/guide/cordova-webview/android.md | 122 ------
docs/en/edge/guide/cordova-webview/index.md | 27 --
docs/en/edge/guide/cordova-webview/ios.md | 136 ------
docs/en/edge/guide/platforms/android/config.md | 43 ++
docs/en/edge/guide/platforms/android/plugin.md | 192 ++++++++
.../edge/guide/platforms/android/upgrading.md | 242 ++++++++++
docs/en/edge/guide/platforms/android/webview.md | 122 ++++++
.../edge/guide/platforms/blackberry/config.md | 29 ++
.../edge/guide/platforms/blackberry/plugin.md | 153 +++++++
.../guide/platforms/blackberry/upgrading.md | 311 +++++++++++++
.../edge/guide/platforms/blackberry10/plugin.md | 191 ++++++++
.../en/edge/guide/platforms/firefoxos/config.md | 24 +
docs/en/edge/guide/platforms/ios/config.md | 60 +++
docs/en/edge/guide/platforms/ios/plugin.md | 230 ++++++++++
docs/en/edge/guide/platforms/ios/upgrading.md | 438 +++++++++++++++++++
docs/en/edge/guide/platforms/ios/webview.md | 136 ++++++
docs/en/edge/guide/platforms/win8/config.md | 26 ++
docs/en/edge/guide/platforms/win8/index.md | 111 +++++
docs/en/edge/guide/platforms/win8/tools.md | 44 ++
.../guide/platforms/win8/upgrading.md/index.md | 39 ++
docs/en/edge/guide/platforms/windows-8/index.md | 111 -----
docs/en/edge/guide/platforms/windows-8/tools.md | 44 --
.../guide/platforms/windows-phone-7/index.md | 95 ----
.../guide/platforms/windows-phone-8/index.md | 135 ------
.../guide/platforms/windows-phone-8/tools.md | 77 ----
docs/en/edge/guide/platforms/wp7/config.md | 25 ++
docs/en/edge/guide/platforms/wp7/index.md | 95 ++++
docs/en/edge/guide/platforms/wp8/config.md | 25 ++
docs/en/edge/guide/platforms/wp8/index.md | 135 ++++++
docs/en/edge/guide/platforms/wp8/plugin.md | 194 ++++++++
docs/en/edge/guide/platforms/wp8/tools.md | 77 ++++
docs/en/edge/guide/platforms/wp8/upgrading.md | 236 ++++++++++
.../guide/plugin-development/android/index.md | 192 --------
.../plugin-development/blackberry/index.md | 153 -------
.../plugin-development/blackberry10/index.md | 191 --------
docs/en/edge/guide/plugin-development/index.md | 110 -----
.../edge/guide/plugin-development/ios/index.md | 230 ----------
.../plugin-development/windows-phone/index.md | 194 --------
docs/en/edge/guide/plugins/index.md | 110 +++++
.../guide/project-settings/android/index.md | 43 --
.../guide/project-settings/blackberry/index.md | 29 --
.../guide/project-settings/firefoxos/index.md | 24 -
.../en/edge/guide/project-settings/ios/index.md | 60 ---
.../guide/project-settings/windows8/index.md | 26 --
.../en/edge/guide/project-settings/wp7/index.md | 25 --
.../en/edge/guide/project-settings/wp8/index.md | 25 --
docs/en/edge/guide/upgrading/android/index.md | 242 ----------
.../en/edge/guide/upgrading/blackberry/index.md | 311 -------------
docs/en/edge/guide/upgrading/ios/index.md | 438 -------------------
docs/en/edge/guide/upgrading/windows-8/index.md | 39 --
.../edge/guide/upgrading/windows-phone/index.md | 236 ----------
docs/en/edge/guide/webviews/index.md | 27 ++
52 files changed, 3315 insertions(+), 3315 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/610314b2/docs/en/edge/guide/cordova-webview/android.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/cordova-webview/android.md b/docs/en/edge/guide/cordova-webview/android.md
deleted file mode 100644
index c3c96b3..0000000
--- a/docs/en/edge/guide/cordova-webview/android.md
+++ /dev/null
@@ -1,122 +0,0 @@
----
-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/610314b2/docs/en/edge/guide/cordova-webview/index.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/cordova-webview/index.md b/docs/en/edge/guide/cordova-webview/index.md
deleted file mode 100644
index 649a5e8..0000000
--- a/docs/en/edge/guide/cordova-webview/index.md
+++ /dev/null
@@ -1,27 +0,0 @@
----
-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.
----
-
-Embedding WebViews
-=================
-
-> Implement the Cordova WebView in your own project.
-
-- Android WebViews
-- iOS WebViews
-
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/610314b2/docs/en/edge/guide/cordova-webview/ios.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/cordova-webview/ios.md b/docs/en/edge/guide/cordova-webview/ios.md
deleted file mode 100644
index 445016a..0000000
--- a/docs/en/edge/guide/cordova-webview/ios.md
+++ /dev/null
@@ -1,136 +0,0 @@
----
-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.
----
-
-iOS WebViews
-================================
-
-Beginning with Cordova 1.4, you can use Cordova as a component in your
-iOS applications. This component is code-named 'Cleaver'.
-
-New Cordova-based applications created using the Xcode template
-provided in Cordova 1.4 or greater use Cleaver. (The template is
-Cleaver's reference implementation.)
-
-Cordova 2.0.0 and subsequent versions only support the sub-project
-based Cleaver implementation.
-
-Prerequisites
--------------
-
-1. **Cordova 2.3.0** or greater
-2. **Xcode 4.5** or greater
-3. `config.xml` file (from a newly created iOS project)
-
-Adding Cleaver to your Xcode project (CordovaLib sub-project)
--------------------------------------------------------------
-
-1. **Download and extract the Cordova source** to a **permanent folder location** on your hard drive (say to `~/Documents/Cordova`)
-2. **Quit Xcode** if it is running.
-3. **Navigate** to the directory where you put the downloaded source above, using **Terminal.app**.
-4. **Copy** the `config.xml` file into your project folder on disk (see **Prerequisites** above)
-5. **Drag and drop** the `config.xml` file into the Project Navigator of Xcode
-6. **Choose** the **Create groups for any added folders** radio button and press **Finish**
-7. **Drag and drop** the `CordovaLib.xcodeproj` file into the Project Navigator of Xcode (from the permanent folder location above, and it should be in the CordovaLib sub-folder)
-8. Select `CordovaLib.xcodeproj` in the Project Navigator
-9. Type the **Option-Command-1** key combination to show the **File Inspector**
-10. Choose **Relative to Group** in the **File Inspector** for the drop-down menu for **Location**
-11. Select the **project icon** in the Project Navigator, select your **Target**, then select the **Build Settings** tab
-12. Add `-all_load` and `-Obj-C` for the **Other Linker Flags** value
-13. Click on the **project icon** in the Project Navigator, select your **Target**, then select the **Build Phases** tab
-14. Expand **Link Binaries with Libraries**
-15. Select the **+** button, and add these **frameworks** (and optionally in the Project Navigator, **move** them under the Frameworks group):
-
- AddressBook.framework
- AddressBookUI.framework
- AudioToolbox.framework
- AVFoundation.framework
- CoreLocation.framework
- MediaPlayer.framework
- QuartzCore.framework
- SystemConfiguration.framework
- MobileCoreServices.framework
- CoreMedia.framework
-
-16. Expand **Target Dependencies** - the top box labeled like this if you have multiple boxes!
-17. Select the **+** button, and add the `CordovaLib` build product
-18. Expand **Link Binaries with Libraries** - the top box labeled like
- this if you have multiple boxes!
-19. Select the **+** button, and add `libCordova.a`
-20. Set the Xcode preference **Xcode Preferences → Locations → Derived Data → Advanced...** to **Unique**
-21. Select the **project icon** in the Project Navigator, select your **Target**, then select the **Build Settings** tab
-22. Search for **Header Search Paths**. For that setting, add these three values below (with quotes):
-
- "$(TARGET_BUILD_DIR)/usr/local/lib/include"
- "$(OBJROOT)/UninstalledProducts/include"
- "$(BUILT_PRODUCTS_DIR)"
-
- With **Cordova 2.1.0**, CordovaLib has been upgraded to use **Automatic Reference Counting (ARC)**. You don't need to upgrade to **ARC** to use CordovaLib, but if you want to upgrade your project to use **ARC**, please use the Xcode migration wizard from the menu: **Edit → Refactor → Convert to Objective-C ARC...**, **de-select libCordova.a**, then run the wizard to completion.
-
-Using CDVViewController in your code
-------------------------------------
-
-1. Add this **header**:
-
- #import <Cordova/CDVViewController.h>
-
-2. Instantiate a **new** `CDVViewController`, and **retain it somewhere** (e.g. to a property in your class):
-
- CDVViewController* viewController = [CDVViewController new];
-
-3. (_OPTIONAL_) Set the `wwwFolderName` property (defaults to `www`):
-
- viewController.wwwFolderName = @"myfolder";
-
-4. (_OPTIONAL_) Set the start page in your config.xml, the `<content>` tag.
-
- <content src="index.html" />
-
- OR
-
- <content src="http://apache.org" />
-
-5. (_OPTIONAL_) Set the `useSplashScreen` property (defaults to `NO`):
-
- viewController.useSplashScreen = YES;
-
-6. Set the **view frame** (always set this as the last property):
-
- viewController.view.frame = CGRectMake(0, 0, 320, 480);
-
-7. **Add** Cleaver to your view:
-
- [myView addSubview:viewController.view];
-
-Adding your HTML, CSS and JavaScript assets
--------------------------------------------
-
-1. Create a **new folder** in your project **on disk**, `www` for example.
-2. Put your **HTML, CSS and JavaScript** assets into this folder.
-3. **Drag and drop** the folder into the Project Navigator of Xcode.
-4. **Choose** the **Create folder references for any added folders** radio button.
-5. **Set the appropriate `wwwFolderName` and `startPage` properties** for the folder you created in **(1)** or use the defaults (see previous section) when you instantiate the `CDVViewController`.
-
- /*
- if you created a folder called 'myfolder' and
- you want the file 'mypage.html' in it to be
- the startPage
- */
- viewController.wwwFolderName = @"myfolder";
- viewController.startPage = @"mypage.html"
-
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/610314b2/docs/en/edge/guide/platforms/android/config.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/android/config.md b/docs/en/edge/guide/platforms/android/config.md
new file mode 100644
index 0000000..b3c02b5
--- /dev/null
+++ b/docs/en/edge/guide/platforms/android/config.md
@@ -0,0 +1,43 @@
+<!--
+#
+# 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 Configuration
+===================================
+
+The `config.xml` settings file controls various settings of Cordova. This is application wide, and not set per CordovaWebView Instance.
+
+## <preference>
+
+Various **other** preferences (as **<preference>** tags) default on not breaking existing apps. The available preferences are:
+
+1. **useBrowserHistory (boolean, defaults to true)** - set to false if you want to use the history shim that was used to work around the hashtag error present in Android 3.x prior to the history fix. (Note: This setting will be deprecated in April 2013)
+2. **loadingDialog** - Display a native loading dialog when loading the app. The value's format is _Title, Message_
+3. **loadingPageDialog** - Display a native loading dialog when loading sub-pages. The value's format is _Title, Message_
+4. **errorUrl** - Set the error page for your application. Should be located in your Android project in file://android_asset/www/
+5. **backgroundColor** - Set the background color for your application. Supports a four-byte hex value, with the first byte representing alpha value, and the following three bytes with standard RGB values. (i.e. 0x00000000 = Black)
+6. **loadUrlTimeoutValue** - How much time Cordova should wait before throwing a timeout error on the application.
+7. **keepRunning (boolean, defaults to true)** - Determines whether Cordova will keep running in the background or not
+8. **splashscreen** - The name of the file minus its extension in the res/drawable directory. If you have multiple assets, they all must share this common name in their respective directories.
+9. **disallowOverscroll (boolean, defaults to false)** - set to true if you want to disable the glow when a user scrolls beyond the edge of the webview.
+
+## <plugin>
+
+Android supports using <feature> as analogues to <plugin> elements.
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/610314b2/docs/en/edge/guide/platforms/android/plugin.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/android/plugin.md b/docs/en/edge/guide/platforms/android/plugin.md
new file mode 100644
index 0000000..39a79d7
--- /dev/null
+++ b/docs/en/edge/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
+
+We have JavaScript to fire off a plugin request to the native side. We
+have the Android Java plugin 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
+
+We would add the following to our config.xml:
+
+ <plugin name="Echo" value="org.apache.cordova.plugin.Echo" />
+
+Then we would 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/610314b2/docs/en/edge/guide/platforms/android/upgrading.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/android/upgrading.md b/docs/en/edge/guide/platforms/android/upgrading.md
new file mode 100644
index 0000000..63019d3
--- /dev/null
+++ b/docs/en/edge/guide/platforms/android/upgrading.md
@@ -0,0 +1,242 @@
+---
+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 document is for people who need to upgrade their Cordova versions from an older version to a current version of Cordova.
+
+## 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 libs directory in your project
+2. Add cordova-2.8.0.jar to the libs directory in your project
+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 to be the same as the one found in 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 cordova directory in your project
+
+## Upgrade to 2.7.0 from 2.6.0 ##
+1. Remove cordova-2.6.0.jar from the libs directory in your project
+2. Add cordova-2.7.0.jar to the libs directory in your project
+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 be the same as the one found in 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 cordova directory in your project
+
+
+## Upgrade to 2.6.0 from 2.5.0 ##
+1. Remove cordova-2.5.0.jar from the libs directory in your project
+2. Add cordova-2.6.0.jar to the libs directory in your project
+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 be the same as the one found in 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 cordova directory in your project
+
+. 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 libs directory in your project
+2. Add cordova-2.5.0.jar to the libs directory in your project
+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 be the same as the one found in 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 cordova directory in your project
+
+## Upgrade to 2.4.0 from 2.3.0 ##
+
+1. Remove cordova-2.3.0.jar from the libs directory in your project
+2. Add cordova-2.4.0.jar to the libs directory in your project
+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 be the same as the one found in framework/res/xml/config.xml
+7. Copy files from bin/templates/cordova to the cordova directory in your project
+
+## Upgrade to 2.3.0 from 2.2.0 ##
+
+1. Remove cordova-2.2.0.jar from the libs directory in your project
+2. Add cordova-2.3.0.jar to the libs directory in your project
+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 be the same as the one found in framework/res/xml/config.xml
+7. Copy files from bin/templates/cordova to the cordova directory in your project
+
+## Upgrade to 2.2.0 from 2.1.0 ##
+
+1. Remove cordova-2.1.0.jar from the libs directory in your project
+2. Add cordova-2.2.0.jar to the libs directory in your project
+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 be the same as the one found in framework/res/xml/config.xml
+7. Copy files from bin/templates/cordova to the cordova directory in your project
+
+## Upgrade to 2.1.0 from 2.0.0 ##
+
+1. Remove cordova-2.0.0.jar from the libs directory in your project
+2. Add cordova-2.1.0.jar to the libs directory in your project
+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 be the same as the one found in framework/res/xml/config.xml
+7. Copy files from bin/templates/cordova to the cordova directory in your project
+
+## Upgrade to 2.0.0 from 1.9.0 ##
+
+1. Remove cordova-1.9.0.jar from the libs directory in your project
+2. Add cordova-2.0.0.jar to the libs directory in your project
+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 be the same as the one found in 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 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 libs directory in your project
+2. Add cordova-1.9.0.jar to the libs directory in your project
+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 the res/xml/plugins.xml to be the same as the one found in 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 libs directory in your project
+2. Add cordova-1.8.1.jar to the libs directory in your project
+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 the res/xml/plugins.xml to be the same as the one found in framework/res/xml/plugins.xml
+
+## Upgrade to 1.8.0 from 1.7.0 ##
+
+1. Remove cordova-1.7.0.jar from the libs directory in your project
+2. Add cordova-1.8.0.jar to the libs directory in your project
+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 the res/xml/plugins.xml to be the same as the one found in framework/res/xml/plugins.xml
+
+## Upgrade to 1.8.0 from 1.7.0 ##
+
+1. Remove cordova-1.7.0.jar from the libs directory in your project
+2. Add cordova-1.8.0.jar to the libs directory in your project
+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 the res/xml/plugins.xml to be the same as the one found in framework/res/xml/plugins.xml
+
+## Upgrade to 1.7.0 from 1.6.1 ##
+
+1. Remove cordova-1.6.1.jar from the libs directory in your project
+2. Add cordova-1.7.0.jar to the libs directory in your project
+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 the res/xml/plugins.xml to be the same as the one found in framework/res/xml/plugins.xml
+
+## Upgrade to 1.6.1 from 1.6.0 ##
+
+1. Remove cordova-1.6.0.jar from the libs directory in your project
+2. Add cordova-1.6.1.jar to the libs directory in your project
+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 the res/xml/plugins.xml to be the same as the one found in framework/res/xml/plugins.xml
+
+## Upgrade to 1.6.0 from 1.5.0 ##
+1. Remove cordova-1.5.0.jar from the libs directory in your project
+2. Add cordova-1.6.0.jar to the libs directory in your project
+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 the res/xml/plugins.xml so that it is the same as the one found in framework/res/xml/plugins.xml
+7. Replace the res/xml/phonegap.xml with res/xml/cordova.xml so that it is the same as the one found in framework/res/xml/cordova.xml
+
+## Upgrade to 1.5.0 from 1.4.0##
+1. Remove phonegap-1.4.0.jar from the libs directory in your project
+2. Add cordova-1.5.0.jar to the libs directory in your project
+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 the res/xml/plugins.xml so that it is the same as the one found in framework/res/xml/plugins.xml
+7. Replace the res/xml/phonegap.xml with res/xml/cordova.xml so that it is the same as the one found in framework/res/xml/cordova.xml
+
+## Upgrade to 1.4.0 from 1.3.0 ##
+1. Remove phonegap-1.3.0.jar from the libs directory in your project
+2. Add phonegap-1.4.0.jar to the libs directory in your project
+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 the res/xml/plugins.xml so that it is the same as the one found in framework/res/xml/plugins.xml
+7. Update the res/xml/phonegap.xml so that it is the same as the one found in framework/res/xml/phonegap.xml
+
+## Upgrade to 1.3.0 from 1.2.0 ##
+1. Remove phonegap-1.2.0.jar from the libs directory in your project
+2. Add phonegap-1.3.0.jar to the libs directory in your project
+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 the res/xml/plugins.xml so that it is the same as the one found in framework/res/xml/plugins.xml
+7. Update the res/xml/phonegap.xml so that it is the same as the one found in framework/res/xml/phonegap.xml
+
+## Upgrade to 1.2.0 from 1.1.0 ##
+1. Remove phonegap-1.1.0.jar from the libs directory in your project
+2. Add phonegap-1.2.0.jar to the libs directory in your project
+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 the res/xml/plugins.xml so that it is the same as the one found in framework/res/xml/plugins.xml
+7. Update the res/xml/phonegap.xml so that it is the same as the one found in framework/res/xml/phonegap.xml
+
+## Upgrade to 1.1.0 from 1.0.0 ##
+1. Remove phonegap-1.0.0.jar from the libs directory in your project
+2. Add phonegap-1.1.0.jar to the libs directory in your project
+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 the res/xml/plugins.xml so that it is the same as the one found in framework/res/xml/plugins.xml
+
+## Upgrade to 1.0.0 from 0.9.6 ##
+1. Remove phonegap-0.9.6.jar from the libs directory in your project
+2. Add phonegap-1.0.0.jar to the libs directory in your project
+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 so that it is the same as the one found in framework/res/xml/plugins.xml
+
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/610314b2/docs/en/edge/guide/platforms/android/webview.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/android/webview.md b/docs/en/edge/guide/platforms/android/webview.md
new file mode 100644
index 0000000..c3c96b3
--- /dev/null
+++ b/docs/en/edge/guide/platforms/android/webview.md
@@ -0,0 +1,122 @@
+---
+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/610314b2/docs/en/edge/guide/platforms/blackberry/config.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/blackberry/config.md b/docs/en/edge/guide/platforms/blackberry/config.md
new file mode 100644
index 0000000..ab266ad
--- /dev/null
+++ b/docs/en/edge/guide/platforms/blackberry/config.md
@@ -0,0 +1,29 @@
+<!--
+#
+# 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/610314b2/docs/en/edge/guide/platforms/blackberry/plugin.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/blackberry/plugin.md b/docs/en/edge/guide/platforms/blackberry/plugin.md
new file mode 100644
index 0000000..ebdb780
--- /dev/null
+++ b/docs/en/edge/guide/platforms/blackberry/plugin.md
@@ -0,0 +1,153 @@
+---
+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
+=================================
+
+## How to make the Echo plugin on Blackberry
+
+This guide explores how to develop the Echo plugin on BlackBerry.
+If you haven't read the top-level guide about the JavaScript part of
+the plugin, it would be best if you read that first and then this
+guide. In addition, please download the [Cordova Blackberry
+repo](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 a the Torch and Bold, as well as the Playbook. There's a
+difference between deploying to normal BlackBerry handheld devices and
+the Playbook. They use two different code bases, so when you develop
+for one, you have to duplicate your efforts for the other! This guide
+focuses on the handheld devices rather than the tablet. (In the future,
+this guide should cover both platforms.)
+
+Continuing on from the previous guide, the Echo plugin essentially
+returns whatever message a user provides to the `window.echo`
+function.
+
+The 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/610314b2/docs/en/edge/guide/platforms/blackberry/upgrading.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/blackberry/upgrading.md b/docs/en/edge/guide/platforms/blackberry/upgrading.md
new file mode 100644
index 0000000..a50cddb
--- /dev/null
+++ b/docs/en/edge/guide/platforms/blackberry/upgrading.md
@@ -0,0 +1,311 @@
+---
+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 document describes the process of upgrading Cordova projects to the latest released version
+
+## Upgrading 2.8.0 projects to 2.9.0 ##
+
+### BlackBerry10 ###
+
+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 IDE's** Eclipse, Momentics and the lik
+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 IDE's** 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 ##
+
+### BlackBerry10 ###
+
+BlackBerry10 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 IDE's** 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 IDE's** 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 IDE's** 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 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 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 BlackBerry10, 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 BlackBerry10, 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 BlackBerry10, 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/610314b2/docs/en/edge/guide/platforms/blackberry10/plugin.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/blackberry10/plugin.md b/docs/en/edge/guide/platforms/blackberry10/plugin.md
new file mode 100644
index 0000000..5eb1401
--- /dev/null
+++ b/docs/en/edge/guide/platforms/blackberry10/plugin.md
@@ -0,0 +1,191 @@
+---
+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 Plugins
+
+This is a continuation of the Plugin Development Guide for Cordova. Once you have reviewed that content, now let's look at things we need to have the Echo plugin for the BlackBerry 10 platform. Recall that the Echo plugin basically returns whatever string 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]);
+ };
+
+A native BlackBerry 10 plugin for Cordova contains JavaScript code and may also contain native code. The Echo plugin example demonstrates how to invoke native functionality from JavaScript. The native and JavaScript code communicate with each other through a framework provided by JNEXT. Every plugin must also include a plugin.xml file.
+
+
+## Creating the native part of your plugin ##
+
+To create the native portion of your plugin, open the BlackBerry 10 NDK IDE and select File > New > BlackBerry Project > Native Extension > BlackBerry WebWorks. Enter your desired project name / location and click finish.
+
+The project created by the IDE contains sample code for a memory plugin. You may replace or modify these files to include your own functionality.
+
+- ***name*_js.hpp** - C++ header for the JNEXT code.
+- ***name*_js.cpp** - C++ code for JNEXT.
+
+The native interface for the JNEXT extension can be viewed in the plugin header file located in the public folder of your project. It also contains constants and utility functions that can be used in your native code. Your plugin must be derived from JSExt which is defined in plugin.h. That is, you must implement the following class:
+
+ class JSExt
+ {
+ public:
+ virtual ~JSExt() {};
+ virtual string InvokeMethod( const string& strCommand ) = 0;
+ virtual bool CanDelete( void ) = 0;
+ private:
+ std::string m_id;
+ };
+
+Therefore, your extension should include the plugin.h header file. In the Echo example, you use JSExt as follows in the echo_js.hpp file:
+
+ #include "../public/plugin.h"
+ #include <string>
+
+ #ifndef ECHO_JS_H_
+ #define ECHO_JS_H_
+
+ class Echo : public JSExt
+ {
+ public:
+ explicit Echo(const std::string& id);
+ virtual ~Echo();
+ virtual std::string InvokeMethod(const std::string& command);
+ virtual bool CanDelete();
+ private:
+ std::string m_id;
+ };
+
+ #endif // ECHO_JS_H_
+
+The `m_id` is an attribute that contains the JNEXT id for this object. The id is passed to the class as an argument to the constructor. It is needed to trigger events on the JavaScript side from native.
+The CanDelete method is used by JNEXT to determine whether your native object can be deleted.
+The InvokeMethod function is called as a result from a request from JavaScript to invoke a method of this particular object. The only argument to this function is a string passed from JavaScript that this method should parse in order to determine which method of the native object should be executed.
+Now we implement these functions in echo_js.cpp. For the Echo example, we implement InvokeMethod function as follows:
+
+ string Echo::InvokeMethod(const string& command) {
+
+ //parse command and args from string
+ int index = command.find_first_of(" ");
+ string strCommand = command.substr(0, index);
+ string strValue = command.substr(index + 1, command.length());
+
+ // Determine which function should be executed
+ if (strCommand == "echo") {
+ return strValue;
+ } else {
+ return "Unsupported Method";
+ }
+ }
+
+Your native plugin must also implement the following callback functions:
+
+- `extern char* onGetObjList( void );`
+- `extern JSExt* onCreateObject( const string& strClassName, const string& strObjId );`
+
+The `onGetObjList` function returns a comma separated list of classes supported by JNEXT. JNEXT uses this function to determine the set of classes that JNEXT can instantiate. In our Echo plugin, we have the following in `echo_js.cpp`:
+
+ char* onGetObjList() {
+ static char name[] = "Echo";
+ return name;
+ }
+
+The `onCreateObject ` function takes two parameters. The first parameter is the name of the class requested to be created from the JavaScript side. Valid names are those that are returned in `onGetObjList`. The second parameter is the unique object id for the class. This method returns a pointer to the created plugin object. In our Echo plugin, we have the following in `echo_js.cpp`:
+
+ JSExt* onCreateObject(const string& className, const string& id) {
+ if (className == "Echo") {
+ return new Echo(id);
+ }
+ return NULL;
+ }
+
+##Creating the JavaScript part of your plugin##
+
+The JavaScript portion of your plugin must contain the following files:
+
+- **client.js** – This is considered the client side and contains the API that a Cordova application can call. The API in client.js calls makes calls to index.js. The API in client.js also connects callback functions to the events that fire the callbacks.
+
+- **index.js** – Cordova loads index.js and makes it accessible through the cordova.exec bridge. The client.js file makes calls to the API in the index.js file, which in turn makes call to JNEXT to communicate with the native side.
+
+The client and server side (client.js and index.js) interacts through the `Cordova.exec `function. So, in client.js you invoke the exec function and provide the necessary arguments. In the Echo plugin, we have the following in the client.js file:
+
+ var service = "org.apache.cordova.blackberry.echo",
+ exec = cordova.require("cordova/exec");
+
+ module.exports = {
+ echo: function (data, success, fail) {
+ exec(success, fail, service, "echo", { data: data });
+ }
+ };
+
+Now, index.js interacts with the native side using JNEXT. So you attach a constructor function named Echo to JNEXT. Within the constructor you perform the following key operations using the init function:
+
+- Specify the required module exported by the native side. The name of the required module must match the name of a shared library file (.so file).
+
+`JNEXT.require("libecho")`
+
+- Create an object by using an acquired module and save the ID that's returned by the call.
+self.m_id = JNEXT.createObject("libecho.Echo");
+When your application calls the echo function in client.js, that call in turn calls the echo function in index.js, where the PluginResult object sends a response (data) back to client.js. Since the args argument passed into the functions was converted by JSON.stringfy() and encoded as a URIcomponent, you must call the following:
+
+`data = JSON.parse(decodeURIComponent(args.data));`
+
+You can now send the data back. Let’s put it all together:
+
+ module.exports = {
+
+ echo: function (success, fail, args, env) {
+
+ var result = new PluginResult(args, env),
+ data = JSON.parse(decodeURIComponent(args.data)),
+ response = echo.getInstance().echo(data);
+ result.ok(response, false);
+ }
+ };
+
+## Architecture of the plugin ##
+
+You can place the artifacts of the plugin, which includes the plugin.xml file, the source files (JavaScript, C++), and the binary files (.so) within any directory structure, as long as you correctly specify the file locations in the plugin.xml file. Below we show a typical structure that you can follow:
+
+***your_project_folder*** (>plugin.xml)
+
+- **www** (>client.js)
+- **src**
+ - **blackberry10** (>index.js, **native** >*.cpp, *.hpp)
+ - **device** (>*biary file* *.so)
+ - **simulator** (>*binary file* *.so)
+
+(The list shows the hierarchical relationship among the top level folders. The parenthesis shows the contents of a given folder. All folder names appear in bold text. File names are preceded by the '>' sign.)
+
+## Contents of the plugin.xml file##
+The plugin.xml file contains the namespace of the extension and other metadata. Define the namespace and specify other metadata for the Echo plugin as follows:
+
+ <plugin xmlns="http://www.phonegap.com/ns/plugins/1.0"
+ id="org.apache.cordova.blackberry.echo"
+ version="1.0.0">
+ <js-module src="www/client.js">
+ <merges target="navigator" />
+ </js-module>
+ <platform name="blackberry10">
+ <source-file src="src/blackberry10/index.js" />
+ <lib-file src="src/blackberry10/native/device/libecho.so" arch="device" />
+ <lib-file src="src/blackberry10/native/simulator/libecho.so" arch="simulator" />
+ <config-file target="www/config.xml" parent="/widget">
+ <feature name="org.apache.cordova.blackberry.echo" value="org.apache.cordova.blackberry.echo" />
+ </config-file>
+ </platform>
+ </plugin>