cordova-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mwbro...@apache.org
Subject [03/14] docs commit: [CB-3825] boilerplate & code indent in platform plugin guides
Date Mon, 21 Oct 2013 22:13:45 GMT
[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 <msierra@adobe.com>
Authored: Mon Oct 7 13:20:03 2013 -0400
Committer: Michael Brooks <michael@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


Mime
View raw message