cordova-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From dblot...@apache.org
Subject [19/51] [partial] docs commit: Renaming 6.0.0 to 6.x.
Date Fri, 26 Feb 2016 01:00:20 GMT
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/21c8e8f0/www/docs/en/6.x/guide/platforms/android/lifecycle.md
----------------------------------------------------------------------
diff --git a/www/docs/en/6.x/guide/platforms/android/lifecycle.md b/www/docs/en/6.x/guide/platforms/android/lifecycle.md
new file mode 100644
index 0000000..4c54359
--- /dev/null
+++ b/www/docs/en/6.x/guide/platforms/android/lifecycle.md
@@ -0,0 +1,323 @@
+---
+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.
+
+title: Android Lifecycle Guide
+---
+
+# Android Lifecycle Guide
+
+## Cordova and Android
+
+Native Android apps typically consist of a series of [activities](http://developer.android.com/reference/android/app/Activity.html) that the user
+interacts with. Activities can be thought of as the individual screens that make
+up an application; different tasks in an app will often have their own activity.
+Each activity has its own lifecycle that is maintained as the activity enters
+and leaves the foreground of a user's device.
+
+In contrast, Cordova applications on the Android platform are executed within a
+Webview that is embedded in a *single* Android activity. The lifecycle of this
+activity is exposed to your application through the document events that are
+fired. The events are not guaranteed to line up with Android's lifecycle, but
+they can provide guidelines for saving and restoring your state. These events
+roughly map to Android callbacks as follows:
+
+Cordova Event   | Rough Android Equivalent  | Meaning
+----------------|---------------------------|-----------------
+`deviceready`   | `onCreate()`              | Application is starting (not from background)
+`pause`         | `onPause()`               | Application is moving to the background
+`resume`        | `onResume()`              | Application is returning to the foreground
+
+Most other Cordova platforms have a similar concept of lifecycles and should
+fire these same events when similar actions happen on a user's device. However,
+Android presents some unique challenges that can sometimes show up thanks to the
+native Activity lifecycle.
+
+## What makes Android different?
+
+In Android, the OS can choose to kill activities in the background in
+order to free up resources if the device running the application is low on
+memory. Unfortunately, when the activity holding your application is killed,
+the Webview in which your application lives will be destroyed as well. Any state
+that your application is maintaining will be lost in this case. When the user
+navigates back to your application, the Activity and Webview will be
+recreated by the OS, but state will not be automatically restored for your
+Cordova app. For this reason, it is imperative that your application be aware of
+the lifecycle events that are fired and maintain whatever state is appropriate
+to make sure a user's context in your app is not lost when they leave the
+application.
+
+## When can this happen?
+
+Your application is susceptible to being destroyed by the OS whenever it leaves
+the sight of the user. There are two main situations in which this can occur.
+The first and most obvious case is when the user presses the home button or
+switches to another application.
+
+However, there is a second (and much more subtle) case that certain plugins can
+introduce. As noted above, Cordova applications are usually confined to the
+single activity that contains the Webview. However, there are instances in which
+other activities may be launched by plugins and temporarily push the Cordova
+activity to the background. These other Activities are typically launched in
+order to perform a specific task using a native application installed on the
+device. For example, the Apache camera plugin launches whatever camera activity
+is natively installed on the device in order to take a photo. Reusing the
+installed camera application in this way makes your application feel much more
+like a native app when the user tries to take a photo. Unfortunately, when the
+native Activity pushes your app to the background there is a chance the OS
+will kill it.
+
+For a clearer understanding of this second case, let's walk through an example
+using the camera plugin. Imagine you have an application that requires the user
+to take a profile photo. The flow of events in the application when everything
+goes as planned will look something like this:
+
+1. The user is interacting with your app and needs to take a picture
+2. The camera plugin launches the native camera activity
+    * *The Cordova activity is pushed to the background (pause event is fired)*
+3. The user takes a photo
+4. The camera activity finishes
+    * *The Cordova activity is moved to the foreground (resume event is fired)*
+5. The user is returned to your application where they left off
+
+However, this flow of events can be disrupted if a device is low on memory. If
+the Activity is killed by the OS, the above sequence of events instead plays out
+as follows:
+
+1. The user is interacting with your app and needs to take a picture
+2. The camera plugin launches the native camera activity
+    * *The OS destroys the Cordova activity (pause event is fired)*
+3. The user takes a photo
+4. The camera activity finishes
+    * *The OS recreates the Cordova activity (deviceready and resume events are fired)*
+5. The user is confused as to why they are suddenly back at your app's login screen
+
+In this instance, the OS killed the application in the background and the
+application did not maintain its state as part of the lifecycle. When the user
+returned to the app, the Webview was recreated and the app appeared to have
+restarted from scratch (hence the user's confusion). This sequence of events is
+equivalent to what happens when the home button is pressed or the user switches
+applications. The key to preventing the above experience is subscribing to
+events and properly maintaining state as part of the activity lifecycle.
+
+## Respecting the Lifecycle
+
+In the examples above, the javascript events that are fired are noted in
+italics. These events are your opportunity to save and restore your
+application's state. You should register callbacks in your application's
+`bindEvents` function that respond to the lifecycle events by saving state. What
+information you save and how you save it is left to your discretion, but you
+should be sure to save enough information so that you can restore the user to
+exactly where they left off when they return to your application.
+
+There is one additional factor in the example above that only applies in the
+second-discussed situation (i.e. when a plugin launches an external activity).
+Not only was the state of the application lost when the user finished taking a
+photo, but so was the photo that the user took. Normally, that photo would be
+delivered to your application through the callback that was registered with the
+camera plugin. However, when the Webview was destroyed that callback was lost
+forever. Luckily, cordova-android 5.1.0 and above provide a means for getting
+the result of that plugin call when your application resumes.
+
+## Retrieving plugin callback results (cordova-android 5.1.0+)
+
+When the OS destroys the Cordova activity that was pushed into the background
+by a plugin, any pending callbacks are lost as well. This means that if you
+passed a callback to the plugin that launched the new activity (e.g. the camera
+plugin), that callback will NOT be fired when the application is recreated.
+However, starting in cordova-android **5.1.0**, the `resume` event's payload will
+contain any pending plugin results from the plugin request that launched the
+external activity made prior to the activity being destroyed.
+
+The payload for the `resume` event adheres to the following format:
+
+```
+{
+    action: "resume",
+    pendingResult: {
+        pluginServiceName: string,
+        pluginStatus: string,
+        result: any
+    }
+}
+```
+
+The fields of that payload are defined as follows:
+
+* `pluginServiceName`: The name of the plugin returning the result (e.g. "Camera"). This can be found in the `<name>` tag of a plugin's plugin.xml file
+* `pluginStatus`: The status of the plugin call (see below)
+* `result`: Whatever the result of the plugin call is
+
+The possible values for `pluginStatus` in the `pendingResult` field include the following:
+* `"OK"` - The plugin call was successful
+* `"No Result"` - The plugin call ended with no result
+* `"Error"` - The plugin call resulted in some general error
+* Other miscellaneous errors
+    * `"Class not found"`
+    * `"Illegal access"`
+    * `"Instantiation error"`
+    * `"Malformed url"`
+    * `"IO error"`
+    * `"Invalid action"`
+    * `"JSON error"`
+
+Please note that it is up to the plugin to decide what is contained in the
+`result` field and the meaning of the `pluginStatus` that is returned. Reference
+the API of the plugin you are using to see what you should expect those fields
+to contain and how to use their values.
+
+### Example
+
+Below is a brief example application that uses the `resume` and `pause` events
+to manage state. It uses the Apache camera plugin as an example of how to
+retrieve the results of a plugin call from the `resume` event payload. The
+portion of the code dealing with the `resume`'s `event.pendingResult` object
+requires cordova-android **5.1.0+**
+
+```javascript
+// This state represents the state of our application and will be saved and
+// restored by onResume() and onPause()
+var appState = {
+    takingPicture: true,
+    imageUri: ""
+};
+
+var APP_STORAGE_KEY = "exampleAppState";
+
+var app = {
+    initialize: function() {
+        this.bindEvents();
+    },
+    bindEvents: function() {
+        // Here we register our callbacks for the lifecycle events we care about
+        document.addEventListener('deviceready', this.onDeviceReady, false);
+        document.addEventListener('pause', this.onPause, false);
+        document.addEventListener('resume', this.onResume, false);
+    },
+    onDeviceReady: function() {
+        document.getElementById("take-picture-button").addEventListener("click", function() {
+            // Because the camera plugin method launches an external Activity,
+            // there is a chance that our application will be killed before the
+            // success or failure callbacks are called. See onPause() and
+            // onResume() where we save and restore our state to handle this case
+            appState.takingPicture = true;
+
+            navigator.camera.getPicture(cameraSuccessCallback, cameraFailureCallback,
+                {
+                    sourceType: Camera.PictureSourceType.CAMERA,
+                    destinationType: Camera.DestinationType.FILE_URI,
+                    targetWidth: 250,
+                    targetHeight: 250
+                }
+            );
+        });
+    },
+    onPause: function() {
+        // Here, we check to see if we are in the middle of taking a picture. If
+        // so, we want to save our state so that we can properly retrieve the
+        // plugin result in onResume(). We also save if we have already fetched
+        // an image URI
+        if(appState.takingPicture || appState.imageUri) {
+            window.localStorage.setItem(APP_STORAGE_KEY, JSON.stringify(appState));
+        }
+    },
+    onResume: function(event) {
+        // Here we check for stored state and restore it if necessary. In your
+        // application, it's up to you to keep track of where any pending plugin
+        // results are coming from (i.e. what part of your code made the call)
+        // and what arguments you provided to the plugin if relevant
+        var storedState = window.localStorage.getItem(APP_STORAGE_KEY);
+
+        if(storedState) {
+            appState = JSON.parse(storedState);
+        }
+
+        // Check to see if we need to restore an image we took
+        if(!appState.takingPicture && appState.imageUri) {
+            document.getElementById("get-picture-result").src = appState.imageUri;
+        }
+        // Now we can check if there is a plugin result in the event object.
+        // This requires cordova-android 5.1.0+
+        else if(appState.takingPicture && event.pendingResult) {
+            // Figure out whether or not the plugin call was successful and call
+            // the relevant callback. For the camera plugin, "OK" means a
+            // successful result and all other statuses mean error
+            if(event.pendingResult.pluginStatus === "OK") {
+                // The camera plugin places the same result in the resume object
+                // as it passes to the success callback passed to getPicture(),
+                // thus we can pass it to the same callback. Other plugins may
+                // return something else. Consult the documentation for
+                // whatever plugin you are using to learn how to interpret the
+                // result field
+                cameraSuccessCallback(event.pendingResult.result);
+            } else {
+                cameraFailureCallback(event.pendingResult.result);
+            }
+        }
+    }
+}
+
+// Here are the callbacks we pass to getPicture()
+function cameraSuccessCallback(imageUri) {
+    appState.takingPicture = false;
+    appState.imageUri = imageUri;
+    document.getElementById("get-picture-result").src = imageUri;
+}
+
+function cameraFailureCallback(error) {
+    appState.takingPicture = false;
+    console.log(error);
+}
+
+app.initialize();
+```
+
+The corresponding html:
+
+```html
+<!DOCTYPE html>
+
+<html>
+    <head>
+        <meta http-equiv="Content-Security-Policy" content="default-src 'self' data: gap: https://ssl.gstatic.com 'unsafe-eval'; style-src 'self' 'unsafe-inline'; media-src *">
+        <meta name="format-detection" content="telephone=no">
+        <meta name="msapplication-tap-highlight" content="no">
+        <meta name="viewport" content="user-scalable=no, initial-scale=1, maximum-scale=1, minimum-scale=1, width=device-width">
+        <link rel="stylesheet" type="text/css" href="css/index.css">
+        <title>Cordova Android Lifecycle Example</title>
+    </head>
+    <body>
+        <div class="app">
+            <div>
+                <img id="get-picture-result" />
+            </div>
+            <Button id="take-picture-button">Take Picture</button>
+        </div>
+        <script type="text/javascript" src="cordova.js"></script>
+        <script type="text/javascript" src="js/index.js"></script>
+    </body>
+</html>
+```
+
+## Testing the Activity Lifecycle
+
+Android provides a developer setting for testing Activity destruction on low
+memory. Enable the "Don't keep activities" setting in the Developer Options menu
+on your device or emulator to simulate low memory scenarios. You should always
+do some amount of testing with this setting enabled to make sure that your
+application is properly maintaining state.

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/21c8e8f0/www/docs/en/6.x/guide/platforms/android/plugin.md
----------------------------------------------------------------------
diff --git a/www/docs/en/6.x/guide/platforms/android/plugin.md b/www/docs/en/6.x/guide/platforms/android/plugin.md
new file mode 100644
index 0000000..9cb25db
--- /dev/null
+++ b/www/docs/en/6.x/guide/platforms/android/plugin.md
@@ -0,0 +1,464 @@
+---
+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.
+
+title: Android Plugins
+---
+
+# Android Plugins
+
+This section provides details for how to implement native plugin code
+on the Android platform. Before reading this, see Application Plugins
+for an overview of the plugin's structure and its common JavaScript
+interface. This section continues to demonstrate the sample _echo_
+plugin that communicates from the Cordova webview to the native
+platform and back.  For another sample, see also the comments in
+[CordovaPlugin.java](https://github.com/apache/cordova-android/blob/master/framework/src/org/apache/cordova/CordovaPlugin.java).
+
+Android plugins are based on Cordova-Android, which consists of an
+Android WebView with hooks attached to it.  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,
+overriding one of its `execute` methods. As best practice, the plugin
+should also handle `[pause](../../../cordova/events/events.pause.html)` and `[resume](../../../cordova/events/events.resume.html)` events, along with any message
+passing between plugins.  Plugins with long-running requests,
+background activity such as media playback, listeners, or internal
+state should implement the `onReset()` method as well. It executes
+when the `WebView` navigates to a new page or refreshes, which reloads
+the JavaScript.
+
+## Plugin Class Mapping
+
+The plugin's JavaScript interface 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,
+effectively calling the `action` method on the `service` class, with
+additional arguments passed in the `args` array.
+
+Whether you distribute a plugin as Java file or as a _jar_ file of its
+own, the plugin must be specified in your Cordova-Android
+application's `res/xml/config.xml` file. See Application Plugins for
+more information on how to use the `plugin.xml` file to inject this
+`feature` element:
+
+        <feature name="<service_name>">
+            <param name="android-package" value="<full_name_including_namespace>" />
+        </feature>
+
+The service name matches the one used in the JavaScript `exec` call.
+The value is the Java class's fully qualified namespace identifier.
+Otherwise, the plugin may compile but still be unavailable to Cordova.
+
+## Plugin Initialization and Lifetime
+
+One instance of a plugin object is created for the life of each
+`WebView`. Plugins are not instantiated until they are first
+referenced by a call from JavaScript, unless `<param>` with an `onload`
+`name` attribute is set to `"true"` in `config.xml`. E.g.:
+
+    <feature name="Echo">
+        <param name="android-package" value="<full_name_including_namespace>" />
+        <param name="onload" value="true" />
+    </feature>
+
+Plugins should use the `initialize` method for their start-up logic.
+
+    @Override
+    public void initialize(CordovaInterface cordova, CordovaWebView webView) {
+        super.initialize(cordova, webView);
+        // your init code here
+    }
+
+## Writing an Android Java Plugin
+
+A JavaScript call fires off a plugin request to the native side, and
+the corresponding Java plugin is mapped properly in the `config.xml`
+file, but what does the final Android Java Plugin class look like?
+Whatever is dispatched to the plugin with JavaScript's `exec` function
+is 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.
+        }
+
+The JavaScript `exec` function's `action` parameter corresponds to a
+private class method to dispatch with optional parameters.
+
+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
+
+The plugin's JavaScript does _not_ run in the main thread of the
+`WebView` interface; instead, it runs on the `WebCore` thread, as
+does the `execute` method.  If you need to interact with the user
+interface, you should use the following variation:
+
+        @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;
+        }
+
+Use the following if you do not need to run on the main interface's
+thread, but do not want to block the `WebCore` thread either:
+
+        @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;
+        }
+
+## Adding Dependency Libraries
+
+If a plugin requires additional libraries to work, you can use
+one of the following approaches to add them via `config.xml`.
+
+Option A. Via _Gradle_ reference, for example:
+
+        <framework src="com.android.support:support-v4:+" />
+
+This is a recommended approach as it allows multiple plugins
+to refer to the same dependency library such as _gson_,
+_android-support-v4_, _google-play-services_, etc and
+_Gradle_ will resolve duplicate dependencies using its
+[Dependency Management logic](https://docs.gradle.org/current/userguide/dependency_management.html).
+
+Option B. As _JAR_ files placed to some plugin's folder and
+linked using `lib-file`, for example:
+
+        <lib-file src="src/android/libs/gcm.jar"/>
+
+We recommend using this approach only if you are sure that
+dependency jar is plugin specific and won't be used by
+other plugins. Otherwise, there will be platform build issue.
+
+## Echo Android Plugin Example
+
+To match the JavaScript interface's _echo_ feature described in
+Application Plugins, use the `plugin.xml` to inject a `feature`
+specification to the local platform's `config.xml` file:
+
+        <platform name="android">
+            <config-file target="config.xml" parent="/*">
+                <feature name="Echo">
+                    <param name="android-package" value="org.apache.cordova.plugin.Echo"/>
+                </feature>
+            </config-file>
+        </platform>
+
+Then add the following to the
+`src/org/apache/cordova/plugin/Echo.java` file:
+
+        package org.apache.cordova.plugin;
+
+        import org.apache.cordova.CordovaPlugin;
+        import org.apache.cordova.CallbackContext;
+
+        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.");
+                }
+            }
+        }
+
+The necessary imports at the top of the file extends the class from
+`CordovaPlugin`, whose `execute()` method it overrides to receive
+messages from `exec()`.  The `execute()` method first tests the value
+of `action`, for which in this case there is only one valid `echo`
+value.  Any other action returns `false` and results in an
+`INVALID_ACTION` error, which translates to an error callback invoked
+on the JavaScript side.
+
+Next, the method retrieves the echo string using the `args` object's
+`getString` method, specifying the first parameter passed to the
+method.  After the value is passed to a private `echo` method, it is
+parameter-checked to make sure it is not `null` or an empty string, in
+which case `callbackContext.error()` invokes JavaScript's error
+callback.  If the various checks pass, the `callbackContext.success()`
+passes the original `message` string back to JavaScript's success
+callback as a parameter.
+
+## Android Integration
+
+Android features an `Intent` system that allows processes to
+communicate with each other.  Plugins have access to a
+`CordovaInterface` object, which can access the Android `Activity`
+that runs 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` returns to the application.
+
+As of Cordova 2.0, Plugins can no longer directly access the
+`Context`, and the legacy `ctx` member is deprecated. All `ctx`
+methods exist on the `Context`, so both `getContext()` and
+`getActivity()` can return the required object.
+
+## Android Permissions
+
+Android permissions until recently have been handled at install-time instead
+of runtime.  These permissions are required to be declared on an application that uses
+the permissions, and these permissions need to be added to the Android Manifest.  This can be
+accomplished by using the config.xml to inject these permissions in the AndroidManifest.xml file.
+The example below uses the Contacts permission.
+
+        <config-file target="AndroidManifest.xml" parent="/*">
+            <uses-permission android:name="android.permission.READ_CONTACTS" />
+        </config-file>
+
+## Android Permissions (Cordova-Android 5.0.x and greater)
+
+Android 6.0 "Marshmallow" introduced a new permissions model where
+the user can turn on and off permissions as necessary.  This means that
+applications must handle these permission changes to be future-proof, which
+was the focus of the Cordova-Android 5.0 release.
+
+The permissions that need to be handled at runtime can be found in the Android Developer
+documentation [here](http://developer.android.com/guide/topics/security/permissions.html#perm-groups).
+
+As far as a plugin is concerned, the permission can be requested by calling the permission method, which signature is as follows:
+
+        cordova.requestPermission(CordovaPlugin plugin, int requestCode, String permission);
+
+To cut down on verbosity, it's standard practice to assign this to a local static variable:
+
+    public static final String READ = Manifest.permission.READ_CONTACTS;
+
+It is also standard practice to define the requestCode as follows:
+
+    public static final int SEARCH_REQ_CODE = 0;
+
+Then, in the exec method, the permission should be checked:
+
+            if(cordova.hasPermission(READ)) {
+                search(executeArgs);
+            }
+            else
+            {
+                getReadPermission(SEARCH_REQ_CODE);
+            }
+
+In this case, we just call requestPermission:
+
+    protected void getReadPermission(int requestCode)
+    {
+        cordova.requestPermission(this, requestCode, READ);
+    }
+
+This will call the activity and cause a prompt to appear asking for the permission.  Once the user has the permission, the result must be handled with the onRequestPermissionResult method, which
+every plugin should override.  An example of this can be found below:
+
+    public void onRequestPermissionResult(int requestCode, String[] permissions,
+                                             int[] grantResults) throws JSONException
+    {
+        for(int r:grantResults)
+        {
+            if(r == PackageManager.PERMISSION_DENIED)
+            {
+                this.callbackContext.sendPluginResult(new PluginResult(PluginResult.Status.ERROR, PERMISSION_DENIED_ERROR));
+                return;
+            }
+        }
+        switch(requestCode)
+        {
+            case SEARCH_REQ_CODE:
+                search(executeArgs);
+                break;
+            case SAVE_REQ_CODE:
+                save(executeArgs);
+                break;
+            case REMOVE_REQ_CODE:
+                remove(executeArgs);
+                break;
+        }
+    }
+
+
+The switch statement above would return from the prompt and depending on the requestCode that was passed in, it would call the method.  It should be noted that permission prompts may stack if the execution is not handled correctly, and that this should be avoided.
+
+In addition to asking for permission for a single permission, it is also possible to request permissions for an entire group by defining the permissions array, as what is done with the Geolocation plugin:
+
+    String [] permissions = { Manifest.permission.ACCESS_COARSE_LOCATION, Manifest.permission.ACCESS_FINE_LOCATION };
+
+Then when requesting the permission, all that needs to be done is the following:
+
+    cordova.requestPermissions(this, 0, permissions);
+
+This requests the permissions specified in the array.  It's a good idea to provide a publicly accessible permissions array since this can be used by plugins that use your plugin as a
+dependency, although this is not required.
+
+## Debugging Android Plugins
+
+Android debugging can be done with either Eclipse or Android Studio, although Android
+studio is recommended.  Since Cordova-Android is currently used as a library project,
+and plugins are supported as source code, it is possible to debug the Java code inside
+a Cordova application just like a native Android application.
+
+## Launching Other Activities
+
+There are special considerations to be made if your plugin launches an Activity
+that pushes the Cordova Activity to the background. The Android OS will destroy
+Activities in the background if the device is running low on memory. In that
+case, the CordovaPlugin instance will be destroyed as well. If your plugin is
+waiting on a result from the Activity it launched, a new instance of your plugin
+will be created when the Cordova Activity is brought back to the foreground and
+the result is obtained. However, state for the plugin will not be automatically
+saved or restored and the CallbackContext for the plugin will be lost. There are
+two methods that your CordovaPlugin may implement to handle this situation:
+
+```java
+/**
+ * Called when the Activity is being destroyed (e.g. if a plugin calls out to an
+ * external Activity and the OS kills the CordovaActivity in the background).
+ * The plugin should save its state in this method only if it is awaiting the
+ * result of an external Activity and needs to preserve some information so as
+ * to handle that result; onRestoreStateForActivityResult() will only be called
+ * if the plugin is the recipient of an Activity result
+ *
+ * @return  Bundle containing the state of the plugin or null if state does not
+ *          need to be saved
+ */
+public Bundle onSaveInstanceState() {}
+
+/**
+ * Called when a plugin is the recipient of an Activity result after the
+ * CordovaActivity has been destroyed. The Bundle will be the same as the one
+ * the plugin returned in onSaveInstanceState()
+ *
+ * @param state             Bundle containing the state of the plugin
+ * @param callbackContext   Replacement Context to return the plugin result to
+ */
+public void onRestoreStateForActivityResult(Bundle state, CallbackContext callbackContext) {}
+```
+
+It is important to note that the above methods should only be used if your
+plugin launches an Activity for a result and should only restore the state
+necessary to handle that Activity result. The state of the plugin will *NOT* be
+restored except in the case where an Activity result is obtained that your
+plugin requested using the CordovaInterface's `startActivityForResult()` method
+and the Cordova Activity was destroyed by the OS while in the background.
+
+As part of `onRestoreStateForActivityResult()`, your plugin will be passed a
+replacement CallbackContext. It is important to realize that this
+CallbackContext *IS NOT* the same one that was destroyed with the Activity. The
+original callback is lost, and will not be fired in the javascript application.
+Instead, this replacement CallbackContext will return the result as part of the
+`resume` event that is fired when the application resumes. The payload of the
+`resume` event follows this structure:
+
+```
+{
+    action: "resume",
+    pendingResult: {
+        pluginServiceName: string,
+        pluginStatus: string,
+        result: any
+    }
+}
+```
+
+* `pluginServiceName` will match the `name` attribute from your plugin.xml
+* `pluginStatus` will be a String describing the status of the PluginResult
+   passed to the CallbackContext. See PluginResult.java for the String values
+   that correspond to plugin statuses
+* `result` will be whatever result the plugin passes to the CallbackContext
+   (e.g. a String, a number, a JSON object, etc.)
+
+This resume payload will be passed to any callbacks that the javascript
+application has registered for the `resume` event. This means that the result is
+going *directly* to the Cordova application; your plugin will not have a chance
+to process the result with javascript before the application receives it.
+Consequently, you should strive to make the result returned by the native code
+as complete as possible and not rely on any javascript callbacks when launching
+activities.
+
+Be sure to communicate how the Cordova application should interpret the result
+they receive in the `resume` event. It is up to the Cordova application to
+maintain their own state and remember what requests they made and what arguments
+they provided if necessary. However, you should still clearly communicate the
+meaning of `pluginStatus` values and what sort of data is being returned in the
+`result` field as part of your plugin's API.
+
+The complete sequence of events for launching an Activity is as follows
+
+1. The Cordova application makes a call to your plugin
+2. Your plugin launches an Activity for a result
+3. The Android OS destroys the Cordova Activity and your plugin instance
+    * *`onSaveInstanceState()` is called*
+4. The user interacts with your Activity and the Activity finishes
+5. The Cordova Activity is recreated and the Activity result is received
+    * *`onRestoreStateForActivityResult()` is called*
+6. `onActivityResult()` is called and your plugin passes a result to the new
+    CallbackContext
+7. The `resume` event is fired and received by the Cordova application
+
+Android provides a developer setting for debugging Activity destruction on low
+memory. Enable the "Don't keep activities" setting in the Developer Options menu
+on your device or emulator to simulate low memory scenarios. If your plugin
+launches external activities, you should always do some testing with this
+setting enabled to ensure that you are properly handling low memory scenarios.

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/21c8e8f0/www/docs/en/6.x/guide/platforms/android/tools.md
----------------------------------------------------------------------
diff --git a/www/docs/en/6.x/guide/platforms/android/tools.md b/www/docs/en/6.x/guide/platforms/android/tools.md
new file mode 100644
index 0000000..119a863
--- /dev/null
+++ b/www/docs/en/6.x/guide/platforms/android/tools.md
@@ -0,0 +1,224 @@
+---
+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.
+
+title: Android Shell Tool Guide
+---
+
+# Android Shell Tool Guide
+
+This guide shows how to use Cordova's set of platform-centered shell
+tools to develop Android apps. This development path, discussed in the
+[Overview](../../overview/index.html), may offer you a greater range of development options than
+the cross-platform CLI tool described in [The Command-Line Interface](../../cli/index.html).
+For example, you need to use shell tools when deploying a custom
+Cordova WebView alongside native components.  Before using either
+development path, you must first configure the Android SDK environment
+as described in the [Android Platform Guide](index.html).
+
+To enable shell tools for Android, download Cordova from
+[cordova.apache.org](http://cordova.apache.org). The download contains
+separate archives for each platform. Expand each you wish to target,
+`android` in this case. The relevant tools are typically available in
+the top-level `bin` directory, otherwise consult the __README__ file
+for more detailed directions.
+
+These tools allow you to create, build, and run Android apps.  For
+information on the additional command-line interface that enables
+plugin features across all platforms, see Using Plugman to Manage
+Plugins. See Application Plugins for details on how to develop
+plugins.
+
+## 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/Linux and Windows:
+
+        $ /path/to/cordova-android/bin/create /path/to/project com.example.project_name ProjectName
+
+        C:\>\path\to\cordova-android\bin\create.bat \path\to\project com.example.project_name ProjectName
+
+## Build
+
+This cleans then builds a project.
+
+Debug, on Mac/Linux or Windows:
+
+        $ /path/to/project/cordova/build --debug
+
+        C:\>\path\to\project\cordova\build.bat --debug
+
+Release, on Mac/Linux 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.
+
+## Signing the App
+
+You can review Android app signing requirements here: http://developer.android.com/tools/publishing/app-signing.html
+
+To sign an app, you need the following parameters:
+
+  * Keystore (`--keystore`): Path to a binary file which can hold a set of keys.
+  
+  * Keystore password (`--storePassword`): Password to the keystore
+  
+  * Alias (`--alias`): The id specifying the private key used for singing.
+  
+  * Password (`--password`): Password for the private key specified.
+  
+  * Type of the keystore (`--keystoreType`): pkcs12, jks (Default: auto-detect based on file extension)
+
+These parameters can be specified using the command line arguments above to `build` or `run` scripts.
+
+Alternatively, you could specify them in a build configuration file (build.json) using (`--buildConfig`) argument. Here's a sample of a build configuration file:
+
+    {
+         "android": {
+             "debug": {
+                 "keystore": "..\android.keystore",
+                 "storePassword": "android",
+                 "alias": "mykey1",
+                 "password" : "password",
+                 "keystoreType": ""
+             },
+             "release": {
+                 "keystore": "..\android.keystore",
+                 "storePassword": "",
+                 "alias": "mykey2",
+                 "password" : "password",
+                 "keystoreType": ""
+             }
+         }
+     }
+
+For release signing, passwords can be excluded and the build system will issue a prompt asking for the password.
+
+There is also support to mix and match command line arguments and parameters in build.json file. Values from the command line arguments will get precedence. This can be useful for specifying passwords on the command line. 
+
+## 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
+
+## Building with Gradle
+
+As of cordova-android@4.0.0, project build using [Gradle](http://www.gradle.org/).
+For instructions on building with ANT, refer to older versions of documentation.
+
+### Gradle Properties
+
+These [properties](http://www.gradle.org/docs/current/userguide/tutorial_this_and_that.html)
+can be set to customize the build:
+
+  * **cdvBuildMultipleApks** (default: false)
+
+  If this is set, then multiple APK files will be generated: One per native
+  platform supported by library projects (x86, ARM, etc). This can be important
+  if your project uses large native libraries, which can drastically increase
+  the size of the generated APK.
+
+  If not set, then a single APK will be generated which can be used on all devices.
+
+  * **cdvVersionCode**
+
+  Overrides the versionCode set in `AndroidManifest.xml`
+
+  * **cdvReleaseSigningPropertiesFile** (default: release-signing.properties)
+
+  Path to a .properties file that contains signing information for release builds.
+  The file should look like:
+  ```
+  storeFile=relative/path/to/keystore.p12
+  storePassword=SECRET1
+  storeType=pkcs12
+  keyAlias=DebugSigningKey
+  keyPassword=SECRET2
+  ```
+
+  `storePassword` and `keyPassword` are optional, and will be prompted for if omitted.
+
+  * **cdvDebugSigningPropertiesFile** (default: debug-signing.properties)
+
+  Same as cdvReleaseSigningPropertiesFile, but for debug builds. Useful when you need
+  to share a signing key with other developers.
+
+  * **cdvMinSdkVersion**
+
+  Overrides the value of `minSdkVersion` set in `AndroidManifest.xml`. Useful when
+  creating multiple APKs based on SDK version.
+
+  * **cdvBuildToolsVersion**
+
+  Override the automatically detected `android.buildToolsVersion` value.
+
+  * **cdvCompileSdkVersion**
+
+  Override the automatically detected `android.compileSdkVersion` value.
+
+
+### Extending build.gradle
+
+If you need to customize `build.gradle`, rather than edit directly, you should create
+a sibling file named `build-extras.gradle`. This file will be included by the main
+`build.gradle` when present. Here's an example:
+
+    # Example build-extras.gradle
+    # This file is included at the beginning of `build.gradle`
+    ext.cdvDebugSigningPropertiesFile = '../../android-debug-keys.properties'
+    # When set, this function allows code to run at the end of `build.gradle`
+    ext.postBuildExtras = {
+        android.buildTypes.debug.applicationIdSuffix = '.debug'
+    }
+
+Note that plugins can also include `build-extras.gradle` files via:
+
+    <framework src="some.gradle" custom="true" type="gradleReference" />
+
+### Example Build
+
+    export ORG_GRADLE_PROJECT_cdvMinSdkVersion=14
+    cordova build android -- --gradleArg=-PcdvBuildMultipleApks=true
+

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/21c8e8f0/www/docs/en/6.x/guide/platforms/android/upgrade.md
----------------------------------------------------------------------
diff --git a/www/docs/en/6.x/guide/platforms/android/upgrade.md b/www/docs/en/6.x/guide/platforms/android/upgrade.md
new file mode 100644
index 0000000..33b2bee
--- /dev/null
+++ b/www/docs/en/6.x/guide/platforms/android/upgrade.md
@@ -0,0 +1,521 @@
+---
+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.
+
+title: Upgrading Android
+---
+
+# 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 Command-Line Interface](../../cli/index.html) for information how to update the
+version of the CLI.
+
+## Upgrading to 4.0.0
+
+There are specific upgrade steps required to take advantage of the significant
+changes in 4.0.0.  First, the common upgrade steps are needed as below.
+
+For non-CLI projects, run:
+
+        bin/update path/to/project
+
+For CLI projects:
+
+1. Update the `cordova` CLI version. See [The Command-Line Interface](../../cli/index.html).
+
+2. Run `cordova platform update android` in your existing projects.
+
+### Upgrading the Whitelist
+All whitelist functionality is now implemented via plugin.  Without a plugin,
+your app is no longer protected by a whitelist after upgrading to 4.0.0.  Cordova
+has two whitelist plugins, which provide different levels of protection.
+
+1. The `cordova-plugin-whitelist` plugin *(RECOMMENDED)*
+  * This plugin is highly recommended, as it is more secure and configurable
+    than the whitelist in previous versions
+  * See [cordova-plugin-whitelist](https://github.com/apache/cordova-plugin-whitelist)
+    for details on the configuration changes required
+  * Run: `cordova plugin add cordova-plugin-crosswalk-webview`
+
+2. The `cordova-plugin-legacy-whitelist` plugin
+  * This plugin provides the same whitelist behaviour as previous versions. See
+    [cordova-plugin-legacy-whitelist](https://github.com/apache/cordova-plugin-legacy-whitelist)
+  * No configuration changes are required, but it provides less protection than
+    the recommended plugin
+  * Run: `cordova plugin add cordova-plugin-legacy-whitelist`
+
+### Using the Crosswalk WebView
+By default, your app will continue to use the system WebView provided by the
+device.  If you wish to use the Crosswalk WebView instead, simply add the
+Crosswalk plugin:
+
+    cordova plugin add cordova-plugin-crosswalk-webview
+
+Upon adding the plugin, your app will get the Crosswalk WebView installed and
+configured correctly.
+
+### Upgrading to the Splashscreen Plugin
+If your app makes use of a splash screen, that functionality has been moved to
+a plugin.  The configuration options for splash screens are unchanged.  The only
+upgrade step required is to add the plugin:
+
+    cordova plugin add cordova-plugin-splashscreen
+
+## Upgrading to 3.7.1 from 3.6.0
+
+For non-CLI projects, run:
+
+        bin/update path/to/project
+        
+For CLI projects:
+
+1. Update the `cordova` CLI version. See [The Command-Line Interface](../../cli/index.html).
+
+2. Run `cordova platform update android` in your existing projects.
+
+
+## Upgrading to 3.3.0 from 3.2.0
+
+Follow the same instructions as for `3.2.0`.
+
+Starting with 3.3.0, the Cordova runtime is now compiled as an Android Library
+instead of a Jar. This should have no effect for command-line usage, but IDE
+users will need to import the newly added `MyProject-CordovaLib` project into
+their workspace.
+
+## Upgrading to 3.2.0 from 3.1.0
+
+For projects that were created with the cordova CLI: 
+
+1. Update the `cordova` CLI version. See [The Command-Line Interface](../../cli/index.html).
+
+2. Run `cordova platform update android`
+        
+For projects not created with the cordova CLI, run:
+
+        bin/update <project_path>
+
+**WARNING:**  On Android 4.4 - Android 4.4.3, creating a file input element with type="file" will not open the file picker dialog.
+This is a regression with Chromium on Android and the problem can be reproduced in the standalone Chrome browser on Android (see http://code.google.com/p/android/issues/detail?id=62220)  The suggested workaround is to use the FileTransfer and File plugins for Android 4.4. You can listen for an onClick event from the input type="file" and then pop up a file picker UI. In order to tie the form data with the upload, you can use JavaScript to attach form values to the multi-part POST request that FileTransfer makes.
+
+
+## Upgrading to 3.1.0 from 3.0.0
+
+For projects that were created with the cordova CLI: 
+
+1. Update the `cordova` CLI version. See [The Command-Line Interface](../../cli/index.html).
+
+2. Run `cordova platform update android`
+        
+For projects not created with the cordova CLI, run:
+
+        bin/update <project_path>
+        
+## 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 Command-Line Interface](../../cli/index.html).
+
+2. Add your platforms the cordova project, for example: `cordova
+   platform add android`.
+
+3. Copy the contents of your project's `www` directory to the `www` directory
+   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 the `www` directory to the new project.
+
+3. Copy any native Android assets from the `res` directory 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.
+
+6. Update any references to the `org.apache.cordova.api` package to be `org.apache.cordova`.
+
+   __NOTE__: all core APIs have been removed and must be installed as plugins. Please see the [Using Plugman to Manage Plugins](../../../plugin_ref/plugman.html) 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 use Eclipse, please refresh your Eclipse project and do a clean.
+
+<!-- SS Eclipse -->
+
+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 use 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 use 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 use 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 use 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 use 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 use 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 use 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 use 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`.
+
+In the 2.0.0 release, the `config.xml` file combines and replaces
+`cordova.xml` and `plugins.xml`.  The old files are deprecated, and
+while they still work in 2.0.0, will stop 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 use 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`.
+
+Due to the introduction of the `CordovaWebView` in the 1.9.0 release,
+third-party plugins may not work.  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 use 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 use 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 use 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 use 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 use 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 use 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 use 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 use 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 use 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 use 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 use 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 use 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/21c8e8f0/www/docs/en/6.x/guide/platforms/android/webview.md
----------------------------------------------------------------------
diff --git a/www/docs/en/6.x/guide/platforms/android/webview.md b/www/docs/en/6.x/guide/platforms/android/webview.md
new file mode 100644
index 0000000..24bcf12
--- /dev/null
+++ b/www/docs/en/6.x/guide/platforms/android/webview.md
@@ -0,0 +1,134 @@
+---
+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.
+
+title: Android WebViews
+---
+
+# Android WebViews
+
+This guide shows how to embed a Cordova-enabled WebView component
+within a larger Android application. For details on how these
+components can communicate with each other, see Application Plugins.
+
+If you're unfamiliar with Android, you should first familiarize
+yourself with the [Android Platform Guide](index.html) and have the latest Android
+SDK installed before you attempt the more unusual development option
+of embedding a WebView.  Starting with Cordova 1.9, the Android
+platform relies on a `CordovaWebView` component, which builds on a
+legacy `CordovaActivity` component that pre-dates the 1.9 release.
+
+1. To follow these instructions, make sure you have the latest Cordova
+   distribution. Download it from
+   [cordova.apache.org](http://cordova.apache.org) and unzip its
+   Android package.
+
+1. Navigate to the Android package's `/framework` directory and run
+   `ant jar`. It creates the Cordova `.jar` file, formed as
+   `/framework/cordova-x.x.x.jar`.
+
+1. Copy the `.jar` file into the Android project's `/libs` directory.
+
+1. Add the following to the application's `/res/xml/main.xml` file,
+   with the `layout_height`, `layout_width` and `id` modified to suit
+   the application:
+
+        <org.apache.cordova.CordovaWebView
+            android:id="@+id/tutorialView"
+            android:layout_width="match_parent"
+            android:layout_height="match_parent" />
+
+1. Modify the activity so that it implements the `CordovaInterface`.
+   It should implement the included methods.  You may wish to copy
+   them from `/framework/src/org/apache/cordova/CordovaActivity.java`,
+   or else implement them on your own.  The following code fragment
+   shows a basic application that relies on 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());
+            }
+
+1. If the application needs to use the camera, implement the
+   following:
+
+        @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);
+            }
+        }
+
+1. Finally, remember to add the thread pool, otherwise plugins
+   have no threads on which to run:
+
+        @Override
+        public ExecutorService getThreadPool() {
+            return threadPool;
+        }
+
+1. Copy the application's HTML and JavaScript files to the Android
+   project's `/assets/www` directory.
+
+1. Copy the `config.xml` file from `/framework/res/xml` to the
+   project's `/res/xml` directory.


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org


Mime
View raw message