Return-Path: X-Original-To: apmail-cordova-commits-archive@www.apache.org Delivered-To: apmail-cordova-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id BDEAE1078C for ; Thu, 1 Aug 2013 22:18:27 +0000 (UTC) Received: (qmail 32164 invoked by uid 500); 1 Aug 2013 22:18:27 -0000 Delivered-To: apmail-cordova-commits-archive@cordova.apache.org Received: (qmail 32145 invoked by uid 500); 1 Aug 2013 22:18:27 -0000 Mailing-List: contact commits-help@cordova.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@cordova.apache.org Delivered-To: mailing list commits@cordova.apache.org Received: (qmail 32138 invoked by uid 99); 1 Aug 2013 22:18:27 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 01 Aug 2013 22:18:27 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 01 Aug 2013 22:18:16 +0000 Received: from eris.apache.org (localhost [127.0.0.1]) by eris.apache.org (Postfix) with ESMTP id 027562388ADA; Thu, 1 Aug 2013 22:17:54 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Subject: svn commit: r1509456 [5/21] - in /cordova/site/public/docs: en/1.5.0/ en/1.5.0rc1/ en/1.6.0/ en/1.6.0rc1/ en/1.6.1/ en/1.7.0/ en/1.7.0rc1/ en/1.8.0/ en/1.8.0rc1/ en/1.8.1/ en/1.9.0/ en/1.9.0rc1/ en/2.0.0/ en/2.0.0rc1/ en/2.1.0/ en/2.1.0rc1/ en/2.1.0rc2... Date: Thu, 01 Aug 2013 22:17:47 -0000 To: commits@cordova.apache.org From: mwbrooks@apache.org X-Mailer: svnmailer-1.0.9 Message-Id: <20130801221754.027562388ADA@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Modified: cordova/site/public/docs/en/3.0.0/guide_cli_index.md.html URL: http://svn.apache.org/viewvc/cordova/site/public/docs/en/3.0.0/guide_cli_index.md.html?rev=1509456&r1=1509455&r2=1509456&view=diff ============================================================================== --- cordova/site/public/docs/en/3.0.0/guide_cli_index.md.html (original) +++ cordova/site/public/docs/en/3.0.0/guide_cli_index.md.html Thu Aug 1 22:17:43 2013 @@ -86,9 +86,11 @@ - + - + + Modified: cordova/site/public/docs/en/3.0.0/guide_hybrid_plugins_index.md.html URL: http://svn.apache.org/viewvc/cordova/site/public/docs/en/3.0.0/guide_hybrid_plugins_index.md.html?rev=1509456&r1=1509455&r2=1509456&view=diff ============================================================================== --- cordova/site/public/docs/en/3.0.0/guide_hybrid_plugins_index.md.html (original) +++ cordova/site/public/docs/en/3.0.0/guide_hybrid_plugins_index.md.html Thu Aug 1 22:17:43 2013 @@ -94,7 +94,6 @@
  • Overview
  • The Command-line Interface
  • Platform Guides
  • -
  • Guides
  • Configuration Reference
  • Embedding WebViews
  • Plugin Development Guide
  • @@ -154,52 +153,47 @@ front-facing and arguably most important

    You can structure your plugin's JavaScript however you like. The one thing you must use to communicate between the Cordova JavaScript - and native environments is the cordova.exec function. Here is an example:

    +and native environments is the cordova.exec function. Here is an example:

    -
    cordova.exec(function(winParam) {}, function(error) {}, "service",
    -             "action", ["firstArgument", "secondArgument", 42,
    -             false]);
    +
        cordova.exec(function(winParam) {}, function(error) {}, "service",
    +                 "action", ["firstArgument", "secondArgument", 42,
    +                 false]);
     

    The parameters are detailed below:

    -
      -
    1. -function(winParam) {} - Success function callback. Assuming your +
        +
      • function(winParam) {}: Success function callback. Assuming your exec call completes successfully, this function is invoked -(optionally with any parameters you pass back to it).

      • -
      • -function(error) {} - Error function callback. If the operation does -not complete successfully, this function is invoked (optionally -with an error parameter).
      • -
      • -"service" - The service name to call into on the native side. This +(optionally with any parameters you pass back to it).

      • +
      • function(error) {}: Error function callback. If the operation does +not complete successfully, this function is invoked (optionally with +an error parameter).

      • +
      • "service": The service name to call into on the native side. This is mapped to a native class, about which more information is -available in the native guides listed below.

      • -
      • -"action" - The action name to call into. This is picked up by the +available in the native guides listed below.

      • +
      • "action": The action name to call into. This is picked up by the native class receiving the exec call, and, depending on the -platform, essentially maps to a class's method. -The native guides listed below provide details.

      • -
      • -[/* arguments */] - Arguments to pass into the native environment.
      • -
    +platform, essentially maps to a class's method. The native guides +listed below provide details.

    +
  • [/* arguments */]: Arguments to pass into the native environment.

  • +

    Echo Plugin JavaScript Example

    -
    window.echo = function(str, callback) {
    -    cordova.exec(callback, function(err) {
    -        callback('Nothing to echo.');
    -    }, "Echo", "echo", [str]);
    -};
    +
        window.echo = function(str, callback) {
    +        cordova.exec(callback, function(err) {
    +            callback('Nothing to echo.');
    +        }, "Echo", "echo", [str]);
    +    };
     

    Let's dive into this. The plugin attaches itself to window, specifically to the echo function. Plugin users would then use it as follows:

    -
    window.echo("echome", function(echoValue) {
    -    alert(echoValue == "echome"); // should alert true.
    -});
    +
        window.echo("echome", function(echoValue) {
    +        alert(echoValue == "echome"); // should alert true.
    +    });
     

    First, let's take a look at the last three arguments to the exec @@ -221,7 +215,7 @@ string.

    installation of the plugin for Android, iOS, BlackBerry 10 and Windows Phone platforms. By structuring your plugin in a particular way and adding a plugin.xml manifest file, you can enable users to install -your plugin via the command line tooling.

    +your plugin via the command-line tooling.

    • Plugin Specification
    • Modified: cordova/site/public/docs/en/3.0.0/guide_hybrid_webviews_index.md.html URL: http://svn.apache.org/viewvc/cordova/site/public/docs/en/3.0.0/guide_hybrid_webviews_index.md.html?rev=1509456&r1=1509455&r2=1509456&view=diff ============================================================================== --- cordova/site/public/docs/en/3.0.0/guide_hybrid_webviews_index.md.html (original) +++ cordova/site/public/docs/en/3.0.0/guide_hybrid_webviews_index.md.html Thu Aug 1 22:17:43 2013 @@ -91,7 +91,6 @@
    • Overview
    • The Command-line Interface
    • Platform Guides
    • -
    • Guides
    • Configuration Reference
    • Embedding WebViews
    • Plugin Development Guide
    • Modified: cordova/site/public/docs/en/3.0.0/guide_overview_index.md.html URL: http://svn.apache.org/viewvc/cordova/site/public/docs/en/3.0.0/guide_overview_index.md.html?rev=1509456&r1=1509455&r2=1509456&view=diff ============================================================================== --- cordova/site/public/docs/en/3.0.0/guide_overview_index.md.html (original) +++ cordova/site/public/docs/en/3.0.0/guide_overview_index.md.html Thu Aug 1 22:17:43 2013 @@ -94,7 +94,6 @@
    • Overview
    • The Command-line Interface
    • Platform Guides
    • -
    • Guides
    • Configuration Reference
    • Embedding WebViews
    • Plugin Development Guide
    • @@ -144,7 +143,7 @@ platform's language and tool set.

    • a mobile developer interested in mixing native application components with a WebView (browser window) that can access -device-level APIs, or if you want to develop a plug-in interface +device-level APIs, or if you want to develop a plugin interface between native and WebView components.

    @@ -166,14 +165,14 @@ which you distribute to app stores. For various device features the way native apps do, it must also reference a cordova.js file, which provides API bindings.

    The Cordova-enabled WebView may provide the application with its entire user interface. It can also be a component within a larger, hybrid application that mixes the WebView with native application -components. Cordova provides a plug-in interface for these +components. Cordova provides a plugin interface for these components to communicate with each other.

    @@ -246,57 +245,41 @@ available for each mobile platform:

    Windows
    Phone 7 Windows
    Phone 8 Windows
    8 + Tizen -cordova
    CLI
    +cordova
    CLI
    Mac, Windows, Linux - Mac, Windows + Mac, Windows Mac, Windows Mac Windows Windows - - - -PhoneGap
    Build
    - - - - - - - - - -SDK platform support - - - - - - - + + -Embedded
    WebView
    - +Embedded
    WebView
    + (see details) - + (see details) + -Plug-in
    Interface
    - - - - - - +Plug-in
    Interface
    + (see details) + (see details) + (see details) + (see details) + (see details) + + @@ -311,6 +294,7 @@ available for each mobile platform:

    + Camera @@ -321,6 +305,7 @@ available for each mobile platform:

    + Capture @@ -331,16 +316,18 @@ available for each mobile platform:

    + Compass - + (3GS+) + Connection @@ -351,6 +338,7 @@ available for each mobile platform:

    + Contacts @@ -361,6 +349,7 @@ available for each mobile platform:

    + Device @@ -371,6 +360,7 @@ available for each mobile platform:

    + Events @@ -381,6 +371,7 @@ available for each mobile platform:

    + File @@ -388,9 +379,10 @@ available for each mobile platform:

    - - + (no FileTransfer) + (no FileTransfer) + Geolocation @@ -401,16 +393,18 @@ available for each mobile platform:

    + Globalization - + + InAppBrowser @@ -420,17 +414,19 @@ available for each mobile platform:

    - + + Media - + + Notification @@ -441,16 +437,18 @@ available for each mobile platform:

    + Splashscreen - + - - + + + Storage @@ -458,9 +456,12 @@ available for each mobile platform:

    - - + +localStorage only + +localStorage only + Modified: cordova/site/public/docs/en/3.0.0/guide_platforms_android_config.md.html URL: http://svn.apache.org/viewvc/cordova/site/public/docs/en/3.0.0/guide_platforms_android_config.md.html?rev=1509456&r1=1509455&r2=1509456&view=diff ============================================================================== --- cordova/site/public/docs/en/3.0.0/guide_platforms_android_config.md.html (original) +++ cordova/site/public/docs/en/3.0.0/guide_platforms_android_config.md.html Thu Aug 1 22:17:43 2013 @@ -93,7 +93,6 @@
  • Overview
  • The Command-line Interface
  • Platform Guides
  • -
  • Guides
  • Configuration Reference
  • Embedding WebViews
  • Plugin Development Guide
  • @@ -126,41 +125,46 @@

    Android Configuration

    -

    The config.xml settings file controls various settings of Cordova. This is application wide, and not set per CordovaWebView Instance.

    +

    The config.xml file controls various Cordova settings. These apply +across the application, and per CordovaWebView instance.

    <preference>

    -

    Various other preferences (as <preference> tags) default on not breaking existing apps. The available preferences are:

    +

    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. -
    3. -loadingDialog - Display a native loading dialog when loading the app. The value's format is Title, Message -
    4. -
    5. -loadingPageDialog - Display a native loading dialog when loading sub-pages. The value's format is Title, Message -
    6. -
    7. -errorUrl - Set the error page for your application. Should be located in your Android project in file://android_asset/www/
    8. -
    9. -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)
    10. -
    11. -loadUrlTimeoutValue - How much time Cordova should wait before throwing a timeout error on the application.
    12. -
    13. -keepRunning (boolean, defaults to true) - Determines whether Cordova will keep running in the background or not
    14. -
    15. -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.
    16. -
    17. -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.
    18. -
    +
      +
    • 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)

    • +
    • loadingDialog: Display a native loading dialog when loading the +app. The value's format is Title, Message

    • +
    • loadingPageDialog: Display a native loading dialog when loading +sub-pages. The value's format is Title, Message

    • +
    • errorUrl: Set the error page for your application. Should be +located in your Android project in file://android_asset/www/

    • +
    • 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)

    • +
    • loadUrlTimeoutValue: How much time Cordova should wait before +throwing a timeout error on the application.

    • +
    • keepRunning (boolean, defaults to true): Determines whether +Cordova stays running in the background.

    • +
    • 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.

    • +
    • disallowOverscroll (boolean, defaults to false): set to true to +disable the glow when a user scrolls beyond the edge of the webview.

    • +

    <plugin>

    -

    Android supports using <feature> as analogues to <plugin> elements.

    +

    Android supports using <feature> as analogues to <plugin> elements.

    Modified: cordova/site/public/docs/en/3.0.0/guide_platforms_android_index.md.html URL: http://svn.apache.org/viewvc/cordova/site/public/docs/en/3.0.0/guide_platforms_android_index.md.html?rev=1509456&r1=1509455&r2=1509456&view=diff ============================================================================== --- cordova/site/public/docs/en/3.0.0/guide_platforms_android_index.md.html (original) +++ cordova/site/public/docs/en/3.0.0/guide_platforms_android_index.md.html Thu Aug 1 22:17:43 2013 @@ -97,7 +97,6 @@
  • Overview
  • The Command-line Interface
  • Platform Guides
  • -
  • Guides
  • Configuration Reference
  • Embedding WebViews
  • Plugin Development Guide
  • @@ -142,7 +141,7 @@ detailed platform-specific information:<
  • Android Command-line Tools
  • The command-line tools above refer to versions prior to Cordova 3.0. -See The Cordova Command-line Interface for information about the +See The Command-line Interface for information about the current interface.

    @@ -232,23 +231,22 @@ Cordova - -
  • Navigate to hello, or whichever directory you created for the project, then to the platforms/android subdirectory.
  • -
  • Press Finish.
  • +
  • Launch the Eclipse application.

  • +
  • Select the New Project menu item.

  • +
  • Choose Android Project from Existing Code from the resulting dialog box, and press Next: +

  • +
  • Navigate to hello, or whichever directory you created for the project, then to the platforms/android subdirectory.

  • +
  • Press Finish.

  • Once the Eclipse window opens, a red X may appear to indicate unresolved problems. If so, follow these additional steps:

      -
    • Right-click on the project folder.
    • -
    • In the resulting Properties dialog, select Android from the navigation pane.
    • -
    • For the project build target, select the highest Android API level you have installed.
    • -
    • Click OK.
    • -
    • Select Clean from the Project menu. This should correct all the errors in the project.
    • +
    • Right-click on the project directory.

    • +
    • In the resulting Properties dialog, select Android from the navigation pane.

    • +
    • For the project build target, select the highest Android API level you have installed.

    • +
    • Click OK.

    • +
    • Select Clean from the Project menu. This should correct all the errors in the project.

    Deploy to Emulator @@ -306,14 +304,14 @@ specify an AVD if none are already open.

    For a faster experience, use an Intel-based emulator image:

      -
    • Install one or more Intel x86 Atom System Images as well as the +
    • Install one or more Intel x86 Atom System Images as well as the Intel Hardware Accelerated Execution Manager, available under -Extras.

    • -
    • Run the Intel installer, which is available within your Android SDK -at extras/intel/Hardware_Accelerated_Execution_Manager.
    • -
    • Create a new AVD with the target set to an Intel image.
    • -
    • When starting the emulator, ensure there are no error messages -indicating a failure to load HAX modules.
    • +Extras.

      +
    • Run the Intel installer, which is available within your Android SDK +at extras/intel/Hardware_Accelerated_Execution_Manager.

    • +
    • Create a new AVD with the target set to an Intel image.

    • +
    • When starting the emulator, ensure there are no error messages +indicating a failure to load HAX modules.

    Deploy to Device Modified: cordova/site/public/docs/en/3.0.0/guide_platforms_android_plugin.md.html URL: http://svn.apache.org/viewvc/cordova/site/public/docs/en/3.0.0/guide_platforms_android_plugin.md.html?rev=1509456&r1=1509455&r2=1509456&view=diff ============================================================================== --- cordova/site/public/docs/en/3.0.0/guide_platforms_android_plugin.md.html (original) +++ cordova/site/public/docs/en/3.0.0/guide_platforms_android_plugin.md.html Thu Aug 1 22:17:43 2013 @@ -96,7 +96,6 @@
  • Overview
  • The Command-line Interface
  • Platform Guides
  • -
  • Guides
  • Configuration Reference
  • Embedding WebViews
  • Plugin Development Guide
  • @@ -129,14 +128,19 @@

    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.

    +

    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 playback, listeners, or internal state should implement the +onReset() method as well. It executeswhen the WebView navigates to +a new page or refreshes, which reloads the JavaScript.

    Plugin Class Mapping @@ -151,9 +155,13 @@ Plugins with long-running requests, back 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>"/>
    +

    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/ directory.

    + +
    <feature name="<service_name>">
    +    <param name="android-package" value="<full_name_including_namespace>" />
    +</feature>
     

    The service name should match the one used in the JavaScript exec @@ -237,7 +245,9 @@ public boolean execute(String action, JS

    Add the following to our config.xml file:

    -
    <plugin name="Echo" value="org.apache.cordova.plugin.Echo" />
    +
    <feature name="Echo">
    +    <param name="android-package" value="org.apache.cordova.plugin.Echo" />
    +</feature>
     

    Then add the following file to @@ -246,8 +256,9 @@ application:

    package org.apache.cordova.plugin;
     
    -import org.apache.cordova.api.CordovaPlugin;
    -import org.apache.cordova.api.PluginResult;
    +import org.apache.cordova.CordovaPlugin;
    +import org.apache.cordova.CallbackContext;
    +
     import org.json.JSONArray;
     import org.json.JSONException;
     import org.json.JSONObject;
    @@ -256,6 +267,7 @@ 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")) {
    @@ -305,10 +317,10 @@ JavaScript success callback function.

      -
    • 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 +
    • 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 -Intents 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.
    • +Intents 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 @@ -317,7 +329,7 @@ a new Android Intent. The <

    One of the best ways to prepare yourself to write your own plugin is to look over existing plugins.

    -

    You should also read through the comments in CordovaPlugin.java.

    +

    You should also read through the comments in CordovaPlugin.java.

    Modified: cordova/site/public/docs/en/3.0.0/guide_platforms_android_tools.md.html URL: http://svn.apache.org/viewvc/cordova/site/public/docs/en/3.0.0/guide_platforms_android_tools.md.html?rev=1509456&r1=1509455&r2=1509456&view=diff ============================================================================== --- cordova/site/public/docs/en/3.0.0/guide_platforms_android_tools.md.html (original) +++ cordova/site/public/docs/en/3.0.0/guide_platforms_android_tools.md.html Thu Aug 1 22:17:43 2013 @@ -95,7 +95,6 @@
  • Overview
  • The Command-line Interface
  • Platform Guides
  • -
  • Guides
  • Configuration Reference
  • Embedding WebViews
  • Plugin Development Guide
  • @@ -176,7 +175,7 @@ $ C:\path\to\project\cordova\build.bat -

    The run command accepts the following optional parameters:

      -
    • Target specification. This includes --emulator, --device, or --target=<targetID>.
    • +
    • Target specification. This includes --emulator, --device, or --target=<targetID>.

    • Build specification. This includes --debug, --release, or --nobuild.