incubator-callback-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From fil...@apache.org
Subject docs commit: [CB-862] Providing top-level plugin development guidance, specifically with respect to JavaScript.
Date Wed, 18 Jul 2012 21:30:16 GMT
Updated Branches:
  refs/heads/master dd39a3fbf -> 5d9c35cd0


[CB-862] Providing top-level plugin development guidance, specifically with respect to JavaScript.


Project: http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/commit/5d9c35cd
Tree: http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/tree/5d9c35cd
Diff: http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/diff/5d9c35cd

Branch: refs/heads/master
Commit: 5d9c35cd05583d68db05486f9d58f1460aca5857
Parents: dd39a3f
Author: Fil Maj <maj.fil@gmail.com>
Authored: Wed Jul 18 14:32:51 2012 -0700
Committer: Fil Maj <maj.fil@gmail.com>
Committed: Wed Jul 18 14:32:51 2012 -0700

----------------------------------------------------------------------
 .../edge/guide/plugin-development/android/index.md |   43 ++++----
 docs/en/edge/guide/plugin-development/index.md     |   87 ++++++++++++++-
 2 files changed, 106 insertions(+), 24 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/5d9c35cd/docs/en/edge/guide/plugin-development/android/index.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/plugin-development/android/index.md b/docs/en/edge/guide/plugin-development/android/index.md
index 0202a74..5734e86 100644
--- a/docs/en/edge/guide/plugin-development/android/index.md
+++ b/docs/en/edge/guide/plugin-development/android/index.md
@@ -1,18 +1,18 @@
 ---
 license: Licensed to the Apache Software Foundation (ASF) under one
-         or more contributor license agreements.  See the NOTICE file
+         or more contributor license agreements. See the NOTICE file
          distributed with this work for additional information
-         regarding copyright ownership.  The ASF licenses this file
+         regarding copyright ownership. The ASF licenses this file
          to you under the Apache License, Version 2.0 (the
          "License"); you may not use this file except in compliance
-         with the License.  You may obtain a copy of the License at
+         with the License. You may obtain a copy of the License at
 
            http://www.apache.org/licenses/LICENSE-2.0
 
          Unless required by applicable law or agreed to in writing,
          software distributed under the License is distributed on an
          "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-         KIND, either express or implied.  See the License for the
+         KIND, either express or implied. See the License for the
          specific language governing permissions and limitations
          under the License.
 ---
@@ -20,25 +20,24 @@ license: Licensed to the Apache Software Foundation (ASF) under one
 Developing a Plugin on Android
 ==============================
 
-Writing a plugin requires an understanding of the architecture of Cordova-Android.  Cordova
consists
-of a WebView with hooks attached to it.  These plugins are represented as sub-classes in
the config.xml
+Writing a plugin requires an understanding of the architecture of Cordova-Android. Cordova
consists
+of a WebView with hooks attached to it. These plugins are represented as sub-classes in the
config.xml
 file.
 
-A plugin will consist of at least a single Java class that extends the Plugin object.  This
object MUST
-have a method called execute that must return a pluginresult.  In addition to this, there
is a best practice that
+A plugin will consist of at least a single Java class that extends the `Plugin` class. A
plugin **must**
+have a method called `execute` that must return a `PluginResult` object. In addition to this,
there is a best practice that
 the plugin should handle pause and resume events, and should handle message passing between
plugins.
 
 Writing the Java portion:
 --------------------------------
-Assuming that you know how Javascript plugins work, you must use the exec method as follows:
-
-{{
-exec(<successFunction>, <failFunction>, <service>, <action>, [<args>]);
-}}
+Assuming that you know how the JavaScript portion of plugins work, you must use the `exec`
method as follows:
 
+    exec(<successFunction>, <failFunction>, <service>, <action>,
[<args>]);
 
-This will send the message to Java to start work on your plugin.  Then you must handle what
-comes into the plugin in the execute command.  Most execute commands look like the following:
+This will marshall 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. Then you must handle what
+comes into the plugin in the execute command. Most execute commands look like the following:
 
 {{
     public PluginResult execute(String action, JSONArray args, String callbackId) {
@@ -86,7 +85,7 @@ comes into the plugin in the execute command.  Most execute commands look
like t
     }
 }}
 
-When catching exceptions and returning errors, it's important that the error we return to
Javascript match the Java exception as much as possible, otherwise the developer won't know
what
+When catching exceptions and returning errors, it's important that the error we return to
JavaScript match the Java exception as much as possible, otherwise the developer won't know
what
 is going on with the device.
 
 Adding your plugin to a project:
