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:45 UTC
[03/14] docs commit: [CB-3825] boilerplate & code indent in platform
plugin guides
[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