You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by mw...@apache.org on 2013/10/22 00:13:43 UTC
[01/14] docs commit: [CB-3825] improve plugins section
Updated Branches:
refs/heads/master 25e4b9e31 -> 685d0750f
[CB-3825] improve plugins section
Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/52db02fd
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/52db02fd
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/52db02fd
Branch: refs/heads/master
Commit: 52db02fdbbe720839303d75ae44b6695f3fdc6c1
Parents: 25e4b9e
Author: Mike Sierra <ms...@adobe.com>
Authored: Mon Oct 7 10:38:42 2013 -0400
Committer: Michael Brooks <mi...@michaelbrooks.ca>
Committed: Mon Oct 21 15:08:02 2013 -0700
----------------------------------------------------------------------
docs/en/edge/guide/hybrid/plugins/index.md | 157 ++++++++++++------------
1 file changed, 80 insertions(+), 77 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/52db02fd/docs/en/edge/guide/hybrid/plugins/index.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/hybrid/plugins/index.md b/docs/en/edge/guide/hybrid/plugins/index.md
index cf720d7..613aacd 100644
--- a/docs/en/edge/guide/hybrid/plugins/index.md
+++ b/docs/en/edge/guide/hybrid/plugins/index.md
@@ -19,59 +19,66 @@ license: Licensed to the Apache Software Foundation (ASF) under one
# Plugin Development Guide
-A Cordova plugin bridges a bit of functionality between the WebView
-powering a Cordova application and the native platform the Cordova
-application is running on. Plugins are composed of a single JavaScript
-interface used across all platforms, and native implementations
-following platform-specific Plugin interfaces that the JavaScript
-calls into. All of the core Cordova APIs are implemented using this
-architecture.
-
-This guide steps the process of writing a simple Echo Plugin that
-passes a string from JavaScript and sends it into the native
-environment for the supported platforms. The native code then returns
-the same string back to the callbacks inside the plugin's JavaScript.
-
-This guide provides enough overview on which you can build to write
-more complex plugins.
-
-## JavaScript
-
-The entry point for any plugin is JavaScript. The reason developers use
-Cordova is so they can use and write JavaScript, not Objective-C,
-not Java, not C#. The JavaScript interface for your plugin is the
-front-facing and arguably most important part of your Cordova plugin.
-
-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:
-
- cordova.exec(function(winParam) {}, function(error) {}, "service",
- "action", ["firstArgument", "secondArgument", 42,
- false]);
-
-The parameters are detailed below:
-
-* `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
- is mapped to a native class, about which more information is
+A _plugin_ is a bit of injected code that allows the webview within
+which your app renders to communicate with the native platform on
+which it runs. Plugins thus provide access to device and platform
+functionality that is ordinarily unavailable to web-based apps. All
+the main Cordova API features are implemented as plugins, and many
+others are available that enable features such as bar code scanners,
+NFC communication, or to tailor calendar interfaces.
+
+This section steps through how to write a simple _echo_ plugin that
+passes a string from JavaScript to the native platform and back. You
+can build far more complex plugins based on this simple model. This
+section discusses the outward-facing JavaScript interface. For each
+corresponding native interface, see the list at the end of this
+section. For detailed information on the plugin format, see the
+Plugin Specification. For information on how to add existing plugins
+to an app, see The Command-line Interface.
+
+<!-- ## File and Directory Structure -->
+
+## The JavaScript Interface
+
+Plugins comprise a single JavaScript interface along with
+corresponding native code libraries for each supported platform. The
+JavaScript provides the provides the front-facing interface, making it
+perhaps the most important part of the plugin.
+
+You can structure your plugin's JavaScript however you like, but you
+need to call `cordova.exec` to communicate with the native platform,
+as in the following example:
+
+ cordova.exec(function(winParam) {},
+ function(error) {},
+ "service",
+ "action",
+ ["firstArgument", "secondArgument", 42, false]);
+
+The parameters work as follows:
+
+- `function(winParam) {}`: A success callback function. Assuming your
+ `exec` call completes successfully, this function executes along
+ with any parameters you pass to it.
+
+- `function(error) {}`: An error callback function. If the operation
+ does not complete successfully, this function executes with an
+ optional error parameter.
+
+- `"service"`: The service name to call on the native side. This
+ corresponds to a native class, for which more information is
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.
+- `"action"`: The action name to call on the native side. This
+ generally corresponds to the native class method. See the native
+ guides listed below.
-* `[/* arguments */]`: Arguments to pass into the native environment.
+- `[/* arguments */]`: An array of arguments to pass into the native
+ environment.
-### Echo Plugin JavaScript Example
+## Sample JavaScript
+
+This example shows how to specify the plugin's JavaScript interface:
window.echo = function(str, callback) {
cordova.exec(callback, function(err) {
@@ -79,49 +86,45 @@ The parameters are detailed below:
}, "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:
+In this example, the plugin attaches itself to the `window` object as
+the `echo` function, which plugin users would call as follows:
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`
-function. We will be calling the `Echo` "service", requesting the `echo`
-"action", and passing an array of arguments containing the echo string,
-which is the first parameter into the `window.echo` function.
+Look at the last three arguments to the `cordova.exec` function. The
+first calls the `Echo` _service_. The second requests the `echo`
+_action_. The third is an array of arguments containing the echo
+string, which is the `window.echo` function's the first parameter.
The success callback passed into `exec` is simply a reference to the
-callback function that `window.echo` takes. We do a bit more for the
-error callback: if the native side fires off the error callback, we
-simply invoke the success callback and pass into it a "default"
-string.
-
-## Plugin Specification
-
-Cordova has a plugin specification available to enable automated
-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.
-
-- Plugin Specification
+callback function `window.echo` takes. If the native platform fires
+the error callback, it simply calls the success callback and passes it
+a default string.
-## Native
+## Native Interfaces
Once you define JavaScript for your plugin, you need to complement it
-with at least one native implementation. Details to do so for each
-platform are listed below. These guides continue to build on the
-simple Echo Plugin example discussed above.
+with at least one native implementation. Details for each platform are
+listed below, and each builds on the simple Echo Plugin example above:
- Android Plugins
+- iOS Plugins
- BlackBerry Plugins
- BlackBerry 10 Plugins
-- iOS Plugins
- Windows Phone Plugins
-The Tizen platform currently does not support plugins.
+The Tizen platform does not support plugins.
+
+## Plugin Specification
+
+Cordova's plugin specification allows plugins to be installed
+automatically for Android, iOS, BlackBerry 10 and Windows Phone
+platforms. If you specify a `plugin.xml` manifest file and follow the
+specification's conventions for filename and directory structure,
+users can install your plugin using platform-specific command-line
+tooling. See Plugin Specification for details.
## Publishing plugins
@@ -134,4 +137,4 @@ To publish a plugin you need to use the plugman tool and go through the followin
That is it!
-Other registry-based commands are available and `plugman --help` will give you a list of what commands are available and how to use them.
+Other registry-based commands are available and `plugman --help` will give you a list of what commands are available and how to use them.
[11/14] docs commit: [CB-3825] new boilerplate that intro native;
tighten up android & BB
Posted by mw...@apache.org.
[CB-3825] new boilerplate that intro native; tighten up android & BB
Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/4e709fe7
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/4e709fe7
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/4e709fe7
Branch: refs/heads/master
Commit: 4e709fe7af2c35265ff997bdf1262caeddfbda48
Parents: 025bdbf
Author: Mike Sierra <ms...@adobe.com>
Authored: Wed Oct 16 11:30:38 2013 -0400
Committer: Michael Brooks <mi...@michaelbrooks.ca>
Committed: Mon Oct 21 15:12:52 2013 -0700
----------------------------------------------------------------------
docs/en/edge/guide/platforms/android/plugin.md | 38 +++----
.../edge/guide/platforms/blackberry/plugin.md | 109 ++++++++-----------
.../edge/guide/platforms/blackberry10/plugin.md | 9 +-
docs/en/edge/guide/platforms/ios/plugin.md | 9 +-
docs/en/edge/guide/platforms/wp8/plugin.md | 9 +-
5 files changed, 84 insertions(+), 90 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/4e709fe7/docs/en/edge/guide/platforms/android/plugin.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/android/plugin.md b/docs/en/edge/guide/platforms/android/plugin.md
index a6d34f6..7cd0eae 100644
--- a/docs/en/edge/guide/platforms/android/plugin.md
+++ b/docs/en/edge/guide/platforms/android/plugin.md
@@ -19,25 +19,25 @@ license: Licensed to the Apache Software Foundation (ASF) under one
# Android Plugins
-The section provides details for how to implement plugin code on the
-Android platform. See Application Plugins for an overview of how to
-structure the plugin and implement its common JavaScript interface.
-See also the comments in
-[CordovaPlugin.java](https://github.com/apache/cordova-android/blob/master/framework/src/org/apache/cordova/CordovaPlugin.java) for sample code.
+The 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. A plugin must override one of the `execute`
-methods from `CordovaPlugin`. As best practice, the plugin should also
-handle `pause` and `resume` 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.
+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` and `resume` 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
@@ -93,8 +93,8 @@ 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 the WebCore thread, as does
-the `execute` method. If you need to interact with the user
+`WebView` interface; instead, it runs on the the `WebCore` thread, as
+does the `execute` method. If you need to interact with the user
interface, you should use the following variation:
@Override
@@ -113,7 +113,7 @@ interface, you should use the following variation:
}
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:
+thread, but do not want to block the `WebCore` thread either:
@Override
public boolean execute(String action, JSONArray args, final CallbackContext callbackContext) throws JSONException {
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/4e709fe7/docs/en/edge/guide/platforms/blackberry/plugin.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/blackberry/plugin.md b/docs/en/edge/guide/platforms/blackberry/plugin.md
index 0cd10af..a3cfec9 100644
--- a/docs/en/edge/guide/platforms/blackberry/plugin.md
+++ b/docs/en/edge/guide/platforms/blackberry/plugin.md
@@ -19,25 +19,25 @@ license: Licensed to the Apache Software Foundation (ASF) under one
# BlackBerry Plugins
-The section provides details for how to implement plugin code on the
-BlackBerry platform. See Application Plugins for an overview of how to
-structure the plugin and implement its common JavaScript interface.
-
-This guide shows how to develop an Echo plugin on BlackBerry. The
-Plugin Development Guide provides a broad overview with which you
-should already be familiar, and this guide picks up where it leaves
-off. In addition, download the [Cordova BlackBerry
-repository](https://git-wip-us.apache.org/repos/asf?p=cordova-blackberry-webworks.git;a=summary).
-
+The section provides details for how to implement native plugin code
+on the BlackBerry 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.
+
+In addition, download the [Cordova BlackBerry
+repository](https://git-wip-us.apache.org/repos/asf?p=cordova-blackberry.git;a=summary).
The `Cordova-BlackBerry` project allows you to deploy to BlackBerry
devices such as the Torch, Bold, and Playbook. The Playbook uses a
different code base than other BlackBerry handheld devices, for which
you need to duplicate your development efforts. This guide focuses on
-the handheld devices rather than tablets. (In the future, this guide
-should cover both platforms.)
+handheld devices rather than tablets.
-The Echo plugin essentially returns whatever message a user provides
-to the `window.echo` function:
+## Modifying plugins.xml
+
+The `Echo` plugin returns whatever message a user sends with the
+`window.echo` function on the JavaScript side:
window.echo = function(str, callback) {
cordova.exec(callback, function(err) {
@@ -45,38 +45,29 @@ to the `window.echo` function:
}, "Echo", "echo", [str]);
};
-## Modifying plugins.xml
-
-Your project's `www/plugins.xml` directory contains all of the
-necessary references to your Cordova project's plugins. Add an
-additional reference so that when `cordova.exec` is called, Cordova
-knows how to map the `Echo` argument of `cordova.exec` to the `Echo`
-class that we want to write natively:
+The project's `www/plugins.xml` file contains all of the necessary
+references to the Cordova project's plugins. Add an additional
+reference so that when `cordova.exec` is called, Cordova knows how to
+map the `Echo` argument to the native `Echo` class:
<feature name="Echo">
<param name="blackberry-package" value="org.apache.cordova.echo.Echo" />
</feature>
-## Adding Echo.java
-
-If you notice the structure of the value attribute, you'll see a
-defined path that leads to the Echo plugin. In the root directory of the
-Cordova BlackBerry WebWorks repo, look for a directory called `framework`.
-This directory contains all of the source code that runs natively on the
-BlackBerry. Navigate to `framework/ext/src/org/apache/cordova`. At
-this point, you'll see all of the plugin directorys, inside of which is
-the source code. So add the directory echo to
-`framework/ext/src/org/apache/cordova/echo` and create a file called
-`Echo.java` at `framework/ext/src/org/apache/cordova/echo/Echo.java`.
+## The Echo.java File
-## Writing Echo.java
+The `feature` specification's `value` attribute references a reverse
+domain-style identifier. This corresponds to a path within the Cordova
+BlackBerry WebWorks repo's `framework/ext/src` directory. Add a
+`framework/ext/src/org/apache/cordova/echo` directory and and add a
+`Echo.java` file.
-The basic idea behind writing a plugin is to create a class that
-extends the Plugin class and have a method called `execute` to return
-a `PluginResult` class. Any call to `cordova.exec` passes in the
-action to execute within the class, as well as the arguments. In this
-case, "echo" is the action we want to execute within the class "Echo"
-and [str] are the arguments we are passing in.
+The `Echo.java` needs to define a class that extends the `Plugin`
+class. It also needs to implement an `execute` method that returns a
+`PluginResult` class. Any call to `cordova.exec` passes in the action
+within the class to execute, as well as the arguments. In this case,
+the `Echo` class's `echo` method is the action, and `[str]` is an
+additional argument to pass to the method.
package org.apache.cordova.echo;
@@ -107,42 +98,36 @@ and [str] are the arguments we are passing in.
result = new PluginResult(PluginResult.Status.JSON_EXCEPTION, e.getMessage());
}
}
-
return result;
}
-
}
-So if we look at the code above, we can see that within the execute
-method, we are first looking for what actions are coming in. The Echo
-plugin has only one action, `echo`, so we will be only checking for
-that. If our plugin had more actions, it's simply a matter of adding
-more conditional tests to check for those actions.
+In the code above, the `execute` method first brings in an action. In
+this case, there is only one valid `echo` action, so it simply checks
+for that value.
+
+The incoming message passed in as `[str]` from JavaScript is available
+to the `Echo` class as an `args` array. In this case, there is only
+one argument, accessible using a zero-based array index:
-We are then going to grab the message coming in from the arguments
-which is supplied by the args parameter. We can grab the first
-argument by simply doing `String theMsg = args.getString(0);`.
+ String theMsg = args.getString(0);
-We will do some error checking and if the message looks okay, we will
-instantiate a new PluginResult with an ok status:
-`PluginResult.Status.OK` and return the message: `theMsg`. After this,
-we return the result which to be passed back to JavaScript to be fired
-in the success callback. If something fails, we can return various
-status exceptions like `PluginResult.Status.ERROR`,
-`PluginResult.Status.JSON_EXCEPTION`, or
-`PluginResult.Status.INVALID_ACTION`. When passed back, these types of
-results fire the fail callback in JavaScript.
+After various error-checking on the message's value, the method
+instantiates a new `PluginResult` with an `OK` status and returns the
+message. This value, in turn, is passed back as an argument to the
+JavaScript success callback. In case of error, various status codes
+are sent back to the JavaScript's error callback.
-## Updating the .jar in your project's www directory
+## Updating the .jar in the project's www directory
The added `Echo.java` needs to be updated in your project. To build
-the `.jar` file, Navigate to the BlackBerry WebWorks repo's root
+the `.jar` file, navigate to the BlackBerry WebWorks repo's root
directory and run the `ant` command:
ant update -Dproject.path="~/path_to_my_project"
This builds a new `.jar` file in the `build/ext` directory. Copy the
-`build/ext/cordova.jar` file into your `project/www/ext` directory.
+`build/ext/cordova.jar` file into the `project/www/ext` directory.
-If all goes well, that allows you to use the Echo plugin in
+If all goes well, that allows you to use the `Echo` plugin in
BlackBerry.
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/4e709fe7/docs/en/edge/guide/platforms/blackberry10/plugin.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/blackberry10/plugin.md b/docs/en/edge/guide/platforms/blackberry10/plugin.md
index f84c642..cdeb629 100644
--- a/docs/en/edge/guide/platforms/blackberry10/plugin.md
+++ b/docs/en/edge/guide/platforms/blackberry10/plugin.md
@@ -19,9 +19,12 @@ license: Licensed to the Apache Software Foundation (ASF) under one
# BlackBerry 10 Plugins
-The section provides details for how to implement plugin code on the
-BlackBerry 10 platform. See Application Plugins for an overview of how to
-structure the plugin and implement its common JavaScript interface.
+The section provides details for how to implement native plugin code
+on the BlackBerry 10 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.
This is a continuation of the Plugin Development Guide for
Cordova. Once you have reviewed that content, now let's look at things
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/4e709fe7/docs/en/edge/guide/platforms/ios/plugin.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/ios/plugin.md b/docs/en/edge/guide/platforms/ios/plugin.md
index 790c5cd..725f6dd 100644
--- a/docs/en/edge/guide/platforms/ios/plugin.md
+++ b/docs/en/edge/guide/platforms/ios/plugin.md
@@ -19,9 +19,12 @@ license: Licensed to the Apache Software Foundation (ASF) under one
# iOS Plugins
-The section provides details for how to implement plugin code on the
-iOS platform. See Application Plugins for an overview of how to
-structure the plugin and implement its common JavaScript interface.
+The section provides details for how to implement native plugin code
+on the iOS 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.
An iOS plugin is implemented as an Objective-C class that extends the
`CDVPlugin` class. For JavaScript's `exec` method's `service`
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/4e709fe7/docs/en/edge/guide/platforms/wp8/plugin.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/wp8/plugin.md b/docs/en/edge/guide/platforms/wp8/plugin.md
index e53870c..34f1bab 100644
--- a/docs/en/edge/guide/platforms/wp8/plugin.md
+++ b/docs/en/edge/guide/platforms/wp8/plugin.md
@@ -19,9 +19,12 @@ license: Licensed to the Apache Software Foundation (ASF) under one
# Windows Phone Plugins
-The section provides details for how to implement plugin code on the
-Windows Phone platform. See Application Plugins for an overview of how
-to structure the plugin and implement its common JavaScript interface.
+The section provides details for how to implement native plugin code
+on the Windows Phone 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.
Writing a plugin for Cordova on Windows Phone requires a basic
understanding of Cordova's architecture. Cordova-WP7 consists of a
[14/14] docs commit: [CB-3825] BB10 native plugin
Posted by mw...@apache.org.
[CB-3825] BB10 native plugin
Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/685d0750
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/685d0750
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/685d0750
Branch: refs/heads/master
Commit: 685d0750f20aa0a7fa89522ab6fc3d8cee57045e
Parents: 4e709fe
Author: Mike Sierra <ms...@adobe.com>
Authored: Wed Oct 16 12:32:24 2013 -0400
Committer: Michael Brooks <mi...@michaelbrooks.ca>
Committed: Mon Oct 21 15:13:36 2013 -0700
----------------------------------------------------------------------
docs/en/edge/guide/platforms/android/plugin.md | 2 +-
.../edge/guide/platforms/blackberry/plugin.md | 2 +-
.../edge/guide/platforms/blackberry10/plugin.md | 157 +++++++++----------
docs/en/edge/guide/platforms/ios/plugin.md | 2 +-
docs/en/edge/guide/platforms/wp8/plugin.md | 2 +-
5 files changed, 79 insertions(+), 86 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/685d0750/docs/en/edge/guide/platforms/android/plugin.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/android/plugin.md b/docs/en/edge/guide/platforms/android/plugin.md
index 7cd0eae..a496d46 100644
--- a/docs/en/edge/guide/platforms/android/plugin.md
+++ b/docs/en/edge/guide/platforms/android/plugin.md
@@ -19,7 +19,7 @@ license: Licensed to the Apache Software Foundation (ASF) under one
# Android Plugins
-The section provides details for how to implement native plugin code
+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_
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/685d0750/docs/en/edge/guide/platforms/blackberry/plugin.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/blackberry/plugin.md b/docs/en/edge/guide/platforms/blackberry/plugin.md
index a3cfec9..2e076db 100644
--- a/docs/en/edge/guide/platforms/blackberry/plugin.md
+++ b/docs/en/edge/guide/platforms/blackberry/plugin.md
@@ -19,7 +19,7 @@ license: Licensed to the Apache Software Foundation (ASF) under one
# BlackBerry Plugins
-The section provides details for how to implement native plugin code
+This section provides details for how to implement native plugin code
on the BlackBerry 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
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/685d0750/docs/en/edge/guide/platforms/blackberry10/plugin.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/blackberry10/plugin.md b/docs/en/edge/guide/platforms/blackberry10/plugin.md
index cdeb629..57185d0 100644
--- a/docs/en/edge/guide/platforms/blackberry10/plugin.md
+++ b/docs/en/edge/guide/platforms/blackberry10/plugin.md
@@ -19,51 +19,46 @@ license: Licensed to the Apache Software Foundation (ASF) under one
# BlackBerry 10 Plugins
-The section provides details for how to implement native plugin code
+This section provides details for how to implement native plugin code
on the BlackBerry 10 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.
-This is a continuation of the Plugin Development Guide for
-Cordova. Once you have reviewed that content, now let's look at things
-we need to have the Echo plugin for the BlackBerry 10 platform. Recall
-that the Echo plugin basically returns whatever string a user provides
-to the `window.echo` function:
+The Echo plugin basically returns whatever string the `window.echo`
+function sends from JavaScript:
window.echo = function(str, callback) {
- cordova.exec(callback, function(err) {
- callback('Nothing to echo.');
- }, "Echo", "echo", [str]);
- };
+ cordova.exec(callback, function(err) {
+ callback('Nothing to echo.');
+ }, "Echo", "echo", [str]);
+ };
-A native BlackBerry 10 plugin for Cordova contains JavaScript code and
-may also contain native code. The Echo plugin example demonstrates how
-to invoke native functionality from JavaScript. The native and
-JavaScript code communicate with each other through a framework
-provided by JNEXT. Every plugin must also include a `plugin.xml` file.
+A Cordova plugin for BlackBerry 10 contains both JavaScript and native
+code, which communicate with each other through a framework provided
+by JNEXT. Every plugin must also include a `plugin.xml` file.
-## Creating the native part of your plugin
+## Creating the native class
To create the native portion of your plugin, open the BlackBerry 10
-NDK IDE and select File > New > BlackBerry Project > Native Extension
-> BlackBerry WebWorks. Enter your desired project name / location and
-click finish.
+NDK IDE and select __File → New → BlackBerry Project →
+Native Extension → BlackBerry WebWorks__. Enter the desired
+project name and location, then press __Finish__.
The project created by the IDE contains sample code for a memory
-plugin. You may replace or modify these files to include your own
-functionality.
+plugin. You may replace or modify these files to implement your own
+functionality:
- `*name*_js.hpp`: C++ header for the JNEXT code.
- `*name*_js.cpp`: C++ code for JNEXT.
The native interface for the JNEXT extension can be viewed in the
-plugin header file located in the public directory of your project. It
-also contains constants and utility functions that can be used in your
-native code. Your plugin must be derived from JSExt which is defined
-in plugin.h. That is, you must implement the following class:
+plugin header file located in the project's public directory. It also
+features constants and utility functions available from within native
+code. The plugin must be derived from `JSExt`, which is defined in
+`plugin.h`. That is, you must implement the following class:
class JSExt
{
@@ -75,8 +70,8 @@ in plugin.h. That is, you must implement the following class:
std::string m_id;
};
-Therefore, your extension should include the plugin.h header file. In
-the Echo example, you use JSExt as follows in the echo_js.hpp file:
+The extension should include the `plugin.h` header file. In the `Echo`
+example, you use `JSExt` as follows in the `echo_js.hpp` file:
#include "../public/plugin.h"
#include <string>
@@ -97,17 +92,17 @@ the Echo example, you use JSExt as follows in the echo_js.hpp file:
#endif // ECHO_JS_H_
-The `m_id` is an attribute that contains the JNEXT id for this
-object. The id is passed to the class as an argument to the
-constructor. It is needed to trigger events on the JavaScript side
-from native. The CanDelete method is used by JNEXT to determine
-whether your native object can be deleted. The InvokeMethod function
-is called as a result from a request from JavaScript to invoke a
-method of this particular object. The only argument to this function
-is a string passed from JavaScript that this method should parse in
-order to determine which method of the native object should be
-executed. Now we implement these functions in echo_js.cpp. For the
-Echo example, we implement InvokeMethod function as follows:
+The `m_id` attribute contains the `JNEXT` id for the object, which is
+passed to the class as an argument to the constructor. It is needed
+for the native side to trigger events on the JavaScript side. The
+`CanDelete` method determines whether the native object can be
+deleted. The `InvokeMethod` function is called as a result from a
+request from JavaScript to invoke a method of this particular
+object. The only argument to this function is a string passed from
+JavaScript that this method parses to determine which of the native
+object's methods should execute. These methods are implemented in
+`echo_js.cpp`. Here is the `InvokeMethod` function for the `Echo`
+example:
string Echo::InvokeMethod(const string& command) {
@@ -124,16 +119,16 @@ Echo example, we implement InvokeMethod function as follows:
}
}
-Your native plugin must also implement the following callback
+The native plugin must also implement the following callback
functions:
- `extern char* onGetObjList( void );`
- `extern JSExt* onCreateObject( const string& strClassName, const string& strObjId );`
-The `onGetObjList` function returns a comma separated list of classes
+The `onGetObjList` function returns a comma-separated list of classes
supported by JNEXT. JNEXT uses this function to determine the set of
-classes that JNEXT can instantiate. In our Echo plugin, we have the
+classes that JNEXT can instantiate. The `Echo` plugin implements the
following in `echo_js.cpp`:
char* onGetObjList() {
@@ -141,12 +136,12 @@ following in `echo_js.cpp`:
return name;
}
-The `onCreateObject ` function takes two parameters. The first
-parameter is the name of the class requested to be created from the
-JavaScript side. Valid names are those that are returned in
-`onGetObjList`. The second parameter is the unique object id for the
-class. This method returns a pointer to the created plugin object. In
-our Echo plugin, we have the following in `echo_js.cpp`:
+The `onCreateObject ` function takes two parameters. The first is the
+name of the requested class to be created from the JavaScript side,
+with valid names as those returned in `onGetObjList`. The second
+parameter is the class's unique object id. This method returns a
+pointer to the created plugin object. The `Echo` plugin implements the
+following in `echo_js.cpp`:
JSExt* onCreateObject(const string& className, const string& id) {
if (className == "Echo") {
@@ -155,12 +150,12 @@ our Echo plugin, we have the following in `echo_js.cpp`:
return NULL;
}
-##Creating the JavaScript part of your plugin
+## Creating the plugin's JavaScript
-The JavaScript portion of your plugin must contain the following files:
+The plugin must contain the following JavaScript files:
- `client.js`: This is considered the client side and contains the API
- that a Cordova application can call. The API in `client.js` calls
+ available to a Cordova application. The API in `client.js` calls
makes calls to `index.js`. The API in `client.js` also connects
callback functions to the events that fire the callbacks.
@@ -170,9 +165,9 @@ The JavaScript portion of your plugin must contain the following files:
communicate with the native side.
The client and server side (`client.js` and `index.js`) interacts
-through the `Cordova.exec `function. So, in `client.js` you invoke the
-`exec` function and provide the necessary arguments. In the Echo
-plugin, we have the following in the `client.js` file:
+through the `Cordova.exec` function. The `client.js` needs to invoke
+the `exec` function and provide the necessary arguments. The `Echo`
+plugin implements the following in the `client.js` file:
var service = "org.apache.cordova.blackberry.echo",
exec = cordova.require("cordova/exec");
@@ -183,34 +178,34 @@ plugin, we have the following in the `client.js` file:
}
};
-Now, `index.js` interacts with the native side using JNEXT. So you
-attach a constructor function named Echo to JNEXT. Within the
-constructor you perform the following key operations using the init
-function:
+The `index.js` component uses JNEXT to interact with the native
+side. Attaching a constructor function named `Echo` to JNEXT allows
+you to perform the following key operations using the `init` function:
- Specify the required module exported by the native side. The name of
the required module must match the name of a shared library file
- (.so file).
+ (`.so` file):
JNEXT.require("libecho")
- Create an object by using an acquired module and save the ID that's
- returned by the call. self.m_id =
- JNEXT.createObject("libecho.Echo"); When your application calls the
- echo function in `client.js`, that call in turn calls the echo
- function in `index.js`, where the PluginResult object sends a
- response (data) back to `client.js`. Since the args argument passed
- into the functions was converted by JSON.stringfy() and encoded as a
- URIcomponent, you must call the following:
+ returned by the call:
+
+ self.m_id = JNEXT.createObject("libecho.Echo");
+
+ When the application calls the `echo` function in `client.js`, that
+ call in turn calls the `echo` function in `index.js`, where the
+ `PluginResult` object sends data as a response back to `client.js`.
+ Since the `args` argument passed into the functions was converted by
+ `JSON.stringfy()` and encoded as a `URIcomponent`, you must call the
+ following:
data = JSON.parse(decodeURIComponent(args.data));
-You can now send the data back. Let’s put it all together:
+You can now send the data back, as in the following:
module.exports = {
-
echo: function (success, fail, args, env) {
-
var result = new PluginResult(args, env),
data = JSON.parse(decodeURIComponent(args.data)),
response = echo.getInstance().echo(data);
@@ -218,15 +213,14 @@ You can now send the data back. Let’s put it all together:
}
};
-## Architecture of the plugin
+## Plugin Architecture
-You can place the artifacts of the plugin, which includes the
-`plugin.xml` file, the source files (JavaScript, C++), and the binary
-files (`.so`) within any directory structure, as long as you correctly
-specify the file locations in the `plugin.xml` file. A typical
-structure looks like this:
+You can place the plugin's artifacts, including the `plugin.xml` file,
+the JavaScript and C++ source files, and the `.so` binary files within
+any directory structure, as long as you correctly specify the file
+locations in the `plugin.xml` file. Here is a typical structure:
-***your_project_directory*** (>plugin.xml)
+***project_directory*** (>plugin.xml)
- **www** (>client.js)
- **src**
@@ -234,16 +228,15 @@ structure looks like this:
- **device** (>*binary file* *.so)
- **simulator** (>*binary file* *.so)
-(The list shows the hierarchical relationship among the top-level
-directories. The parenthesis shows the contents of a given directory. All
+The list shows the hierarchical relationship among the top-level
+folders. The parenthesis shows the contents of a given directory. All
directory names appear in bold text. File names are preceded by the `>`
-sign.)
+sign.
-## Contents of the `plugin.xml` file
+## The `plugin.xml` file
-The `plugin.xml` file contains the namespace of the extension and other
-metadata. Define the namespace and specify other metadata for the Echo
-plugin as follows:
+The `plugin.xml` file contains the extension's namespace and other
+metadata. Set up the `Echo` plugin as follows:
<plugin xmlns="http://www.phonegap.com/ns/plugins/1.0"
id="org.apache.cordova.blackberry.echo"
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/685d0750/docs/en/edge/guide/platforms/ios/plugin.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/ios/plugin.md b/docs/en/edge/guide/platforms/ios/plugin.md
index 725f6dd..9e55127 100644
--- a/docs/en/edge/guide/platforms/ios/plugin.md
+++ b/docs/en/edge/guide/platforms/ios/plugin.md
@@ -19,7 +19,7 @@ license: Licensed to the Apache Software Foundation (ASF) under one
# iOS Plugins
-The section provides details for how to implement native plugin code
+This section provides details for how to implement native plugin code
on the iOS 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_
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/685d0750/docs/en/edge/guide/platforms/wp8/plugin.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/wp8/plugin.md b/docs/en/edge/guide/platforms/wp8/plugin.md
index 34f1bab..194f682 100644
--- a/docs/en/edge/guide/platforms/wp8/plugin.md
+++ b/docs/en/edge/guide/platforms/wp8/plugin.md
@@ -19,7 +19,7 @@ license: Licensed to the Apache Software Foundation (ASF) under one
# Windows Phone Plugins
-The section provides details for how to implement native plugin code
+This section provides details for how to implement native plugin code
on the Windows Phone 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
[08/14] docs commit: [CB-3825] tighten up WP plugin content
Posted by mw...@apache.org.
[CB-3825] tighten up WP plugin content
Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/2554e293
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/2554e293
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/2554e293
Branch: refs/heads/master
Commit: 2554e293c5ee5c5e0173a3eb02e097cf0253bb19
Parents: fed2788
Author: Mike Sierra <ms...@adobe.com>
Authored: Tue Oct 8 14:16:14 2013 -0400
Committer: Michael Brooks <mi...@michaelbrooks.ca>
Committed: Mon Oct 21 15:12:51 2013 -0700
----------------------------------------------------------------------
docs/en/edge/guide/platforms/wp8/plugin.md | 148 ++++++++++++------------
1 file changed, 73 insertions(+), 75 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/2554e293/docs/en/edge/guide/platforms/wp8/plugin.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/wp8/plugin.md b/docs/en/edge/guide/platforms/wp8/plugin.md
index 33ab84c..e53870c 100644
--- a/docs/en/edge/guide/platforms/wp8/plugin.md
+++ b/docs/en/edge/guide/platforms/wp8/plugin.md
@@ -1,4 +1,4 @@
----
+--
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
@@ -23,32 +23,34 @@ The section provides details for how to implement plugin code on the
Windows Phone platform. See Application Plugins for an overview of how
to structure the plugin and implement its common JavaScript interface.
-Writing a plugin for Cordova on Windows Phone requires a basic understanding of
-the architecture of Cordova. Cordova-WP7 consists of a WebBrowser which hosts the
-application JavaScript code and manages native API calls. There is a BaseCommand
-(`WP7CordovaClassLib.Cordova.Commands.BaseCommand`) class in C# which you can extend,
-and it comes with the majority of the 'plumbing' built for you already.
+Writing a plugin for Cordova on Windows Phone requires a basic
+understanding of Cordova's architecture. Cordova-WP7 consists of a
+`WebBrowser` that hosts the application's JavaScript code and manages
+native API calls. You can extend a C# `BaseCommand` class
+(`WP7CordovaClassLib.Cordova.Commands.BaseCommand`), which comes with
+most of the functionality you need:
-1. Select your project, and right-click to choose __Add → New Item...__
- - Preferably add it to the 'Plugins' directory, but it is up to you
+1. Select your project, and right-click to choose __Add → New
+ Item...__ If you wish, you can add it to the `Plugins` folder.
-2. Select 'Class' and name it `Echo.cs`
- - The name of this class must _exactly_ match what you call into `cordova.exec(win, fail, "Echo", ...)`
+2. Select __Class__ and name it `Echo.cs`. This class name must
+ _exactly_ match what you call specify as the service in the
+ `cordova.exec()` call on the JavaScript side.
-3. Include the base classes implementation
+3. Include the base classes implementation:
using WPCordovaClassLib.Cordova;
using WPCordovaClassLib.Cordova.Commands;
using WPCordovaClassLib.Cordova.JSON;
-4. Extend your class from BaseCommand
+4. Extend your class from `BaseCommand`:
public class Echo : BaseCommand
{
// ...
}
-5. Add a method that is callable from JavaScript
+5. Add an `echo` method that is callable from JavaScript:
public class Echo : BaseCommand
{
@@ -59,6 +61,11 @@ and it comes with the majority of the 'plumbing' built for you already.
}
}
+See the
+[BaseCommand.cs](https://github.com/apache/cordova-wp7/blob/master/templates/standalone/cordovalib/Commands/BaseCommand.cs)
+class for methods available for the plugin to override. For example,
+the plugin can capture 'pause' and 'resume' events.
+
## Namespaces
The default namespace for unqualified commands is:
@@ -68,7 +75,7 @@ The default namespace for unqualified commands is:
// ...
}
-If you want to use your own namespace, you need to make a fully
+If you want to specify your own namespace, you need to make a fully
qualified call to `cordova.exec`. For example, if you want to define
your C# class like this:
@@ -80,55 +87,58 @@ your C# class like this:
}
}
-Then, in JavaScript you need to call `exec` like this:
+The JavaScript would need to call `exec` like this:
cordova.exec(win, fail, "com.mydomain.cordovaExtensions.Echo", ...);
-## Interpreting your arguments in C#
+## Interpreting Arguments in C#
-The data received by your plugin method is a string value, but in actuality
-looking at our JavaScript code, we see our intention was to pass an array of strings.
-Looking back at our JavaScript call to `cordova.exec`, we see we passed `[str]`:
+In the example discussed in Application Plugins, the data your plugin
+receives is a string, but what if you want to pass an array of
+strings? Suppose the JavaScript `cordova.exec` call is specified like
+this:
cordova.exec(win, fail, "Echo", "echo", ["input string"]);
-If we inspect the options string passed in to our `Echo.echo` method,
-we see that the value is actually:
+The value of `options` string passed to the `Echo.echo` method is
+JSON:
"[\"input string\"]"
-All JavaScript `exec` arguments are JSON encoded before being passed into C#.
-
-If we want to treat this as the string we were expecting, we need to decode it.
-We can use simple JSON deserialization.
+All JavaScript `exec` arguments are JSON-encoded before being passed
+into C#, and so need to be decoded:
string optVal = JsonHelper.Deserialize<string[]>(options)[0];
// optVal now has the value of "input string"
-## Passing results from C# to JavaScript
+## Passing Results from C# to JavaScript
-The base class BaseCommand provides methods for passing data to your JavaScript callback handlers.
-To simply signal that the command has succeeded, when no additional result info is needed,
-you can simply call:
+The `BaseCommand` class provides methods to pass data to JavaScript
+callback handlers. If you simply want to signal success with no
+accompanying result, you can simply call:
- DispatchCommandResult(); // calls back with an empty plugin result, considered a success callback
+ DispatchCommandResult();
+ // calls back with an empty plugin result, considered a success callback
-To pass data back, you need to call a different version of `DispatchCommandResult`:
+To pass data back, you need to call `DispatchCommandResult`
+differently:
DispatchCommandResult(new PluginResult(PluginResult.Status.OK, "Everything went as planned, this is a result that is passed to the success handler."));
-To pass structured object data back to JavaScript, it should be encoded as a JSON string:
+Use an encoded JSON string to pass structured object data back to
+JavaScript:
DispatchCommandResult(new PluginResult(PluginResult.Status.OK, "{result:\"super awesome!\"}"));
-If you need to signal that an error has occurred, you can call `DispatchCommandResult` with a `PluginResult` object:
+To signal an error, call `DispatchCommandResult` with a `PluginResult`
+object whose status is `ERROR`:
DispatchCommandResult(new PluginResult(PluginResult.Status.ERROR, "Echo signaled an error"));
-## Handling serialization errors in your plugin's C# method
+## Handling Serialization Errors
-When interpreting your arguments, it is a good idea to use a try/catch block
-in case we have bad input. This is a pattern used throughout the Cordova C# code:
+When interpreting your arguments, `try`/`catch` blocks help screen out
+bad input. This pattern appears throughout the Cordova C# code:
string optVal = null;
@@ -152,20 +162,17 @@ in case we have bad input. This is a pattern used throughout the Cordova C# code
## Plugin XML
-These are windows phone specific examples of using the plugin.xml
-file, refer to the Plugin Specification for more details
+The following shows how to use the `plugin.xml` file to specify a
+plugin's source files on the Windows Phone platform. See Application
+Plugins for an overview, and Plugin Specification for details on
+available options.
-### `<source-file>`
+- The `<source-file>` element defines all plugin resources, such
+ as _.cs_, _.xaml_, _.xaml.cs_, and _.dll_ files, and image assets.
-On windows phone the `<source-file>` element is currently used to
-define all plugin resources (ie. .cs, .xaml, .xaml.cs, .dll, image
-assets etc).
-
-### `<config-file>`
-
-The `<config-file>` element defines what elements get put into a
-config file. For example to add a plugin to the platforms config.xml,
-you would do something like this :
+- The `<config-file>` element defines elements to inject into a
+ configuration file. This example adds a plugin to the platform's
+ `config.xml` file:
<config-file target="config.xml" parent="/*">
<feature name="PluginName">
@@ -173,51 +180,42 @@ you would do something like this :
</feature>
</config-file>
-If we wanted to add the contacts capability to the WMAppManifest.xml,
-it would look like this :
+ This example adds the contacts capability to the `WMAppManifest.xml`
+ file:
<config-file target="Properties/WMAppManifest.xml" parent="/Deployment/App/Capabilities">
<Capability Name="ID_CAP_CONTACTS" />
</config-file>
-## Advanced Plugin Functionality
-
-See other methods that you can override in:
+## Debugging Plugins
-- [BaseCommand.cs](https://github.com/apache/cordova-wp7/blob/master/templates/standalone/cordovalib/Commands/BaseCommand.cs)
+Use Visual Studio's debugger to debug a plugin's C# component. You can
+set a break point at any of the methods exposed by your class.
-For example, you can hook into the 'pause' and 'resume' application events.
-
-### Debugging Plugins
-
-To debug the C# side, you can use Visual Studio's debugger, just set a break point
-at any of the methods exposed by your class.
-
-JavaScript is a little more difficult to debug on Windows Phone. You
-need to use `console.log` to output the state of your plugin, or
-inform yourself of errors.
+JavaScript is more difficult to debug on Windows Phone. You need to
+use `console.log` to output the plugin's state, or to inform
+yourself of errors.
## Common Pitfalls
-- Be careful when deciding on the arguments you pass to native in your JavaScript
- implementation. Most device platforms expect the args passed to cordova.exec
- to be an array, but if you have different types of objects in this array, it
- becomes difficult or impossible to deserialize.
+- Be careful not to pass arguments from JavaScript to the native side
+ that are difficult to deserialize as JSON. Most device platforms
+ expect the argument passed to `cordova.exec()` to be an array, such
+ as the following:
cordova.exec(win, fail, "ServiceName", "MethodName", ["this is a string", 54, {literal:'trouble'}]);
- - This means that your C# code receives a difficult to decode string value, such as:
+ This may result in an overly complex string value for C# to decode:
"[\"this is a string\", 54, { literal:'trouble' }]"
- - Consider converting ALL parameters to strings before calling exec:
+ Instead, consider converting _all_ parameters to strings before
+ calling `exec()`, and decoding each separately:
cordova.exec(win, fail, "ServiceName", "MethodName", ["this is a string", "54", "{literal:'trouble'}"]);
-
string[] optValues = JsonHelper.Deserialize<string[]>(options);
-- It is usually a good idea to do parameter checking in your
- JavaScript code, before you call `exec`. This allows you to re-use
- more JavaScript code among your plugin's various native
+- It is usually better to check parameters in JavaScript before
+ calling `exec()`. Doing so allows you to re-use more code and pull
+ unnecessary functionality from the plugin's various native
implementations.
-
[13/14] docs commit: [CB-3825] suggest using plugman with default CLI
app
Posted by mw...@apache.org.
[CB-3825] suggest using plugman with default CLI app
Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/1a226ade
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/1a226ade
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/1a226ade
Branch: refs/heads/master
Commit: 1a226ade02ce13641f02eb5cda3738a0c13b2304
Parents: 52c0b62
Author: Mike Sierra <ms...@adobe.com>
Authored: Fri Oct 11 16:33:08 2013 -0400
Committer: Michael Brooks <mi...@michaelbrooks.ca>
Committed: Mon Oct 21 15:12:52 2013 -0700
----------------------------------------------------------------------
docs/en/edge/guide/hybrid/plugins/index.md | 6 ++++--
1 file changed, 4 insertions(+), 2 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/1a226ade/docs/en/edge/guide/hybrid/plugins/index.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/hybrid/plugins/index.md b/docs/en/edge/guide/hybrid/plugins/index.md
index 3ef597a..7660b84 100644
--- a/docs/en/edge/guide/hybrid/plugins/index.md
+++ b/docs/en/edge/guide/hybrid/plugins/index.md
@@ -92,11 +92,13 @@ following [node](http://nodejs.org/) command:
$ npm install -g plugman
-Then run the following to test whether iOS dependencies load:
+Then run a command such as the following to test whether iOS
+dependencies load, optionally using a default CLI-generated project as
+described in The Command-line Interface:
$ plugman -platform ios /path/to/my/project/www /path/to/my/plugin
-For details, see Using Plugman to Manage Plugins.
+For details on `plugman` options, see Using Plugman to Manage Plugins.
## The JavaScript Interface
[09/14] docs commit: [CB-3825] reference myplugin.js from home page
when using plugman to test
Posted by mw...@apache.org.
[CB-3825] reference myplugin.js from home page when using plugman to test
Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/025bdbf4
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/025bdbf4
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/025bdbf4
Branch: refs/heads/master
Commit: 025bdbf40873e18ccf7fc6c199f38d6be4ca69b3
Parents: 1a226ad
Author: Mike Sierra <ms...@adobe.com>
Authored: Fri Oct 11 17:02:32 2013 -0400
Committer: Michael Brooks <mi...@michaelbrooks.ca>
Committed: Mon Oct 21 15:12:52 2013 -0700
----------------------------------------------------------------------
docs/en/edge/guide/hybrid/plugins/index.md | 25 ++++++++++++++++++-------
1 file changed, 18 insertions(+), 7 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/025bdbf4/docs/en/edge/guide/hybrid/plugins/index.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/hybrid/plugins/index.md b/docs/en/edge/guide/hybrid/plugins/index.md
index 7660b84..84e8919 100644
--- a/docs/en/edge/guide/hybrid/plugins/index.md
+++ b/docs/en/edge/guide/hybrid/plugins/index.md
@@ -86,19 +86,30 @@ the platform-specific `config.xml` file to make the platform aware of
the additional code library. The `header-file` and `source-file` tags
specify the path to the library's component files.
-You can use the `plugman` utility to validate whether the plugin
-installs correctly for each platform. Install `plugman` with the
-following [node](http://nodejs.org/) command:
+## Validating a Plugin
- $ npm install -g plugman
+You can use the `plugman` utility to check whether the plugin installs
+correctly for each platform. Install `plugman` with the following
+[node](http://nodejs.org/) command:
+
+ $ npm install -g plugman
+
+You need an valid app source directory, such as the top-level `www`
+directory included in a default CLI-generated project as described in
+The Command-line Interface. Make sure the app's `index.html` home
+page reference the name of the plugin's JavaScript interface, as if it
+were in the same source directory:
+
+ <script src="myplugin.js"></script>
Then run a command such as the following to test whether iOS
-dependencies load, optionally using a default CLI-generated project as
-described in The Command-line Interface:
+dependencies load properly:
- $ plugman -platform ios /path/to/my/project/www /path/to/my/plugin
+ $ plugman -platform ios /path/to/my/project/www /path/to/my/plugin
For details on `plugman` options, see Using Plugman to Manage Plugins.
+For information on how to actually _debug_ plugins, see each
+platform's native interface listed at the bottom of this page.
## The JavaScript Interface
[06/14] docs commit: [CB-3825] reorg advanced android plugin content
Posted by mw...@apache.org.
[CB-3825] reorg advanced android plugin content
Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/1d575e0d
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/1d575e0d
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/1d575e0d
Branch: refs/heads/master
Commit: 1d575e0dd5999babb6012336378e81442e7ef7f4
Parents: c96e9d3
Author: Mike Sierra <ms...@adobe.com>
Authored: Tue Oct 8 09:07:32 2013 -0400
Committer: Michael Brooks <mi...@michaelbrooks.ca>
Committed: Mon Oct 21 15:11:54 2013 -0700
----------------------------------------------------------------------
docs/en/edge/guide/hybrid/plugins/index.md | 5 +++
docs/en/edge/guide/platforms/android/plugin.md | 48 +++++++++------------
2 files changed, 26 insertions(+), 27 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/1d575e0d/docs/en/edge/guide/hybrid/plugins/index.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/hybrid/plugins/index.md b/docs/en/edge/guide/hybrid/plugins/index.md
index 8c748cb..37de077 100644
--- a/docs/en/edge/guide/hybrid/plugins/index.md
+++ b/docs/en/edge/guide/hybrid/plugins/index.md
@@ -36,6 +36,11 @@ basic plugin structure and the outward-facing JavaScript interface.
For each corresponding native interface, see the list at the end of
this section.
+In addition to these instructions, when preparing to write a plugin it
+is best to look over
+[existing plugins](https://github.com/apache/cordova-android/tree/master/framework/src/org/apache/cordova)
+for guidance.
+
## Building a Plugin
Application developers use the CLI's `plugin add` command (discussed
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/1d575e0d/docs/en/edge/guide/platforms/android/plugin.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/android/plugin.md b/docs/en/edge/guide/platforms/android/plugin.md
index 51b782e..a6d34f6 100644
--- a/docs/en/edge/guide/platforms/android/plugin.md
+++ b/docs/en/edge/guide/platforms/android/plugin.md
@@ -22,6 +22,8 @@ license: Licensed to the Apache Software Foundation (ASF) under one
The section provides details for how to implement plugin code on the
Android platform. See Application Plugins for an overview of how to
structure the plugin and implement its common JavaScript interface.
+See also the comments in
+[CordovaPlugin.java](https://github.com/apache/cordova-android/blob/master/framework/src/org/apache/cordova/CordovaPlugin.java) for sample code.
Android plugins are based on Cordova-Android, which consists of an
Android WebView with hooks attached to it. Plugins are represented as
@@ -51,7 +53,8 @@ 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.
+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>" />
@@ -194,33 +197,24 @@ callback. If the various checks pass, the `callbackContext.success()`
passes the original `message` string back to JavaScript's success
callback as a parameter.
-## Debugging Android Plugins
-
-You can use Eclipse to debug plugins as Java source included in the
-project. Only the latest version of the Android Developer Tools is
-known to allow source code attachment to _JAR_ dependencies, so this
-is not yet fully supported.
-
-## Common Pitfalls
+## Android Integration
-- Plugins have access to a `CordovaInterface` object. This object has
- access to the Android `Activity` that is running the application.
- This is the `Context` required to launch a new Android `Intent`. The
- `CordovaInterface` allows plugins to start an `Activity` for a
- result, and to set the callback plugin for when the `Intent` comes
- back to the application. This is important, since the `Intent`s
- system is how Android communicates between processes.
+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.
-- 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.
+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.
-## Use the Source
-
-One of the best ways to prepare yourself to write your own plugin is to
-[look over existing plugins](https://github.com/search?q=%40apache+cordova-plugin).
+## Debugging Android Plugins
-You should also read through the comments in
-[CordovaPlugin.java](https://github.com/apache/cordova-android/blob/master/framework/src/org/apache/cordova/CordovaPlugin.java).
+Eclipse allows you to debug plugins as Java source included in the
+project. Only the latest version of the Android Developer Tools
+allows you to attach source code to _JAR_ dependencies, so this
+feature is not yet fully supported.
[10/14] docs commit: [CB-3825] link to plugman page for command-line
plugin tools
Posted by mw...@apache.org.
[CB-3825] link to plugman page for command-line plugin tools
Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/0e3a1d82
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/0e3a1d82
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/0e3a1d82
Branch: refs/heads/master
Commit: 0e3a1d824069dc5e7de4968daf30953ba75ba497
Parents: f7b90cc
Author: Mike Sierra <ms...@adobe.com>
Authored: Fri Oct 11 16:06:48 2013 -0400
Committer: Michael Brooks <mi...@michaelbrooks.ca>
Committed: Mon Oct 21 15:12:52 2013 -0700
----------------------------------------------------------------------
docs/en/edge/guide/platforms/android/tools.md | 4 ++++
docs/en/edge/guide/platforms/blackberry/tools.md | 4 ++++
docs/en/edge/guide/platforms/blackberry10/tools.md | 4 ++++
docs/en/edge/guide/platforms/ios/tools.md | 4 ++++
docs/en/edge/guide/platforms/win8/tools.md | 4 ++++
docs/en/edge/guide/platforms/wp8/tools.md | 4 ++++
6 files changed, 24 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0e3a1d82/docs/en/edge/guide/platforms/android/tools.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/android/tools.md b/docs/en/edge/guide/platforms/android/tools.md
index ce4b19c..0a3c9a6 100644
--- a/docs/en/edge/guide/platforms/android/tools.md
+++ b/docs/en/edge/guide/platforms/android/tools.md
@@ -30,6 +30,10 @@ target. The tools described here are typically available in the
top-level `bin` directory, otherwise consult the __README__ file for
more detailed directions.
+For information on the low-level command-line interface that enables
+plugins, see Using Plugman to Manage Plugins. See Application Plugins
+for an overview.
+
## Create a project
Run the `create` command, specifying the existing path to the project,
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0e3a1d82/docs/en/edge/guide/platforms/blackberry/tools.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/blackberry/tools.md b/docs/en/edge/guide/platforms/blackberry/tools.md
index df4a1f7..ce08538 100644
--- a/docs/en/edge/guide/platforms/blackberry/tools.md
+++ b/docs/en/edge/guide/platforms/blackberry/tools.md
@@ -30,6 +30,10 @@ target. The tools described here are typically available in the
top-level `bin` directory, otherwise consult the __README__ file for
more detailed directions.
+For information on the low-level command-line interface that enables
+plugins, see Using Plugman to Manage Plugins. See Application Plugins
+for an overview.
+
## Create a project
Run the `create` command, specifying the existing path to the project,
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0e3a1d82/docs/en/edge/guide/platforms/blackberry10/tools.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/blackberry10/tools.md b/docs/en/edge/guide/platforms/blackberry10/tools.md
index 8c3f6fa..26f5f11 100644
--- a/docs/en/edge/guide/platforms/blackberry10/tools.md
+++ b/docs/en/edge/guide/platforms/blackberry10/tools.md
@@ -30,6 +30,10 @@ target. The tools described here are typically available in the
top-level `bin` directory, otherwise consult the __README__ file for
more detailed directions.
+For information on the low-level command-line interface that enables
+plugins, see Using Plugman to Manage Plugins. See Application Plugins
+for an overview.
+
If you need help with any command listed below, type the command along
with the `-h` or `-help` arguments, which are supported by all
commands and which provide descriptions for each of the available
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0e3a1d82/docs/en/edge/guide/platforms/ios/tools.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/ios/tools.md b/docs/en/edge/guide/platforms/ios/tools.md
index c37dbcd..cd8cc4d 100644
--- a/docs/en/edge/guide/platforms/ios/tools.md
+++ b/docs/en/edge/guide/platforms/ios/tools.md
@@ -33,6 +33,10 @@ more detailed directions.
The iOS command-line tools are built upon shell scripts and rely on
Xcode command-line tools such as `xcode-select` and `xcodebuild`.
+For information on the low-level command-line interface that enables
+plugins, see Using Plugman to Manage Plugins. See Application Plugins
+for an overview.
+
## Create a project
Run the `create` command, specifying the existing path to the project,
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0e3a1d82/docs/en/edge/guide/platforms/win8/tools.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/win8/tools.md b/docs/en/edge/guide/platforms/win8/tools.md
index db2c68b..3021824 100644
--- a/docs/en/edge/guide/platforms/win8/tools.md
+++ b/docs/en/edge/guide/platforms/win8/tools.md
@@ -30,6 +30,10 @@ target. The tools described here are typically available in the
top-level `bin` directory, otherwise consult the __README__ file for
more detailed directions.
+For information on the low-level command-line interface that enables
+plugins, see Using Plugman to Manage Plugins. See Application Plugins
+for an overview.
+
## Windows 8
The Windows 8 command-line tools only support creating new projects.
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0e3a1d82/docs/en/edge/guide/platforms/wp8/tools.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/wp8/tools.md b/docs/en/edge/guide/platforms/wp8/tools.md
index d57af0d..d85aff1 100644
--- a/docs/en/edge/guide/platforms/wp8/tools.md
+++ b/docs/en/edge/guide/platforms/wp8/tools.md
@@ -30,6 +30,10 @@ target. The tools described here are typically available in the
top-level `bin` directory, otherwise consult the __README__ file for
more detailed directions.
+For information on the low-level command-line interface that enables
+plugins, see Using Plugman to Manage Plugins. See Application Plugins
+for an overview.
+
## Windows Phone
The Windows Phone command-line tools support creating, building, and
[12/14] docs commit: [CB-3825] Use local plugman to validate plugin
packages; minor edits
Posted by mw...@apache.org.
[CB-3825] Use local plugman to validate plugin packages; minor edits
Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/52c0b623
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/52c0b623
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/52c0b623
Branch: refs/heads/master
Commit: 52c0b623662bbe7bcca1167de29d6859e1653954
Parents: 0e3a1d8
Author: Mike Sierra <ms...@adobe.com>
Authored: Fri Oct 11 16:20:47 2013 -0400
Committer: Michael Brooks <mi...@michaelbrooks.ca>
Committed: Mon Oct 21 15:12:52 2013 -0700
----------------------------------------------------------------------
docs/en/edge/guide/hybrid/plugins/index.md | 12 ++++++++++++
docs/en/edge/guide/platforms/ios/upgrading.md | 4 ++--
docs/en/edge/plugin_ref/plugman.md | 8 ++++----
3 files changed, 18 insertions(+), 6 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/52c0b623/docs/en/edge/guide/hybrid/plugins/index.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/hybrid/plugins/index.md b/docs/en/edge/guide/hybrid/plugins/index.md
index 967c9d5..3ef597a 100644
--- a/docs/en/edge/guide/hybrid/plugins/index.md
+++ b/docs/en/edge/guide/hybrid/plugins/index.md
@@ -86,6 +86,18 @@ the platform-specific `config.xml` file to make the platform aware of
the additional code library. The `header-file` and `source-file` tags
specify the path to the library's component files.
+You can use the `plugman` utility to validate whether the plugin
+installs correctly for each platform. Install `plugman` with the
+following [node](http://nodejs.org/) command:
+
+ $ npm install -g plugman
+
+Then run the following to test whether iOS dependencies load:
+
+ $ plugman -platform ios /path/to/my/project/www /path/to/my/plugin
+
+For details, see Using Plugman to Manage Plugins.
+
## The JavaScript Interface
The JavaScript provides the front-facing interface, making it perhaps
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/52c0b623/docs/en/edge/guide/platforms/ios/upgrading.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/ios/upgrading.md b/docs/en/edge/guide/platforms/ios/upgrading.md
index 4401659..aa62302 100644
--- a/docs/en/edge/guide/platforms/ios/upgrading.md
+++ b/docs/en/edge/guide/platforms/ios/upgrading.md
@@ -95,8 +95,8 @@ For CLI projects, run:
__NOTE:__ Starting with Cordova 3.0.0, projects do not come with any
plugins, you will have to install the ones you require for your
-project using the `plugman` CLI utility. See Using Plugman to Manage
-Plugins.
+project using the `plugman` command-line utility. See Using Plugman to
+Manage Plugins.
## Upgrading 2.8.0 projects to 2.9.0 ##
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/52c0b623/docs/en/edge/plugin_ref/plugman.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/plugin_ref/plugman.md b/docs/en/edge/plugin_ref/plugman.md
index 2783e6a..e93a142 100644
--- a/docs/en/edge/plugin_ref/plugman.md
+++ b/docs/en/edge/plugin_ref/plugman.md
@@ -1,5 +1,5 @@
---
-license: Licensed to the Apache Software Foundation (ASF) under one
+ 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
@@ -38,15 +38,15 @@ For more information on plugman, see
To install plugman, you must have [node](http://nodejs.org/) installed
on your machine:
- npm install -g plugman
+ $ npm install -g plugman
Here is the syntax to add a plugin for each platform:
- plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin <name|url|path> [--plugins_dir <directory>] [--www <directory>] [--variable <name>=<value> [--variable <name>=<value> ...]]
+ $ plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin <name|url|path> [--plugins_dir <directory>] [--www <directory>] [--variable <name>=<value> [--variable <name>=<value> ...]]
To uninstall a plugin:
- plugman --uninstall --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin <id> [--www <directory>] [--plugins_dir <directory>]
+ $ plugman --uninstall --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin <id> [--www <directory>] [--plugins_dir <directory>]
## Installing Core Plugins
[03/14] docs commit: [CB-3825] boilerplate & code indent in platform
plugin guides
Posted by mw...@apache.org.
[CB-3825] boilerplate & code indent in platform plugin guides
Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/e63f5fbf
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/e63f5fbf
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/e63f5fbf
Branch: refs/heads/master
Commit: e63f5fbf61c9dbfbd39d775ea46515d5a8751b03
Parents: 192043f
Author: Mike Sierra <ms...@adobe.com>
Authored: Mon Oct 7 13:20:03 2013 -0400
Committer: Michael Brooks <mi...@michaelbrooks.ca>
Committed: Mon Oct 21 15:09:21 2013 -0700
----------------------------------------------------------------------
docs/en/edge/guide/platforms/android/plugin.md | 134 +++++++--------
.../edge/guide/platforms/blackberry/plugin.md | 80 ++++-----
.../edge/guide/platforms/blackberry10/plugin.md | 166 ++++++++++---------
docs/en/edge/guide/platforms/ios/plugin.md | 112 +++++++------
docs/en/edge/guide/platforms/wp8/plugin.md | 100 +++++------
5 files changed, 306 insertions(+), 286 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/e63f5fbf/docs/en/edge/guide/platforms/android/plugin.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/android/plugin.md b/docs/en/edge/guide/platforms/android/plugin.md
index 30a2c1c..443fbf4 100644
--- a/docs/en/edge/guide/platforms/android/plugin.md
+++ b/docs/en/edge/guide/platforms/android/plugin.md
@@ -19,6 +19,10 @@ license: Licensed to the Apache Software Foundation (ASF) under one
# Android Plugins
+The section provides details for how to implement plugin code on the
+Android platform. See Application Plugins for an overview of how to
+structure the plugin and implement its common JavaScript interface.
+
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
@@ -37,7 +41,7 @@ a new page or refreshes, which reloads the JavaScript.
The JavaScript portion of a plugin always uses the `cordova.exec` method as follows:
- exec(<successFunction>, <failFunction>, <service>, <action>, [<args>]);
+ exec(<successFunction>, <failFunction>, <service>, <action>, [<args>]);
This marshals a request from the WebView to the Android native side,
more or less boiling down to calling the `action` method on the
@@ -47,9 +51,9 @@ 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>
+ <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`
call, and the value is the Java classes full name, including the
@@ -66,15 +70,15 @@ What gets dispatched to the plugin via JavaScript's `exec` function gets
passed into the Plugin class's `execute` method. Most `execute`
implementations look like this:
- @Override
- public boolean execute(String action, JSONArray args, CallbackContext callbackContext) throws JSONException {
- if ("beep".equals(action)) {
- this.beep(args.getLong(0));
- callbackContext.success();
- return true;
+ @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.
}
- return false; // Returning false results in a "MethodNotFound" error.
- }
We compare the value of the `action` parameter, and dispatch the
request off to a (private) method in the class, optionally passing
@@ -91,82 +95,82 @@ the WebCore thread. The `execute` method also runs on the WebCore thread.
If you need to interact with the UI, you should use the following:
- @Override
- public boolean execute(String action, JSONArray args, final CallbackContext callbackContext) throws JSONException {
- if ("beep".equals(action)) {
- final long duration = args.getLong(0);
- cordova.getActivity().runOnUiThread(new Runnable() {
- public void run() {
- ...
- callbackContext.success(); // Thread-safe.
- }
- });
- return true;
+ @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;
}
- return false;
- }
If you do not need to run on the UI thread, but do not want to block the WebCore thread:
- @Override
- public boolean execute(String action, JSONArray args, final CallbackContext callbackContext) throws JSONException {
- if ("beep".equals(action)) {
- final long duration = args.getLong(0);
- cordova.getThreadPool().execute(new Runnable() {
- public void run() {
- ...
- callbackContext.success(); // Thread-safe.
- }
- });
- return true;
+ @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;
}
- return false;
- }
### Echo Android Plugin Example
Add the following to our `config.xml` file:
- <feature name="Echo">
- <param name="android-package" value="org.apache.cordova.plugin.Echo" />
- </feature>
+ <feature name="Echo">
+ <param name="android-package" value="org.apache.cordova.plugin.Echo" />
+ </feature>
Then add the following file to
`src/org/apache/cordova/plugin/Echo.java` inside our Cordova-Android
application:
- package org.apache.cordova.plugin;
+ package org.apache.cordova.plugin;
- import org.apache.cordova.CordovaPlugin;
- import org.apache.cordova.CallbackContext;
+ import org.apache.cordova.CordovaPlugin;
+ import org.apache.cordova.CallbackContext;
- import org.json.JSONArray;
- import org.json.JSONException;
- import org.json.JSONObject;
+ 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 {
+ /**
+ * 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;
+ @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;
}
- 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.");
+ private void echo(String message, CallbackContext callbackContext) {
+ if (message != null && message.length() > 0) {
+ callbackContext.success(message);
+ } else {
+ callbackContext.error("Expected one non-empty string argument.");
+ }
}
}
- }
Let's take a look at the code. The necessary `imports` are at
the top. Our class extends from `CordovaPlugin`. We override the
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/e63f5fbf/docs/en/edge/guide/platforms/blackberry/plugin.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/blackberry/plugin.md b/docs/en/edge/guide/platforms/blackberry/plugin.md
index 560d97d..0cd10af 100644
--- a/docs/en/edge/guide/platforms/blackberry/plugin.md
+++ b/docs/en/edge/guide/platforms/blackberry/plugin.md
@@ -19,6 +19,10 @@ license: Licensed to the Apache Software Foundation (ASF) under one
# BlackBerry Plugins
+The section provides details for how to implement plugin code on the
+BlackBerry platform. See Application Plugins for an overview of how to
+structure the plugin and implement its common JavaScript interface.
+
This guide shows how to develop an Echo plugin on BlackBerry. The
Plugin Development Guide provides a broad overview with which you
should already be familiar, and this guide picks up where it leaves
@@ -35,11 +39,11 @@ should cover both platforms.)
The Echo plugin essentially returns whatever message a user provides
to the `window.echo` function:
- window.echo = function(str, callback) {
- cordova.exec(callback, function(err) {
- callback('Nothing to echo.');
- }, "Echo", "echo", [str]);
- };
+ window.echo = function(str, callback) {
+ cordova.exec(callback, function(err) {
+ callback('Nothing to echo.');
+ }, "Echo", "echo", [str]);
+ };
## Modifying plugins.xml
@@ -49,9 +53,9 @@ additional reference so that when `cordova.exec` is called, Cordova
knows how to map the `Echo` argument of `cordova.exec` to the `Echo`
class that we want to write natively:
- <feature name="Echo">
- <param name="blackberry-package" value="org.apache.cordova.echo.Echo" />
- </feature>
+ <feature name="Echo">
+ <param name="blackberry-package" value="org.apache.cordova.echo.Echo" />
+ </feature>
## Adding Echo.java
@@ -74,41 +78,41 @@ action to execute within the class, as well as the arguments. In this
case, "echo" is the action we want to execute within the class "Echo"
and [str] are the arguments we are passing in.
- package org.apache.cordova.echo;
-
- import org.apache.cordova.api.Plugin;
- import org.apache.cordova.api.PluginResult;
- import org.apache.cordova.json4j.JSONArray;
- import org.apache.cordova.json4j.JSONException;
- import org.apache.cordova.json4j.JSONObject;
- /**
- * A simple plugin to demonstrate how to build a plugin for BlackBerry
- * Basically echos back the msg that a user calls to this plugin
- */
- public final class Echo extends Plugin {
-
- public static final String echo = "echo";
-
- public PluginResult execute(String action, JSONArray args, String callbackId) {
- PluginResult result = new PluginResult(PluginResult.Status.INVALID_ACTION, "Echo: Invalid action:" + action);
- if(action.equals(echo)){
- try {
- String theMsg = args.getString(0);
- if(theMsg!= null || theMsg.length()>0){
- result = new PluginResult(PluginResult.Status.OK, theMsg);
- }else{
- result = new PluginResult(PluginResult.Status.ERROR, "Nothing to echo.");
+ package org.apache.cordova.echo;
+
+ import org.apache.cordova.api.Plugin;
+ import org.apache.cordova.api.PluginResult;
+ import org.apache.cordova.json4j.JSONArray;
+ import org.apache.cordova.json4j.JSONException;
+ import org.apache.cordova.json4j.JSONObject;
+ /**
+ * A simple plugin to demonstrate how to build a plugin for BlackBerry
+ * Basically echos back the msg that a user calls to this plugin
+ */
+ public final class Echo extends Plugin {
+
+ public static final String echo = "echo";
+
+ public PluginResult execute(String action, JSONArray args, String callbackId) {
+ PluginResult result = new PluginResult(PluginResult.Status.INVALID_ACTION, "Echo: Invalid action:" + action);
+ if(action.equals(echo)){
+ try {
+ String theMsg = args.getString(0);
+ if(theMsg!= null || theMsg.length()>0){
+ result = new PluginResult(PluginResult.Status.OK, theMsg);
+ }else{
+ result = new PluginResult(PluginResult.Status.ERROR, "Nothing to echo.");
+ }
+ } catch (JSONException e) {
+ result = new PluginResult(PluginResult.Status.JSON_EXCEPTION, e.getMessage());
}
- } catch (JSONException e) {
- result = new PluginResult(PluginResult.Status.JSON_EXCEPTION, e.getMessage());
}
+
+ return result;
}
- return result;
}
- }
-
So if we look at the code above, we can see that within the execute
method, we are first looking for what actions are coming in. The Echo
plugin has only one action, `echo`, so we will be only checking for
@@ -135,7 +139,7 @@ The added `Echo.java` needs to be updated in your project. To build
the `.jar` file, Navigate to the BlackBerry WebWorks repo's root
directory and run the `ant` command:
- ant update -Dproject.path="~/path_to_my_project"
+ ant update -Dproject.path="~/path_to_my_project"
This builds a new `.jar` file in the `build/ext` directory. Copy the
`build/ext/cordova.jar` file into your `project/www/ext` directory.
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/e63f5fbf/docs/en/edge/guide/platforms/blackberry10/plugin.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/blackberry10/plugin.md b/docs/en/edge/guide/platforms/blackberry10/plugin.md
index 2bd4fe5..bb28422 100644
--- a/docs/en/edge/guide/platforms/blackberry10/plugin.md
+++ b/docs/en/edge/guide/platforms/blackberry10/plugin.md
@@ -19,13 +19,17 @@ license: Licensed to the Apache Software Foundation (ASF) under one
# BlackBerry 10 Plugins
+The section provides details for how to implement plugin code on the
+BlackBerry 10 platform. See Application Plugins for an overview of how to
+structure the plugin and implement its common JavaScript interface.
+
This is a continuation of the Plugin Development Guide for Cordova. Once you have reviewed that content, now let's look at things we need to have the Echo plugin for the BlackBerry 10 platform. Recall that the Echo plugin basically returns whatever string a user provides to the `window.echo` function:
- window.echo = function(str, callback) {
- cordova.exec(callback, function(err) {
- callback('Nothing to echo.');
- }, "Echo", "echo", [str]);
- };
+ window.echo = function(str, callback) {
+ cordova.exec(callback, function(err) {
+ callback('Nothing to echo.');
+ }, "Echo", "echo", [str]);
+ };
A native BlackBerry 10 plugin for Cordova contains JavaScript code and may also contain native code. The Echo plugin example demonstrates how to invoke native functionality from JavaScript. The native and JavaScript code communicate with each other through a framework provided by JNEXT. Every plugin must also include a `plugin.xml` file.
@@ -41,56 +45,56 @@ The project created by the IDE contains sample code for a memory plugin. You may
The native interface for the JNEXT extension can be viewed in the plugin header file located in the public directory of your project. It also contains constants and utility functions that can be used in your native code. Your plugin must be derived from JSExt which is defined in plugin.h. That is, you must implement the following class:
- class JSExt
- {
- public:
- virtual ~JSExt() {};
- virtual string InvokeMethod( const string& strCommand ) = 0;
- virtual bool CanDelete( void ) = 0;
- private:
- std::string m_id;
- };
+ class JSExt
+ {
+ public:
+ virtual ~JSExt() {};
+ virtual string InvokeMethod( const string& strCommand ) = 0;
+ virtual bool CanDelete( void ) = 0;
+ private:
+ std::string m_id;
+ };
Therefore, your extension should include the plugin.h header file. In the Echo example, you use JSExt as follows in the echo_js.hpp file:
- #include "../public/plugin.h"
- #include <string>
-
- #ifndef ECHO_JS_H_
- #define ECHO_JS_H_
-
- class Echo : public JSExt
- {
- public:
- explicit Echo(const std::string& id);
- virtual ~Echo();
- virtual std::string InvokeMethod(const std::string& command);
- virtual bool CanDelete();
- private:
- std::string m_id;
- };
+ #include "../public/plugin.h"
+ #include <string>
+
+ #ifndef ECHO_JS_H_
+ #define ECHO_JS_H_
+
+ class Echo : public JSExt
+ {
+ public:
+ explicit Echo(const std::string& id);
+ virtual ~Echo();
+ virtual std::string InvokeMethod(const std::string& command);
+ virtual bool CanDelete();
+ private:
+ std::string m_id;
+ };
- #endif // ECHO_JS_H_
+ #endif // ECHO_JS_H_
The `m_id` is an attribute that contains the JNEXT id for this object. The id is passed to the class as an argument to the constructor. It is needed to trigger events on the JavaScript side from native.
The CanDelete method is used by JNEXT to determine whether your native object can be deleted.
The InvokeMethod function is called as a result from a request from JavaScript to invoke a method of this particular object. The only argument to this function is a string passed from JavaScript that this method should parse in order to determine which method of the native object should be executed.
Now we implement these functions in echo_js.cpp. For the Echo example, we implement InvokeMethod function as follows:
- string Echo::InvokeMethod(const string& command) {
+ string Echo::InvokeMethod(const string& command) {
- //parse command and args from string
- int index = command.find_first_of(" ");
- string strCommand = command.substr(0, index);
- string strValue = command.substr(index + 1, command.length());
+ //parse command and args from string
+ int index = command.find_first_of(" ");
+ string strCommand = command.substr(0, index);
+ string strValue = command.substr(index + 1, command.length());
- // Determine which function should be executed
- if (strCommand == "echo") {
- return strValue;
- } else {
- return "Unsupported Method";
+ // Determine which function should be executed
+ if (strCommand == "echo") {
+ return strValue;
+ } else {
+ return "Unsupported Method";
+ }
}
- }
Your native plugin must also implement the following callback functions:
@@ -100,19 +104,19 @@ Your native plugin must also implement the following callback functions:
The `onGetObjList` function returns a comma separated list of classes supported by JNEXT. JNEXT uses this function to determine the set of classes that JNEXT can instantiate. In our Echo plugin, we have the following in `echo_js.cpp`:
- char* onGetObjList() {
- static char name[] = "Echo";
- return name;
- }
+ char* onGetObjList() {
+ static char name[] = "Echo";
+ return name;
+ }
The `onCreateObject ` function takes two parameters. The first parameter is the name of the class requested to be created from the JavaScript side. Valid names are those that are returned in `onGetObjList`. The second parameter is the unique object id for the class. This method returns a pointer to the created plugin object. In our Echo plugin, we have the following in `echo_js.cpp`:
- JSExt* onCreateObject(const string& className, const string& id) {
- if (className == "Echo") {
- return new Echo(id);
+ JSExt* onCreateObject(const string& className, const string& id) {
+ if (className == "Echo") {
+ return new Echo(id);
+ }
+ return NULL;
}
- return NULL;
- }
##Creating the JavaScript part of your plugin##
@@ -124,14 +128,14 @@ The JavaScript portion of your plugin must contain the following files:
The client and server side (`client.js` and `index.js`) interacts through the `Cordova.exec `function. So, in `client.js` you invoke the `exec` function and provide the necessary arguments. In the Echo plugin, we have the following in the `client.js` file:
- var service = "org.apache.cordova.blackberry.echo",
- exec = cordova.require("cordova/exec");
+ var service = "org.apache.cordova.blackberry.echo",
+ exec = cordova.require("cordova/exec");
- module.exports = {
- echo: function (data, success, fail) {
- exec(success, fail, service, "echo", { data: data });
- }
- };
+ module.exports = {
+ echo: function (data, success, fail) {
+ exec(success, fail, service, "echo", { data: data });
+ }
+ };
Now, `index.js` interacts with the native side using JNEXT. So you attach a constructor function named Echo to JNEXT. Within the constructor you perform the following key operations using the init function:
@@ -147,16 +151,16 @@ When your application calls the echo function in `client.js`, that call in turn
You can now send the data back. Let’s put it all together:
- module.exports = {
+ module.exports = {
- echo: function (success, fail, args, env) {
+ echo: function (success, fail, args, env) {
- var result = new PluginResult(args, env),
- data = JSON.parse(decodeURIComponent(args.data)),
- response = echo.getInstance().echo(data);
- result.ok(response, false);
- }
- };
+ var result = new PluginResult(args, env),
+ data = JSON.parse(decodeURIComponent(args.data)),
+ response = echo.getInstance().echo(data);
+ result.ok(response, false);
+ }
+ };
## Architecture of the plugin ##
@@ -185,18 +189,18 @@ The `plugin.xml` file contains the namespace of the extension and other
metadata. Define the namespace and specify other metadata for the Echo
plugin as follows:
- <plugin xmlns="http://www.phonegap.com/ns/plugins/1.0"
- id="org.apache.cordova.blackberry.echo"
- version="1.0.0">
- <js-module src="www/client.js">
- <merges target="navigator" />
- </js-module>
- <platform name="blackberry10">
- <source-file src="src/blackberry10/index.js" />
- <lib-file src="src/blackberry10/native/device/libecho.so" arch="device" />
- <lib-file src="src/blackberry10/native/simulator/libecho.so" arch="simulator" />
- <config-file target="www/config.xml" parent="/widget">
- <feature name="org.apache.cordova.blackberry.echo" value="org.apache.cordova.blackberry.echo" />
- </config-file>
- </platform>
- </plugin>
+ <plugin xmlns="http://www.phonegap.com/ns/plugins/1.0"
+ id="org.apache.cordova.blackberry.echo"
+ version="1.0.0">
+ <js-module src="www/client.js">
+ <merges target="navigator" />
+ </js-module>
+ <platform name="blackberry10">
+ <source-file src="src/blackberry10/index.js" />
+ <lib-file src="src/blackberry10/native/device/libecho.so" arch="device" />
+ <lib-file src="src/blackberry10/native/simulator/libecho.so" arch="simulator" />
+ <config-file target="www/config.xml" parent="/widget">
+ <feature name="org.apache.cordova.blackberry.echo" value="org.apache.cordova.blackberry.echo" />
+ </config-file>
+ </platform>
+ </plugin>
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/e63f5fbf/docs/en/edge/guide/platforms/ios/plugin.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/ios/plugin.md b/docs/en/edge/guide/platforms/ios/plugin.md
index 65f0c48..bb7a16b 100644
--- a/docs/en/edge/guide/platforms/ios/plugin.md
+++ b/docs/en/edge/guide/platforms/ios/plugin.md
@@ -19,6 +19,10 @@ license: Licensed to the Apache Software Foundation (ASF) under one
# iOS Plugins
+The section provides details for how to implement plugin code on the
+iOS platform. See Application Plugins for an overview of how to
+structure the plugin and implement its common JavaScript interface.
+
A plugin is an Objective-C class that extends the `CDVPlugin` class.
Each plugin class must be registered as a `<feature>` tag in the
@@ -29,7 +33,7 @@ method's `service` parameter maps to an Objective-C class.
The JavaScript portion of a plugin always uses the `cordova.exec` method as follows:
- exec(<successFunction>, <failFunction>, <service>, <action>, [<args>]);
+ exec(<successFunction>, <failFunction>, <service>, <action>, [<args>]);
This marshals a request from the `UIWebView` to the iOS native side,
more or less boiling down to calling the `action` method on the
@@ -38,9 +42,9 @@ more or less boiling down to calling the `action` method on the
Specifiy the plugin as a `<feature>` tag in your Cordova-iOS
application's project's `config.xml` file.
- <feature name="LocalStorage">
- <param name="ios-package" value="CDVLocalStorage" />
- </feature>
+ <feature name="LocalStorage">
+ <param name="ios-package" value="CDVLocalStorage" />
+ </feature>
The feature `name` attribute should match what you use in the JavaScript
`exec` call's `service` parameter, and the `value` attribute should match the name of the plugin's
@@ -55,10 +59,10 @@ One instance of a plugin object is created for the life of each
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="ios-package" value="Echo" />
- <param name="onload" value="true" />
- </feature>
+ <feature name="Echo">
+ <param name="ios-package" value="Echo" />
+ <param name="onload" value="true" />
+ </feature>
There is _no_ designated initializer for plugins. Instead, plugins
should use the `pluginInitialize` method for their start-up logic.
@@ -75,18 +79,18 @@ We have JavaScript fire off a plugin request to the native side. We have the iOS
What gets dispatched to the plugin via JavaScript's `exec` function gets passed into the corresponding Plugin class's `action` method. A plugin method has this signature:
- - (void)myMethod:(CDVInvokedUrlCommand*)command
- {
- CDVPluginResult* pluginResult = nil;
- NSString* myarg = [command.arguments objectAtIndex:0];
+ - (void)myMethod:(CDVInvokedUrlCommand*)command
+ {
+ CDVPluginResult* pluginResult = nil;
+ NSString* myarg = [command.arguments objectAtIndex:0];
- if (myarg != nil) {
- pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_OK];
- } else {
- pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_ERROR messageAsString:@"Arg was null"];
+ if (myarg != nil) {
+ pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_OK];
+ } else {
+ pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_ERROR messageAsString:@"Arg was null"];
+ }
+ [self.commandDelegate sendPluginResult:pluginResult callbackId:command.callbackId];
}
- [self.commandDelegate sendPluginResult:pluginResult callbackId:command.callbackId];
- }
1. [CDVInvokedUrlCommand.h](https://github.com/apache/cordova-ios/blob/master/CordovaLib/Classes/CDVInvokedUrlCommand.h)
@@ -98,7 +102,7 @@ What gets dispatched to the plugin via JavaScript's `exec` function gets passed
Using CDVPluginResult you can return a variety of result types back to your JavaScript callbacks, using class methods that look like:
- + (CDVPluginResult*)resultWithStatus:(CDVCommandStatus)statusOrdinal messageAs...
+ + (CDVPluginResult*)resultWithStatus:(CDVCommandStatus)statusOrdinal messageAs...
You can create `String`, `Int`, `Double`, `Bool`, `Array`,
`Dictionary`, `ArrayBuffer`, and `Multipart` types. Or, don't attach
@@ -116,45 +120,45 @@ callback does not fire.
We would add the following to the project's `config.xml` file:
- <feature name="Echo">
- <param name="ios-package" value="Echo" />
- </feature>
+ <feature name="Echo">
+ <param name="ios-package" value="Echo" />
+ </feature>
Then we would add the following files (`Echo.h` and `Echo.m`) to the Plugins directory inside our Cordova-iOS
application directory:
- /********* Echo.h Cordova Plugin Header *******/
+ /********* Echo.h Cordova Plugin Header *******/
- #import <Cordova/CDV.h>
+ #import <Cordova/CDV.h>
- @interface Echo : CDVPlugin
+ @interface Echo : CDVPlugin
- - (void)echo:(CDVInvokedUrlCommand*)command;
+ - (void)echo:(CDVInvokedUrlCommand*)command;
- @end
+ @end
- /********* Echo.m Cordova Plugin Implementation *******/
+ /********* Echo.m Cordova Plugin Implementation *******/
- #import "Echo.h"
- #import <Cordova/CDV.h>
+ #import "Echo.h"
+ #import <Cordova/CDV.h>
- @implementation Echo
+ @implementation Echo
- - (void)echo:(CDVInvokedUrlCommand*)command
- {
- CDVPluginResult* pluginResult = nil;
- NSString* echo = [command.arguments objectAtIndex:0];
+ - (void)echo:(CDVInvokedUrlCommand*)command
+ {
+ CDVPluginResult* pluginResult = nil;
+ NSString* echo = [command.arguments objectAtIndex:0];
- if (echo != nil && [echo length] > 0) {
- pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_OK messageAsString:echo];
- } else {
- pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_ERROR];
- }
+ if (echo != nil && [echo length] > 0) {
+ pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_OK messageAsString:echo];
+ } else {
+ pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_ERROR];
+ }
- [self.commandDelegate sendPluginResult:pluginResult callbackId:command.callbackId];
- }
+ [self.commandDelegate sendPluginResult:pluginResult callbackId:command.callbackId];
+ }
- @end
+ @end
Let's take a look at the code. At the top we have all of the necessary
Cordova imports. Our class extends from `CDVPlugin` (very important).
@@ -181,17 +185,17 @@ Plugin methods are executed in the same thread as the UI. If your
plugin requires a great deal of processing or requires a blocking
call, you should use a background thread. For example:
- - (void)myPluginMethod:(CDVInvokedUrlCommand*)command
- {
- // Check command.arguments here.
- [self.commandDelegate runInBackground:^{
- NSString* payload = nil;
- // Some blocking logic...
- CDVPluginResult* pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_OK messageAsString:payload];
- // The sendPluginResult method is thread-safe.
- [self.commandDelegate sendPluginResult:pluginResult callbackId:command.callbackId];
- }];
- }
+ - (void)myPluginMethod:(CDVInvokedUrlCommand*)command
+ {
+ // Check command.arguments here.
+ [self.commandDelegate runInBackground:^{
+ NSString* payload = nil;
+ // Some blocking logic...
+ CDVPluginResult* pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_OK messageAsString:payload];
+ // The sendPluginResult method is thread-safe.
+ [self.commandDelegate sendPluginResult:pluginResult callbackId:command.callbackId];
+ }];
+ }
## Advanced Plugin Functionality
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/e63f5fbf/docs/en/edge/guide/platforms/wp8/plugin.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/wp8/plugin.md b/docs/en/edge/guide/platforms/wp8/plugin.md
index 8deb6ce..b530f8e 100644
--- a/docs/en/edge/guide/platforms/wp8/plugin.md
+++ b/docs/en/edge/guide/platforms/wp8/plugin.md
@@ -19,6 +19,10 @@ license: Licensed to the Apache Software Foundation (ASF) under one
# Windows Phone Plugins
+The section provides details for how to implement plugin code on the
+Windows Phone platform. See Application Plugins for an overview of how
+to structure the plugin and implement its common JavaScript interface.
+
Writing a plugin for Cordova on Windows Phone requires a basic understanding of
the architecture of Cordova. Cordova-WP7 consists of a WebBrowser which hosts the
application JavaScript code and manages native API calls. There is a BaseCommand
@@ -59,26 +63,26 @@ and it comes with the majority of the 'plumbing' built for you already.
The default namespace for unqualified commands is:
- namespace Cordova.Extension.Commands
- {
- // ...
- }
+ namespace Cordova.Extension.Commands
+ {
+ // ...
+ }
If you want to use your own namespace, you need to make a fully
qualified call to `cordova.exec`. For example, if you want to define
your C# class like this:
- namespace com.mydomain.cordovaExtensions
- {
- public class Echo : BaseCommand
+ namespace com.mydomain.cordovaExtensions
{
- // ...
+ public class Echo : BaseCommand
+ {
+ // ...
+ }
}
- }
Then, in JavaScript you need to call `exec` like this:
- cordova.exec(win, fail, "com.mydomain.cordovaExtensions.Echo", ...);
+ cordova.exec(win, fail, "com.mydomain.cordovaExtensions.Echo", ...);
## Interpreting your arguments in C#
@@ -86,20 +90,20 @@ The data received by your plugin method is a string value, but in actuality
looking at our JavaScript code, we see our intention was to pass an array of strings.
Looking back at our JavaScript call to `cordova.exec`, we see we passed `[str]`:
- cordova.exec(win, fail, "Echo", "echo", ["input string"]);
+ cordova.exec(win, fail, "Echo", "echo", ["input string"]);
If we inspect the options string passed in to our `Echo.echo` method,
we see that the value is actually:
- "[\"input string\"]"
+ "[\"input string\"]"
All JavaScript `exec` arguments are JSON encoded before being passed into C#.
If we want to treat this as the string we were expecting, we need to decode it.
We can use simple JSON deserialization.
- string optVal = JsonHelper.Deserialize<string[]>(options)[0];
- // optVal now has the value of "input string"
+ string optVal = JsonHelper.Deserialize<string[]>(options)[0];
+ // optVal now has the value of "input string"
## Passing results from C# to JavaScript
@@ -107,44 +111,44 @@ The base class BaseCommand provides methods for passing data to your JavaScript
To simply signal that the command has succeeded, when no additional result info is needed,
you can simply call:
- DispatchCommandResult(); // calls back with an empty plugin result, considered a success callback
+ DispatchCommandResult(); // calls back with an empty plugin result, considered a success callback
To pass data back, you need to call a different version of `DispatchCommandResult`:
- DispatchCommandResult(new PluginResult(PluginResult.Status.OK, "Everything went as planned, this is a result that is passed to the success handler."));
+ DispatchCommandResult(new PluginResult(PluginResult.Status.OK, "Everything went as planned, this is a result that is passed to the success handler."));
To pass structured object data back to JavaScript, it should be encoded as a JSON string:
- DispatchCommandResult(new PluginResult(PluginResult.Status.OK, "{result:\"super awesome!\"}"));
+ DispatchCommandResult(new PluginResult(PluginResult.Status.OK, "{result:\"super awesome!\"}"));
If you need to signal that an error has occurred, you can call `DispatchCommandResult` with a `PluginResult` object:
- DispatchCommandResult(new PluginResult(PluginResult.Status.ERROR, "Echo signaled an error"));
+ DispatchCommandResult(new PluginResult(PluginResult.Status.ERROR, "Echo signaled an error"));
## Handling serialization errors in your plugin's C# method
When interpreting your arguments, it is a good idea to use a try/catch block
in case we have bad input. This is a pattern used throughout the Cordova C# code:
- string optVal = null;
-
- try
- {
- optVal = JsonHelper.Deserialize<string[]>(options)[0];
- }
- catch(Exception)
- {
- // simply catch the exception, we handle null values and exceptions together
- }
-
- if (optVal == null)
- {
- DispatchCommandResult(new PluginResult(PluginResult.Status.JSON_EXCEPTION));
- }
- else
- {
- // ... continue on to do our work
- }
+ string optVal = null;
+
+ try
+ {
+ optVal = JsonHelper.Deserialize<string[]>(options)[0];
+ }
+ catch(Exception)
+ {
+ // simply catch the exception, we handle null values and exceptions together
+ }
+
+ if (optVal == null)
+ {
+ DispatchCommandResult(new PluginResult(PluginResult.Status.JSON_EXCEPTION));
+ }
+ else
+ {
+ // ... continue on to do our work
+ }
## Plugin XML
@@ -158,16 +162,16 @@ On windows phone the `<source-file>` element is currently used to define all plu
The `<config-file>` element defines what elements get put into a config file. For example to add a plugin to the platforms config.xml, you would do something like this :
- <config-file target="config.xml" parent="/*">
- <feature name="PluginName">
- <param name="wp-package" value="PluginName"/>
- </feature>
- </config-file>
+ <config-file target="config.xml" parent="/*">
+ <feature name="PluginName">
+ <param name="wp-package" value="PluginName"/>
+ </feature>
+ </config-file>
If we wanted to add the contacts capability to the WMAppManifest.xml, it would look like this :
- <config-file target="Properties/WMAppManifest.xml" parent="/Deployment/App/Capabilities">
- <Capability Name="ID_CAP_CONTACTS" />
- </config-file>
+ <config-file target="Properties/WMAppManifest.xml" parent="/Deployment/App/Capabilities">
+ <Capability Name="ID_CAP_CONTACTS" />
+ </config-file>
## Advanced Plugin Functionality
@@ -197,13 +201,13 @@ inform yourself of errors.
- This means that your C# code receives a difficult to decode string value, such as:
- "[\"this is a string\", 54, { literal:'trouble' }]"
+ "[\"this is a string\", 54, { literal:'trouble' }]"
- Consider converting ALL parameters to strings before calling exec:
- cordova.exec(win, fail, "ServiceName", "MethodName", ["this is a string", "54", "{literal:'trouble'}"]) ;
+ cordova.exec(win, fail, "ServiceName", "MethodName", ["this is a string", "54", "{literal:'trouble'}"]);
- string[] optValues = JsonHelper.Deserialize<string[]>(options);
+ string[] optValues = JsonHelper.Deserialize<string[]>(options);
- It is usually a good idea to do parameter checking in your
JavaScript code, before you call `exec`. This allows you to re-use
[04/14] docs commit: [CB-3825] globals; cleanup Android plugin text
Posted by mw...@apache.org.
[CB-3825] globals; cleanup Android plugin text
Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/c96e9d30
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/c96e9d30
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/c96e9d30
Branch: refs/heads/master
Commit: c96e9d305b7e86be8dae95160771ba1fa06aeb38
Parents: e63f5fb
Author: Mike Sierra <ms...@adobe.com>
Authored: Mon Oct 7 16:53:26 2013 -0400
Committer: Michael Brooks <mi...@michaelbrooks.ca>
Committed: Mon Oct 21 15:10:30 2013 -0700
----------------------------------------------------------------------
docs/en/edge/guide/platforms/android/plugin.md | 154 ++++++++++---------
.../edge/guide/platforms/blackberry10/plugin.md | 103 ++++++++++---
docs/en/edge/guide/platforms/ios/plugin.md | 41 +++--
docs/en/edge/guide/platforms/wp8/plugin.md | 17 +-
4 files changed, 204 insertions(+), 111 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/c96e9d30/docs/en/edge/guide/platforms/android/plugin.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/android/plugin.md b/docs/en/edge/guide/platforms/android/plugin.md
index 443fbf4..51b782e 100644
--- a/docs/en/edge/guide/platforms/android/plugin.md
+++ b/docs/en/edge/guide/platforms/android/plugin.md
@@ -23,51 +23,51 @@ The section provides details for how to implement plugin code on the
Android platform. See Application Plugins for an overview of how to
structure the plugin and implement its common JavaScript interface.
-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.
+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. 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 executes when the `WebView` navigates to
-a new page or refreshes, which reloads the JavaScript.
+methods from `CordovaPlugin`. As best practice, the plugin should also
+handle `pause` and `resume` 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 JavaScript portion of a plugin always uses the `cordova.exec` method as follows:
+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,
-more or less boiling down to calling the `action` method on the
-`service` class, with the arguments passed in the `args` Array.
+effectively calling the `action` method on the `service` class, with
+additional 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/` directory.
+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.
<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`
-call, and the value is the Java classes full name, including the
-namespace. Otherwise the plugin may compile but still be unreachable
-by Cordova.
+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.
## Writing an Android Java Plugin
-JavaScript fires off a plugin request to the native side. The Android
-Java plugin is mapped properly via the `config.xml` file. So what
-does the final Android Java Plugin class look like?
-
-What gets dispatched to the plugin via JavaScript's `exec` function gets
-passed into the Plugin class's `execute` method. Most `execute`
+A JavaScript call fires off a plugin request to the native side, and
+the correspoinding 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
@@ -80,20 +80,19 @@ implementations look like this:
return false; // Returning false results in a "MethodNotFound" error.
}
-We compare the value of the `action` parameter, and dispatch the
-request off to a (private) method in the class, optionally passing
-some of the parameters to the method.
+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
-
-JavaScript in the WebView does *not* run on the UI thread. It runs on
-the WebCore thread. The `execute` method also runs on the WebCore thread.
+## Threading
-If you need to interact with the UI, you should use the following:
+The plugin's JavaScript does _not_ run in the main thread of the
+WebView interface; instead, it runs on the 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 {
@@ -110,7 +109,8 @@ If you need to interact with the UI, you should use the following:
return false;
}
-If you do not need to run on the UI thread, but do not want to block the WebCore thread:
+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 {
@@ -127,17 +127,22 @@ If you do not need to run on the UI thread, but do not want to block the WebCore
return false;
}
-### Echo Android Plugin Example
+## Echo Android Plugin Example
-Add the following to our `config.xml` file:
+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:
- <feature name="Echo">
- <param name="android-package" value="org.apache.cordova.plugin.Echo" />
- </feature>
+ <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 file to
-`src/org/apache/cordova/plugin/Echo.java` inside our Cordova-Android
-application:
+Then add the following to the
+`src/org/apache/cordova/plugin/Echo.java` file:
package org.apache.cordova.plugin;
@@ -172,39 +177,50 @@ application:
}
}
-Let's take a look at the code. The necessary `imports` are at
-the top. Our class extends from `CordovaPlugin`. We override the
-execute() method in order to recieve messages from exec(). Our method
-first compares against `action`: this plugin only supports one action,
-the `echo` action. Any other action returns `false`, which results in an
-error of type `INVALID_ACTION`, which translates into an error
-callback invocation on the JavaScript side. Next, we grab the echo
-string using the `getString` method on our `args`, telling it we want
-to get the 0th parameter in the parameter array. We do a bit of
-parameter checking: make sure it is not `null`, and make sure it is
-not a zero-length string. If it is, we call `callbackContext.error()`
-(which, by now, you should know invokes the error callback). If all of
-those checks pass, then we call `callbackContext.success()` and pass
-in the `message` string we received as a parameter. This finally
-translates into a success callback invocation on the JavaScript
-side. It also passes the `message` parameter as a parameter into the
-JavaScript success callback function.
-
-## Debugging Plugins
-
-Eclipse can be used to debug an Android project, and the plugins can be debugged if the Java source is included in the project. Only the latest version of the Android Developer Tools is known to allow source code attachment to JAR dependencies, so this is not fully supported at this time.
+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.
+
+## Debugging Android Plugins
+
+You can use Eclipse to debug plugins as Java source included in the
+project. Only the latest version of the Android Developer Tools is
+known to allow source code attachment to _JAR_ dependencies, so this
+is not yet fully supported.
## Common Pitfalls
-* Plugins have access to a `CordovaInterface` object. This object has access to the Android `Activity` that is running the application. This is the `Context` required to launch
-a new Android `Intent`. The `CordovaInterface` allows plugins to start an `Activity` for a result, and to set the callback plugin for when the `Intent` comes back to the application. This is important, since the
-`Intent`s system is how Android communicates between processes.
+- Plugins have access to a `CordovaInterface` object. This object has
+ access to the Android `Activity` that is running the application.
+ This is the `Context` required to launch a new Android `Intent`. The
+ `CordovaInterface` allows plugins to start an `Activity` for a
+ result, and to set the callback plugin for when the `Intent` comes
+ back to the application. This is important, since the `Intent`s
+ system is how Android communicates between processes.
-* Plugins do not have direct access to the `Context` as they have in the past. The legacy `ctx` member is deprecated, and will be removed six months after 2.0 is released. All of `ctx` methods exist on the `Context`, so both `getContext()` and `getActivity()` are capable of returning the proper object required.
+- Plugins do not have direct access to the `Context` as they have in
+ the past. The legacy `ctx` member is deprecated, and will be removed
+ six months after 2.0 is released. All of `ctx` methods exist on the
+ `Context`, so both `getContext()` and `getActivity()` are capable of
+ returning the proper object required.
## Use the Source
One of the best ways to prepare yourself to write your own plugin is to
[look over existing plugins](https://github.com/search?q=%40apache+cordova-plugin).
-You should also read through the comments in [CordovaPlugin.java](https://github.com/apache/cordova-android/blob/master/framework/src/org/apache/cordova/CordovaPlugin.java).
+You should also read through the comments in
+[CordovaPlugin.java](https://github.com/apache/cordova-android/blob/master/framework/src/org/apache/cordova/CordovaPlugin.java).
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/c96e9d30/docs/en/edge/guide/platforms/blackberry10/plugin.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/blackberry10/plugin.md b/docs/en/edge/guide/platforms/blackberry10/plugin.md
index bb28422..1dc2be2 100644
--- a/docs/en/edge/guide/platforms/blackberry10/plugin.md
+++ b/docs/en/edge/guide/platforms/blackberry10/plugin.md
@@ -23,7 +23,11 @@ The section provides details for how to implement plugin code on the
BlackBerry 10 platform. See Application Plugins for an overview of how to
structure the plugin and implement its common JavaScript interface.
-This is a continuation of the Plugin Development Guide for Cordova. Once you have reviewed that content, now let's look at things we need to have the Echo plugin for the BlackBerry 10 platform. Recall that the Echo plugin basically returns whatever string a user provides to the `window.echo` function:
+This is a continuation of the Plugin Development Guide for
+Cordova. Once you have reviewed that content, now let's look at things
+we need to have the Echo plugin for the BlackBerry 10 platform. Recall
+that the Echo plugin basically returns whatever string a user provides
+to the `window.echo` function:
window.echo = function(str, callback) {
cordova.exec(callback, function(err) {
@@ -31,19 +35,32 @@ This is a continuation of the Plugin Development Guide for Cordova. Once you hav
}, "Echo", "echo", [str]);
};
-A native BlackBerry 10 plugin for Cordova contains JavaScript code and may also contain native code. The Echo plugin example demonstrates how to invoke native functionality from JavaScript. The native and JavaScript code communicate with each other through a framework provided by JNEXT. Every plugin must also include a `plugin.xml` file.
+A native BlackBerry 10 plugin for Cordova contains JavaScript code and
+may also contain native code. The Echo plugin example demonstrates how
+to invoke native functionality from JavaScript. The native and
+JavaScript code communicate with each other through a framework
+provided by JNEXT. Every plugin must also include a `plugin.xml` file.
## Creating the native part of your plugin ##
-To create the native portion of your plugin, open the BlackBerry 10 NDK IDE and select File > New > BlackBerry Project > Native Extension > BlackBerry WebWorks. Enter your desired project name / location and click finish.
+To create the native portion of your plugin, open the BlackBerry 10
+NDK IDE and select File > New > BlackBerry Project > Native Extension
+> BlackBerry WebWorks. Enter your desired project name / location and
+click finish.
-The project created by the IDE contains sample code for a memory plugin. You may replace or modify these files to include your own functionality.
+The project created by the IDE contains sample code for a memory
+plugin. You may replace or modify these files to include your own
+functionality.
- `*name*_js.hpp`: C++ header for the JNEXT code.
- `*name*_js.cpp`: C++ code for JNEXT.
-The native interface for the JNEXT extension can be viewed in the plugin header file located in the public directory of your project. It also contains constants and utility functions that can be used in your native code. Your plugin must be derived from JSExt which is defined in plugin.h. That is, you must implement the following class:
+The native interface for the JNEXT extension can be viewed in the
+plugin header file located in the public directory of your project. It
+also contains constants and utility functions that can be used in your
+native code. Your plugin must be derived from JSExt which is defined
+in plugin.h. That is, you must implement the following class:
class JSExt
{
@@ -55,7 +72,8 @@ The native interface for the JNEXT extension can be viewed in the plugin header
std::string m_id;
};
-Therefore, your extension should include the plugin.h header file. In the Echo example, you use JSExt as follows in the echo_js.hpp file:
+Therefore, your extension should include the plugin.h header file. In
+the Echo example, you use JSExt as follows in the echo_js.hpp file:
#include "../public/plugin.h"
#include <string>
@@ -76,10 +94,17 @@ Therefore, your extension should include the plugin.h header file. In the Echo e
#endif // ECHO_JS_H_
-The `m_id` is an attribute that contains the JNEXT id for this object. The id is passed to the class as an argument to the constructor. It is needed to trigger events on the JavaScript side from native.
-The CanDelete method is used by JNEXT to determine whether your native object can be deleted.
-The InvokeMethod function is called as a result from a request from JavaScript to invoke a method of this particular object. The only argument to this function is a string passed from JavaScript that this method should parse in order to determine which method of the native object should be executed.
-Now we implement these functions in echo_js.cpp. For the Echo example, we implement InvokeMethod function as follows:
+The `m_id` is an attribute that contains the JNEXT id for this
+object. The id is passed to the class as an argument to the
+constructor. It is needed to trigger events on the JavaScript side
+from native. The CanDelete method is used by JNEXT to determine
+whether your native object can be deleted. The InvokeMethod function
+is called as a result from a request from JavaScript to invoke a
+method of this particular object. The only argument to this function
+is a string passed from JavaScript that this method should parse in
+order to determine which method of the native object should be
+executed. Now we implement these functions in echo_js.cpp. For the
+Echo example, we implement InvokeMethod function as follows:
string Echo::InvokeMethod(const string& command) {
@@ -96,20 +121,29 @@ Now we implement these functions in echo_js.cpp. For the Echo example, we implem
}
}
-Your native plugin must also implement the following callback functions:
+Your native plugin must also implement the following callback
+functions:
- `extern char* onGetObjList( void );`
- `extern JSExt* onCreateObject( const string& strClassName, const string& strObjId );`
-The `onGetObjList` function returns a comma separated list of classes supported by JNEXT. JNEXT uses this function to determine the set of classes that JNEXT can instantiate. In our Echo plugin, we have the following in `echo_js.cpp`:
+The `onGetObjList` function returns a comma separated list of classes
+supported by JNEXT. JNEXT uses this function to determine the set of
+classes that JNEXT can instantiate. In our Echo plugin, we have the
+following in `echo_js.cpp`:
char* onGetObjList() {
static char name[] = "Echo";
return name;
}
-The `onCreateObject ` function takes two parameters. The first parameter is the name of the class requested to be created from the JavaScript side. Valid names are those that are returned in `onGetObjList`. The second parameter is the unique object id for the class. This method returns a pointer to the created plugin object. In our Echo plugin, we have the following in `echo_js.cpp`:
+The `onCreateObject ` function takes two parameters. The first
+parameter is the name of the class requested to be created from the
+JavaScript side. Valid names are those that are returned in
+`onGetObjList`. The second parameter is the unique object id for the
+class. This method returns a pointer to the created plugin object. In
+our Echo plugin, we have the following in `echo_js.cpp`:
JSExt* onCreateObject(const string& className, const string& id) {
if (className == "Echo") {
@@ -122,11 +156,20 @@ The `onCreateObject ` function takes two parameters. The first parameter is the
The JavaScript portion of your plugin must contain the following files:
-- `client.js`: This is considered the client side and contains the API that a Cordova application can call. The API in `client.js` calls makes calls to `index.js`. The API in `client.js` also connects callback functions to the events that fire the callbacks.
+- `client.js`: This is considered the client side and contains the API
+ that a Cordova application can call. The API in `client.js` calls
+ makes calls to `index.js`. The API in `client.js` also connects
+ callback functions to the events that fire the callbacks.
-- `index.js`: Cordova loads `index.js` and makes it accessible through the cordova.exec bridge. The `client.js` file makes calls to the API in the `index.js` file, which in turn makes call to JNEXT to communicate with the native side.
+- `index.js`: Cordova loads `index.js` and makes it accessible through
+ the cordova.exec bridge. The `client.js` file makes calls to the API
+ in the `index.js` file, which in turn makes call to JNEXT to
+ communicate with the native side.
-The client and server side (`client.js` and `index.js`) interacts through the `Cordova.exec `function. So, in `client.js` you invoke the `exec` function and provide the necessary arguments. In the Echo plugin, we have the following in the `client.js` file:
+The client and server side (`client.js` and `index.js`) interacts
+through the `Cordova.exec `function. So, in `client.js` you invoke the
+`exec` function and provide the necessary arguments. In the Echo
+plugin, we have the following in the `client.js` file:
var service = "org.apache.cordova.blackberry.echo",
exec = cordova.require("cordova/exec");
@@ -137,17 +180,27 @@ The client and server side (`client.js` and `index.js`) interacts through the `C
}
};
-Now, `index.js` interacts with the native side using JNEXT. So you attach a constructor function named Echo to JNEXT. Within the constructor you perform the following key operations using the init function:
+Now, `index.js` interacts with the native side using JNEXT. So you
+attach a constructor function named Echo to JNEXT. Within the
+constructor you perform the following key operations using the init
+function:
-- Specify the required module exported by the native side. The name of the required module must match the name of a shared library file (.so file).
+- Specify the required module exported by the native side. The name of
+ the required module must match the name of a shared library file
+ (.so file).
-`JNEXT.require("libecho")`
+ JNEXT.require("libecho")
-- Create an object by using an acquired module and save the ID that's returned by the call.
-self.m_id = JNEXT.createObject("libecho.Echo");
-When your application calls the echo function in `client.js`, that call in turn calls the echo function in `index.js`, where the PluginResult object sends a response (data) back to `client.js`. Since the args argument passed into the functions was converted by JSON.stringfy() and encoded as a URIcomponent, you must call the following:
+- Create an object by using an acquired module and save the ID that's
+ returned by the call. self.m_id =
+ JNEXT.createObject("libecho.Echo"); When your application calls the
+ echo function in `client.js`, that call in turn calls the echo
+ function in `index.js`, where the PluginResult object sends a
+ response (data) back to `client.js`. Since the args argument passed
+ into the functions was converted by JSON.stringfy() and encoded as a
+ URIcomponent, you must call the following:
-`data = JSON.parse(decodeURIComponent(args.data));`
+ data = JSON.parse(decodeURIComponent(args.data));
You can now send the data back. Let’s put it all together:
@@ -167,8 +220,8 @@ You can now send the data back. Let’s put it all together:
You can place the artifacts of the plugin, which includes the
`plugin.xml` file, the source files (JavaScript, C++), and the binary
files (`.so`) within any directory structure, as long as you correctly
-specify the file locations in the `plugin.xml` file. A typical structure
-looks like this:
+specify the file locations in the `plugin.xml` file. A typical
+structure looks like this:
***your_project_directory*** (>plugin.xml)
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/c96e9d30/docs/en/edge/guide/platforms/ios/plugin.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/ios/plugin.md b/docs/en/edge/guide/platforms/ios/plugin.md
index bb7a16b..021114d 100644
--- a/docs/en/edge/guide/platforms/ios/plugin.md
+++ b/docs/en/edge/guide/platforms/ios/plugin.md
@@ -75,9 +75,13 @@ the JavaScript.
## Writing an iOS Cordova Plugin
-We have JavaScript fire off a plugin request to the native side. We have the iOS Objective-C plugin mapped properly via the `config.xml` file. So what does the final iOS Objective-C Plugin class look like?
+We have JavaScript fire off a plugin request to the native side. We
+have the iOS Objective-C plugin mapped properly via the `config.xml`
+file. So what does the final iOS Objective-C Plugin class look like?
-What gets dispatched to the plugin via JavaScript's `exec` function gets passed into the corresponding Plugin class's `action` method. A plugin method has this signature:
+What gets dispatched to the plugin via JavaScript's `exec` function
+gets passed into the corresponding Plugin class's `action` method. A
+plugin method has this signature:
- (void)myMethod:(CDVInvokedUrlCommand*)command
{
@@ -100,7 +104,8 @@ What gets dispatched to the plugin via JavaScript's `exec` function gets passed
## iOS CDVPluginResult message types
-Using CDVPluginResult you can return a variety of result types back to your JavaScript callbacks, using class methods that look like:
+Using CDVPluginResult you can return a variety of result types back to
+your JavaScript callbacks, using class methods that look like:
+ (CDVPluginResult*)resultWithStatus:(CDVCommandStatus)statusOrdinal messageAs...
@@ -112,9 +117,18 @@ callback does not fire.
### Notes
- * `messageAsArrayBuffer` expects `NSData*` and converts to an `ArrayBuffer` for your JavaScript callback (and `ArrayBuffers` sent to a plugin from JavaScript are converted to `NSData*`).
- * `messageAsMultipart` expects an `NSArray*` containing any of the other supported types, and sends the whole array as the `arguments` to your JavaScript callback.
- * Quirk: this is not just syntactic sugar (though it is sweet). This way, all of the arguments are serialized or deserialized as necessary. E.g., it is safe to return `NSData*` as multipart, but not as `Array`/`Dictionary`.
+ * `messageAsArrayBuffer` expects `NSData*` and converts to an
+ `ArrayBuffer` for your JavaScript callback (and `ArrayBuffers` sent
+ to a plugin from JavaScript are converted to `NSData*`).
+
+ * `messageAsMultipart` expects an `NSArray*` containing any of the
+ other supported types, and sends the whole array as the `arguments`
+ to your JavaScript callback.
+
+ * Quirk: this is not just syntactic sugar (though it is sweet).
+ This way, all of the arguments are serialized or deserialized as
+ necessary. E.g., it is safe to return `NSData*` as multipart,
+ but not as `Array`/`Dictionary`.
## Echo Plugin iOS Plugin
@@ -124,8 +138,8 @@ We would add the following to the project's `config.xml` file:
<param name="ios-package" value="Echo" />
</feature>
-Then we would add the following files (`Echo.h` and `Echo.m`) to the Plugins directory inside our Cordova-iOS
-application directory:
+Then we would add the following files (`Echo.h` and `Echo.m`) to the
+Plugins folder inside our Cordova-iOS application folder:
/********* Echo.h Cordova Plugin Header *******/
@@ -201,9 +215,9 @@ call, you should use a background thread. For example:
See other methods that you can override in:
-* [CDVPlugin.h](https://github.com/apache/cordova-ios/blob/master/CordovaLib/Classes/CDVPlugin.h)
+- [CDVPlugin.h](https://github.com/apache/cordova-ios/blob/master/CordovaLib/Classes/CDVPlugin.h)
-* [CDVPlugin.m](https://github.com/apache/cordova-ios/blob/master/CordovaLib/Classes/CDVPlugin.m)
+- [CDVPlugin.m](https://github.com/apache/cordova-ios/blob/master/CordovaLib/Classes/CDVPlugin.m)
For example, you can hook into the `pause`, `resume`, app terminate and `handleOpenURL` events.
@@ -219,6 +233,9 @@ running in the iOS 6 Simulator.
## Common Pitfalls
-* Don't forget to add your plugin's mapping to config.xml. If you forget, an error is logged in the Xcode console.
+- Don't forget to add your plugin's mapping to config.xml. If you
+ forget, an error is logged in the Xcode console.
-* Don't forget to add any hosts you connect to in the whitelist, as described in Domain Whitelist Guide. If you forget, an error is logged in the Xcode console.
+- Don't forget to add any hosts you connect to in the whitelist, as
+ described in Domain Whitelist Guide. If you forget, an error is
+ logged in the Xcode console.
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/c96e9d30/docs/en/edge/guide/platforms/wp8/plugin.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/wp8/plugin.md b/docs/en/edge/guide/platforms/wp8/plugin.md
index b530f8e..33ab84c 100644
--- a/docs/en/edge/guide/platforms/wp8/plugin.md
+++ b/docs/en/edge/guide/platforms/wp8/plugin.md
@@ -152,22 +152,29 @@ in case we have bad input. This is a pattern used throughout the Cordova C# code
## Plugin XML
-These are windows phone specific examples of using the plugin.xml file, refer to the Plugin Specification for more details
+These are windows phone specific examples of using the plugin.xml
+file, refer to the Plugin Specification for more details
### `<source-file>`
-On windows phone the `<source-file>` element is currently used to define all plugin resources (ie. .cs, .xaml, .xaml.cs, .dll, image assets etc).
+On windows phone the `<source-file>` element is currently used to
+define all plugin resources (ie. .cs, .xaml, .xaml.cs, .dll, image
+assets etc).
### `<config-file>`
-The `<config-file>` element defines what elements get put into a config file. For example to add a plugin to the platforms config.xml, you would do something like this :
+The `<config-file>` element defines what elements get put into a
+config file. For example to add a plugin to the platforms config.xml,
+you would do something like this :
<config-file target="config.xml" parent="/*">
<feature name="PluginName">
<param name="wp-package" value="PluginName"/>
</feature>
</config-file>
-If we wanted to add the contacts capability to the WMAppManifest.xml, it would look like this :
+
+If we wanted to add the contacts capability to the WMAppManifest.xml,
+it would look like this :
<config-file target="Properties/WMAppManifest.xml" parent="/Deployment/App/Capabilities">
<Capability Name="ID_CAP_CONTACTS" />
@@ -177,7 +184,7 @@ If we wanted to add the contacts capability to the WMAppManifest.xml, it would l
See other methods that you can override in:
-* [BaseCommand.cs](https://github.com/apache/cordova-wp7/blob/master/templates/standalone/cordovalib/Commands/BaseCommand.cs)
+- [BaseCommand.cs](https://github.com/apache/cordova-wp7/blob/master/templates/standalone/cordovalib/Commands/BaseCommand.cs)
For example, you can hook into the 'pause' and 'resume' application events.
[02/14] docs commit: [CB-3825] basic info about plugin.xml repo
structure
Posted by mw...@apache.org.
[CB-3825] basic info about plugin.xml repo structure
Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/192043f5
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/192043f5
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/192043f5
Branch: refs/heads/master
Commit: 192043f5b601b58e3269b4f0074f7ed155a040df
Parents: 52db02f
Author: Mike Sierra <ms...@adobe.com>
Authored: Mon Oct 7 12:51:25 2013 -0400
Committer: Michael Brooks <mi...@michaelbrooks.ca>
Committed: Mon Oct 21 15:09:20 2013 -0700
----------------------------------------------------------------------
docs/en/edge/guide/hybrid/plugins/index.md | 105 ++++++++++++++++--------
1 file changed, 69 insertions(+), 36 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/192043f5/docs/en/edge/guide/hybrid/plugins/index.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/hybrid/plugins/index.md b/docs/en/edge/guide/hybrid/plugins/index.md
index 613aacd..8c748cb 100644
--- a/docs/en/edge/guide/hybrid/plugins/index.md
+++ b/docs/en/edge/guide/hybrid/plugins/index.md
@@ -21,41 +21,81 @@ license: Licensed to the Apache Software Foundation (ASF) under one
A _plugin_ is a bit of injected code that allows the webview within
which your app renders to communicate with the native platform on
-which it runs. Plugins thus provide access to device and platform
+which it runs. Plugins provide access to device and platform
functionality that is ordinarily unavailable to web-based apps. All
the main Cordova API features are implemented as plugins, and many
others are available that enable features such as bar code scanners,
NFC communication, or to tailor calendar interfaces.
-This section steps through how to write a simple _echo_ plugin that
-passes a string from JavaScript to the native platform and back. You
-can build far more complex plugins based on this simple model. This
-section discusses the outward-facing JavaScript interface. For each
-corresponding native interface, see the list at the end of this
-section. For detailed information on the plugin format, see the
-Plugin Specification. For information on how to add existing plugins
-to an app, see The Command-line Interface.
-
-<!-- ## File and Directory Structure -->
+Plugins comprise a single JavaScript interface along with
+corresponding native code libraries for each supported platform. This
+section steps through a simple _echo_ plugin that passes a string from
+JavaScript to the native platform and back, one that you can use as a
+model to build far more complex features. This section discusses the
+basic plugin structure and the outward-facing JavaScript interface.
+For each corresponding native interface, see the list at the end of
+this section.
+
+## Building a Plugin
+
+Application developers use the CLI's `plugin add` command (discussed
+in The Command-line Interface) to apply a plugin to a project. The
+argument to that command is the URL for a _git_ repository containing
+the plugin code. This example implements Cordova's Device API:
+
+ $ cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-device.git
+
+The plugin repository must feature a top-level `plugin.xml` manifest
+file. There are many ways to configure this file, details for which
+are available in the Plugin Specification. This abbreviated version of
+the `Device` plugin provides a simple example to use as a model:
+
+ <?xml version="1.0" encoding="UTF-8"?>
+ <plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
+ id="org.apache.cordova.device" version="0.2.3">
+ <name>Device</name>
+ <description>Cordova Device Plugin</description>
+ <license>Apache 2.0</license>
+ <keywords>cordova,device</keywords>
+ <js-module src="www/device.js" name="device">
+ <clobbers target="device" />
+ </js-module>
+ <platform name="ios">
+ <config-file target="config.xml" parent="/*">
+ <feature name="Device">
+ <param name="ios-package" value="CDVDevice"/>
+ </feature>
+ </config-file>
+ <header-file src="src/ios/CDVDevice.h" />
+ <source-file src="src/ios/CDVDevice.m" />
+ </platform>
+ </plugin>
+
+The top-level `plugin` tag's `id` attribute uses the same
+reverse-domain format to identify the plugin package as the apps to
+they're added. The `js-module` tag specifies the path to the common
+JavaScript interface. The `platform` tag specifies a corresponding
+set of native code, for the `ios` platform in this case. The
+`config-file` tag encapsulates a `feature` tag that is injected into
+the platform-specific `config.xml` file to make the platform aware of
+the additional code library. The `header-file` and `source-file` tags
+specify the path to the library's component files.
## The JavaScript Interface
-Plugins comprise a single JavaScript interface along with
-corresponding native code libraries for each supported platform. The
-JavaScript provides the provides the front-facing interface, making it
-perhaps the most important part of the plugin.
-
-You can structure your plugin's JavaScript however you like, but you
-need to call `cordova.exec` to communicate with the native platform,
-as in the following example:
+The JavaScript provides the front-facing interface, making it perhaps
+the most important part of the plugin. You can structure your
+plugin's JavaScript however you like, but you need to call
+`cordova.exec` to communicate with the native platform, using the
+following syntax:
- cordova.exec(function(winParam) {},
- function(error) {},
+ cordova.exec(function(winParam) {},
+ function(error) {},
"service",
- "action",
+ "action",
["firstArgument", "secondArgument", 42, false]);
-The parameters work as follows:
+Here is how each parameter works:
- `function(winParam) {}`: A success callback function. Assuming your
`exec` call completes successfully, this function executes along
@@ -78,7 +118,8 @@ The parameters work as follows:
## Sample JavaScript
-This example shows how to specify the plugin's JavaScript interface:
+This example shows one way to implement the plugin's JavaScript
+interface:
window.echo = function(str, callback) {
cordova.exec(callback, function(err) {
@@ -94,9 +135,10 @@ the `echo` function, which plugin users would call as follows:
});
Look at the last three arguments to the `cordova.exec` function. The
-first calls the `Echo` _service_. The second requests the `echo`
-_action_. The third is an array of arguments containing the echo
-string, which is the `window.echo` function's the first parameter.
+first calls the `Echo` _service_, a class name. The second requests
+the `echo` _action_, a method within that class. The third is an array
+of arguments containing the echo string, which is the `window.echo`
+function's the first parameter.
The success callback passed into `exec` is simply a reference to the
callback function `window.echo` takes. If the native platform fires
@@ -117,15 +159,6 @@ listed below, and each builds on the simple Echo Plugin example above:
The Tizen platform does not support plugins.
-## Plugin Specification
-
-Cordova's plugin specification allows plugins to be installed
-automatically for Android, iOS, BlackBerry 10 and Windows Phone
-platforms. If you specify a `plugin.xml` manifest file and follow the
-specification's conventions for filename and directory structure,
-users can install your plugin using platform-specific command-line
-tooling. See Plugin Specification for details.
-
## Publishing plugins
Once you developed your plugin, you might want to publish it and share it with the community. You can publish your plugin to the cordova registry (based on [npmjs](https://github.com/isaacs/npmjs.org)) or to any other npmjs based registry. Users will be able to install it automatically using either plugman or cordova-cli.
[07/14] docs commit: [CB-3825] define plugins better
Posted by mw...@apache.org.
[CB-3825] define plugins better
Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/f7b90ccf
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/f7b90ccf
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/f7b90ccf
Branch: refs/heads/master
Commit: f7b90ccf457ac1f3d6a6eb5fc31e403290028650
Parents: 2554e29
Author: Mike Sierra <ms...@adobe.com>
Authored: Fri Oct 11 11:02:18 2013 -0400
Committer: Michael Brooks <mi...@michaelbrooks.ca>
Committed: Mon Oct 21 15:12:51 2013 -0700
----------------------------------------------------------------------
docs/en/edge/guide/hybrid/plugins/index.md | 2 +-
docs/en/edge/guide/platforms/blackberry10/plugin.md | 8 ++++----
2 files changed, 5 insertions(+), 5 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/f7b90ccf/docs/en/edge/guide/hybrid/plugins/index.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/hybrid/plugins/index.md b/docs/en/edge/guide/hybrid/plugins/index.md
index 37de077..967c9d5 100644
--- a/docs/en/edge/guide/hybrid/plugins/index.md
+++ b/docs/en/edge/guide/hybrid/plugins/index.md
@@ -19,7 +19,7 @@ license: Licensed to the Apache Software Foundation (ASF) under one
# Plugin Development Guide
-A _plugin_ is a bit of injected code that allows the webview within
+A _plugin_ is a package of injected code that allows the Cordova webview within
which your app renders to communicate with the native platform on
which it runs. Plugins provide access to device and platform
functionality that is ordinarily unavailable to web-based apps. All
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/f7b90ccf/docs/en/edge/guide/platforms/blackberry10/plugin.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/blackberry10/plugin.md b/docs/en/edge/guide/platforms/blackberry10/plugin.md
index 1dc2be2..f84c642 100644
--- a/docs/en/edge/guide/platforms/blackberry10/plugin.md
+++ b/docs/en/edge/guide/platforms/blackberry10/plugin.md
@@ -41,7 +41,7 @@ to invoke native functionality from JavaScript. The native and
JavaScript code communicate with each other through a framework
provided by JNEXT. Every plugin must also include a `plugin.xml` file.
-## Creating the native part of your plugin ##
+## Creating the native part of your plugin
To create the native portion of your plugin, open the BlackBerry 10
NDK IDE and select File > New > BlackBerry Project > Native Extension
@@ -152,7 +152,7 @@ our Echo plugin, we have the following in `echo_js.cpp`:
return NULL;
}
-##Creating the JavaScript part of your plugin##
+##Creating the JavaScript part of your plugin
The JavaScript portion of your plugin must contain the following files:
@@ -215,7 +215,7 @@ You can now send the data back. Let’s put it all together:
}
};
-## Architecture of the plugin ##
+## Architecture of the plugin
You can place the artifacts of the plugin, which includes the
`plugin.xml` file, the source files (JavaScript, C++), and the binary
@@ -236,7 +236,7 @@ directories. The parenthesis shows the contents of a given directory. All
directory names appear in bold text. File names are preceded by the `>`
sign.)
-## Contents of the `plugin.xml` file##
+## Contents of the `plugin.xml` file
The `plugin.xml` file contains the namespace of the extension and other
metadata. Define the namespace and specify other metadata for the Echo
[05/14] docs commit: [CB-3825] modify/reorg iOS plugin content
Posted by mw...@apache.org.
[CB-3825] modify/reorg iOS plugin content
Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/fed27881
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/fed27881
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/fed27881
Branch: refs/heads/master
Commit: fed278818685bda8aeb7ec5b7ec1a3d3ddbadf19
Parents: 1d575e0
Author: Mike Sierra <ms...@adobe.com>
Authored: Tue Oct 8 11:26:55 2013 -0400
Committer: Michael Brooks <mi...@michaelbrooks.ca>
Committed: Mon Oct 21 15:11:54 2013 -0700
----------------------------------------------------------------------
docs/en/edge/guide/platforms/ios/plugin.md | 202 ++++++++++++------------
1 file changed, 102 insertions(+), 100 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/fed27881/docs/en/edge/guide/platforms/ios/plugin.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/ios/plugin.md b/docs/en/edge/guide/platforms/ios/plugin.md
index 021114d..790c5cd 100644
--- a/docs/en/edge/guide/platforms/ios/plugin.md
+++ b/docs/en/edge/guide/platforms/ios/plugin.md
@@ -23,41 +23,45 @@ The section provides details for how to implement plugin code on the
iOS platform. See Application Plugins for an overview of how to
structure the plugin and implement its common JavaScript interface.
-A plugin is an Objective-C class that extends the `CDVPlugin` class.
-
-Each plugin class must be registered as a `<feature>` tag in the
-`config.xml` file. It is through this mechanism that JavaScript's `exec`
-method's `service` parameter maps to an Objective-C class.
+An iOS plugin is implemented as an Objective-C class that extends the
+`CDVPlugin` class. For JavaScript's `exec` method's `service`
+parameter to map to an Objective-C class, each plugin class must be
+registered as a `<feature>` tag in the named application directory's
+`config.xml` file.
## Plugin Class Mapping
-The JavaScript portion of a plugin always uses the `cordova.exec` method as follows:
+The JavaScript portion of a plugin uses the `cordova.exec` method as
+follows:
exec(<successFunction>, <failFunction>, <service>, <action>, [<args>]);
This marshals a request from the `UIWebView` to the iOS native side,
-more or less boiling down to calling the `action` method on the
-`service` class, with the arguments passed in the `args` array.
+effectively calling the `action` method on the `service` class, with
+the arguments passed in the `args` array.
-Specifiy the plugin as a `<feature>` tag in your Cordova-iOS
-application's project's `config.xml` file.
+Specify the plugin as a `<feature>` tag in your Cordova-iOS
+application's project's `config.xml` file, using the `plugin.xml` file
+to inject this markup automatically, as described in Application
+Plugins:
<feature name="LocalStorage">
<param name="ios-package" value="CDVLocalStorage" />
</feature>
-The feature `name` attribute should match what you use in the JavaScript
-`exec` call's `service` parameter, and the `value` attribute should match the name of the plugin's
-Objective-C class. `<param name>` should always be i`"ios-package"`.
-If you do not follow this setup, the plugin may compile but will not be
-reachable by Cordova.
+The feature's `name` attribute should match what you specify as the
+JavaScript `exec` call's `service` parameter. The `value` attribute
+should match the name of the plugin's Objective-C class. The `<param>`
+element's `name` should always be `ios-package`. If you do not follow
+these guidelines, the plugin may compile, but Cordova may still not be
+able to access it.
## Plugin Initialization and Lifetime
One instance of a plugin object is created for the life of each
-`UIWebView`. 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.:
+`UIWebView`. Plugins are ordinarily instantiated when first referenced
+by a call from JavaScript. Otherwise they can be instantiated by
+setting a `param` named `onload` to `true` in the `config.xml` file:
<feature name="Echo">
<param name="ios-package" value="Echo" />
@@ -65,23 +69,22 @@ referenced by a call from JavaScript, unless `<param>` with an `onload`
</feature>
There is _no_ designated initializer for plugins. Instead, plugins
-should use the `pluginInitialize` method for their start-up logic.
+should use the `pluginInitialize` method for their startup logic.
-Plugins with long-running requests, background activity (e.g., playing
-media), listeners or internal state should implement the `onReset`
-method and stop or clean up those activities. This method is run when
-the `UIWebView` navigates to a new page or refreshes, which reloads
-the JavaScript.
+Plugins with long-running requests, background activity such as media
+playback, listeners, or that maintain internal state should implement
+the `onReset` method to clean up those activities. The method runs
+when the `UIWebView` navigates to a new page or refreshes, which
+reloads the JavaScript.
## Writing an iOS Cordova Plugin
-We have JavaScript fire off a plugin request to the native side. We
-have the iOS Objective-C plugin mapped properly via the `config.xml`
-file. So what does the final iOS Objective-C Plugin class look like?
-
-What gets dispatched to the plugin via JavaScript's `exec` function
-gets passed into the corresponding Plugin class's `action` method. A
-plugin method has this signature:
+A JavaScript call fires off a plugin request to the native side, and
+the corresponding iOS Objective-C plugin is mapped properly in the
+`config.xml` file, but what does the final iOS Objective-C plugin
+class look like? Whatever is dispatched to the plugin with
+JavaScript's `exec` function is passed into the corresponding plugin
+class's `action` method. A plugin method has this signature:
- (void)myMethod:(CDVInvokedUrlCommand*)command
{
@@ -96,50 +99,54 @@ plugin method has this signature:
[self.commandDelegate sendPluginResult:pluginResult callbackId:command.callbackId];
}
-1. [CDVInvokedUrlCommand.h](https://github.com/apache/cordova-ios/blob/master/CordovaLib/Classes/CDVInvokedUrlCommand.h)
-
-2. [CDVPluginResult.h](https://github.com/apache/cordova-ios/blob/master/CordovaLib/Classes/CDVPluginResult.h)
-
-3. [CDVCommandDelegate.h](https://github.com/apache/cordova-ios/blob/master/CordovaLib/Classes/CDVCommandDelegate.h)
+For more details, see
+ `[CDVInvokedUrlCommand.h](https://github.com/apache/cordova-ios/blob/master/CordovaLib/Classes/CDVInvokedUrlCommand.h)`,
+ `[CDVPluginResult.h](https://github.com/apache/cordova-ios/blob/master/CordovaLib/Classes/CDVPluginResult.h)`,
+and
+ `[CDVCommandDelegate.h](https://github.com/apache/cordova-ios/blob/master/CordovaLib/Classes/CDVCommandDelegate.h)`.
## iOS CDVPluginResult message types
-Using CDVPluginResult you can return a variety of result types back to
-your JavaScript callbacks, using class methods that look like:
+You can use `CDVPluginResult` to return a variety of result types back to
+the JavaScript callbacks, using class methods that follow this pattern:
+ (CDVPluginResult*)resultWithStatus:(CDVCommandStatus)statusOrdinal messageAs...
You can create `String`, `Int`, `Double`, `Bool`, `Array`,
-`Dictionary`, `ArrayBuffer`, and `Multipart` types. Or, don't attach
-any arguments (just send a status). Or, return an Error. You can
-even choose to not send any plugin result at all, in which case the
-callback does not fire.
+`Dictionary`, `ArrayBuffer`, and `Multipart` types. You can also leave
+out any arguments to send a status, or return an error, or even choose
+not to send any plugin result, in which case neither callback fires.
-### Notes
+Note the following for complex return values:
- * `messageAsArrayBuffer` expects `NSData*` and converts to an
- `ArrayBuffer` for your JavaScript callback (and `ArrayBuffers` sent
- to a plugin from JavaScript are converted to `NSData*`).
+- `messageAsArrayBuffer` expects `NSData*` and converts to an
+ `ArrayBuffer` in the JavaScript callback. Likewise, any
+ `ArrayBuffer` the JavaScript sends to a plugin are converted to
+ `NSData*`.
- * `messageAsMultipart` expects an `NSArray*` containing any of the
- other supported types, and sends the whole array as the `arguments`
- to your JavaScript callback.
+- `messageAsMultipart` expects an `NSArray*` containing any of the
+ other supported types, and sends the entire array as the `arguments`
+ to your JavaScript callback. This way, all of the arguments are
+ serialized or deserialized as necessary, so it is safe to return
+ `NSData*` as multipart, but not as `Array`/`Dictionary`.
- * Quirk: this is not just syntactic sugar (though it is sweet).
- This way, all of the arguments are serialized or deserialized as
- necessary. E.g., it is safe to return `NSData*` as multipart,
- but not as `Array`/`Dictionary`.
+## Echo iOS Plugin Example
-## Echo Plugin iOS Plugin
+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:
-We would add the following to the project's `config.xml` file:
+ <platform name="ios">
+ <config-file target="config.xml" parent="/*">
+ <feature name="Echo">
+ <param name="ios-package" value="Echo" />
+ </feature>
+ </config-file>
+ </platform>
- <feature name="Echo">
- <param name="ios-package" value="Echo" />
- </feature>
-Then we would add the following files (`Echo.h` and `Echo.m`) to the
-Plugins folder inside our Cordova-iOS application folder:
+Then we would add the following `Echo.h` and `Echo.m` files to the
+`Plugins` folder within the Cordova-iOS application directory:
/********* Echo.h Cordova Plugin Header *******/
@@ -174,30 +181,37 @@ Plugins folder inside our Cordova-iOS application folder:
@end
-Let's take a look at the code. At the top we have all of the necessary
-Cordova imports. Our class extends from `CDVPlugin` (very important).
-
-This plugin only supports one action, the `echo` action. First, we
-grab the echo string using the `objectAtIndex` method on our `args`,
-telling it we want to get the 0th parameter in the arguments array. We
-do a bit of parameter checking: make sure it is not `nil`, and make
-sure it is not a zero-length string.
-
-If it is, we return a `PluginResult` with an `ERROR` status. If all of
-those checks pass, then we return a `PluginResult` with an `OK`
-status, and pass in the `echo` string we received in the first place
-as a parameter.
-
-Finally, we send the result to `self.commandDelegate`, which executes
-the `exec` method's success or failure callbacks on the JavaScript
-side. If the success callback is called, it passes in the `echo`
-parameter.
+The necessary imports at the top of the file extends the class from
+`CDVPlugin`. In this case, the plugin only supports a single `echo`
+action. It obtains the echo string by calling the `objectAtIndex`
+method get the first parameter of the `arguments` array, which
+corresponds to the arguments passed in by the JavaScript `exec()`
+function.
+
+It checks the parameter to make sure it is not `nil` or an empty
+string, returning a `PluginResult` with an `ERROR` status if so. If
+the parameter passes the check, it returns a `PluginResult` with an
+`OK` status, passing in the original `echo` string. Finally, it sends
+the result to `self.commandDelegate`, which executes the `exec`
+method's success or failure callbacks on the JavaScript side. If the
+success callback is called, it passes in the `echo` parameter.
+
+## iOS Integration
+
+The `CDVPlugin` class features other methods that your plugin can
+override. For example, you can capture the `pause`, `resume`, app
+terminate and `handleOpenURL` events. See the
+[CDVPlugin.h](https://github.com/apache/cordova-ios/blob/master/CordovaLib/Classes/CDVPlugin.h)
+and
+[CDVPlugin.m](https://github.com/apache/cordova-ios/blob/master/CordovaLib/Classes/CDVPlugin.m)
+class for guidance.
## Threading
-Plugin methods are executed in the same thread as the UI. If your
-plugin requires a great deal of processing or requires a blocking
-call, you should use a background thread. For example:
+Plugin methods ordinarily execute in the same thread as the main
+interface. If your plugin requires a great deal of processing or
+requires a blocking call, you should use a background thread. For
+example:
- (void)myPluginMethod:(CDVInvokedUrlCommand*)command
{
@@ -211,29 +225,17 @@ call, you should use a background thread. For example:
}];
}
-## Advanced Plugin Functionality
-
-See other methods that you can override in:
-
-- [CDVPlugin.h](https://github.com/apache/cordova-ios/blob/master/CordovaLib/Classes/CDVPlugin.h)
-
-- [CDVPlugin.m](https://github.com/apache/cordova-ios/blob/master/CordovaLib/Classes/CDVPlugin.m)
-
-For example, you can hook into the `pause`, `resume`, app terminate and `handleOpenURL` events.
-
-## Debugging Plugins
-
-To debug the Objective-C side, you would use Xcode's built-in debugger.
-For JavaScript, on iOS 5.0 you can use
-[Weinre, an Apache Cordova Project](https://github.com/apache/cordova-weinre) or
-[iWebInspector, a third-party utility](http://www.iwebinspector.com/)
+## Debugging iOS Plugins
-For iOS 6, you would use Safari 6.0 to simply attach to your app
-running in the iOS 6 Simulator.
+To debug on the Objective-C side, you need Xcode's built-in debugger.
+For JavaScript, on iOS 5.0 you can use [Weinre, an Apache Cordova
+Project](https://github.com/apache/cordova-weinre) or [iWebInspector,
+a third-party utility](http://www.iwebinspector.com/). For iOS 6, you
+can attach Safari 6.0 to your app running within the iOS 6 Simulator.
## Common Pitfalls
-- Don't forget to add your plugin's mapping to config.xml. If you
+- Don't forget to add your plugin's mapping to `config.xml`. If you
forget, an error is logged in the Xcode console.
- Don't forget to add any hosts you connect to in the whitelist, as