@@ -96,19 +95,19 @@ Whether you distribute your plugin as Java file, or whether it's in a
JAR of its
     <plugin name="<service_name>" value="<full_name_including_namespace>"/>
 }}
 
-The service name will be what you use in exec to call the plugin, and the value will be the
full name of the Java class including the namespace.  Withotu this added, the plugin may compile
but 
+The service name will be what you use in exec to call the plugin, and the value will be the
full name of the Java class including the namespace. Withotu this added, the plugin may compile
but 
 will not be reachable by Cordova.
 
 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 Dev Tools is known
to allow source code attachment to JAR dependencies, this is not fully supported at this time.
+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 Dev Tools is known
to allow source code attachment to JAR dependencies, this is not fully supported at this time.
 
 Common Pitfalls:
 -------------------------------
-* Plugins have access to a CordovaInterface object.  This object has access to the activity
that is running the application, which of course, is the context required to launch
-a new 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
+* Plugins have access to a CordovaInterface object. This object has access to the activity
that is running the application, which of course, is the context required to launch
+a new intent. The CordovaInterface allows plugins to  start an activity for a result, and
to set the callback plugin for when the intent comes back to the application. This is important,
since the
 intents system is how Android communicates between processes.
 
-* Plugins do not have direct access to the Context as they have in the past.  ctx id deprecated,
and will be removed six months after 2.0 is released.  All the methods that ctx have 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. ctx id deprecated,
and will be removed six months after 2.0 is released. All the methods that ctx have exist
on the context, so both getContext() and getActivity() are capable of returning the proper
object required.
 
-* Avoid calling Javascript using webView.loadUrl().  The reason we have a callback server
is to allow Javascript execution to be thread-safe, and loadUrl explicitly interrupts the
UI thread, and can affect the usability of your plugin.
+* Avoid calling JavaScript using webView.loadUrl(). The reason we have a callback server
is to allow JavaScript execution to be thread-safe, and loadUrl explicitly interrupts the
UI thread, and can affect the usability of your plugin.

http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/5d9c35cd/docs/en/edge/guide/plugin-development/index.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/plugin-development/index.md b/docs/en/edge/guide/plugin-development/index.md
index 016abd2..ef1cfa4 100644
--- a/docs/en/edge/guide/plugin-development/index.md
+++ b/docs/en/edge/guide/plugin-development/index.md
@@ -17,8 +17,91 @@ license: Licensed to the Apache Software Foundation (ASF) under one
          under the License.
 ---
 
-Plugin Development Guides
-=========================
+# 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 will
+call into. It should be noted that all of the core Cordova APIs are
+implemented using this exact architecture.
+
+This guide will go through each step necessary to write a simple Echo
+Plugin. The Echo Plugin will pass a string from JavaScript and send it
+into the native environment for the supported platforms. The native code
+will then return the same string back into the callbacks inside the
+plugin's JavaScript.
+
+This guide should give anyone the necessary overview and level of
+detail 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 explained in more detail:
+
+1. `function(winParam) {}` - Success function callback. Assuming your
+   `exec` call completes successfully, this function will be invoked
+    (optionally with any parameters you pass back to it)
+2. `function(error) {}` - Error function callback. If the operation does
+   not complete successfully, this function will be invoked (optionally
+   with an error parameter)
+3. `"service"` - The service name to call into on the native side. This
+   will be mapped to a native class. More on this in the native guides
+   below
+4. `"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. For more detail
+   please check out the native guides located at the end of this article.
+5. `[/* arguments */]` - Arguments to get passed into the native
+   environment
+
+### Echo Plugin JavaScript Example
+
+    window.echo = function(str, callback) {
+        cordova.exec(callback, function(err) {
+            callback('Nothing to echo.');
+        }, "Echo", "echo", [str]);
+    };
+
+Let's dive into this. The plugin attaches itself to `window`,
+specifically to the `echo` function. Plugin users would then use it as
+follows:
+
+    window.echo("echome", function(echoValue) {
+        alert(echoValue == "echome"); // should alert true.
+    });
+
+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.
+
+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.
+
+## Native
+
+Once you have defined a JavaScript for your plugin, you need to
+complement it with at least one native implementation. Below are
+specific guides for each platform Cordova supports. The below guides
+will continue on building the simple Echo Plugin example we started in
+this guide.
 
 - Developing a Plugin on Android
 - Developing a Plugin on Bada


Mime
View raw message