cordova-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mwbro...@apache.org
Subject [01/14] docs commit: [CB-3825] improve plugins section
Date Mon, 21 Oct 2013 22:13:43 GMT
Updated Branches:
  refs/heads/master 25e4b9e31 -> 685d0750f


[CB-3825] improve plugins section


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

Branch: refs/heads/master
Commit: 52db02fdbbe720839303d75ae44b6695f3fdc6c1
Parents: 25e4b9e
Author: Mike Sierra <msierra@adobe.com>
Authored: Mon Oct 7 10:38:42 2013 -0400
Committer: Michael Brooks <michael@michaelbrooks.ca>
Committed: Mon Oct 21 15:08:02 2013 -0700

----------------------------------------------------------------------
 docs/en/edge/guide/hybrid/plugins/index.md | 157 ++++++++++++------------
 1 file changed, 80 insertions(+), 77 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/52db02fd/docs/en/edge/guide/hybrid/plugins/index.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/hybrid/plugins/index.md b/docs/en/edge/guide/hybrid/plugins/index.md
index cf720d7..613aacd 100644
--- a/docs/en/edge/guide/hybrid/plugins/index.md
+++ b/docs/en/edge/guide/hybrid/plugins/index.md
@@ -19,59 +19,66 @@ license: Licensed to the Apache Software Foundation (ASF) under one
 
 # Plugin Development Guide
 
-A Cordova plugin bridges a bit of functionality between the WebView
-powering a Cordova application and the native platform the Cordova
-application is running on. Plugins are composed of a single JavaScript
-interface used across all platforms, and native implementations
-following platform-specific Plugin interfaces that the JavaScript
-calls into. All of the core Cordova APIs are implemented using this
-architecture.
-
-This guide steps the process of writing a simple Echo Plugin that
-passes a string from JavaScript and sends it into the native
-environment for the supported platforms. The native code then returns
-the same string back to the callbacks inside the plugin's JavaScript.
-
-This guide provides enough overview on which you can build to write
-more complex plugins.
-
-## JavaScript
-
-The entry point for any plugin is JavaScript. The reason developers use
-Cordova is so they can use and write JavaScript, not Objective-C,
-not Java, not C#. The JavaScript interface for your plugin is the
-front-facing and arguably most important part of your Cordova plugin.
-
-You can structure your plugin's JavaScript however you like. The one
-thing you _must_ use to communicate between the Cordova JavaScript
-and native environments is the `cordova.exec` function. Here is an example:
-
-        cordova.exec(function(winParam) {}, function(error) {}, "service",
-                     "action", ["firstArgument", "secondArgument", 42,
-                     false]);
-
-The parameters are detailed below:
-
-* `function(winParam) {}`: Success function callback. Assuming your
-  `exec` call completes successfully, this function is invoked
-  (optionally with any parameters you pass back to it).
-
-* `function(error) {}`: Error function callback. If the operation does
-  not complete successfully, this function is invoked (optionally with
-  an error parameter).
-
-* `"service"`: The service name to call into on the native side. This
-  is mapped to a native class, about which more information is
+A _plugin_ is a bit of injected code that allows the webview within
+which your app renders to communicate with the native platform on
+which it runs.  Plugins thus provide access to device and platform
+functionality that is ordinarily unavailable to web-based apps.  All
+the main Cordova API features are implemented as plugins, and many
+others are available that enable features such as bar code scanners,
+NFC communication, or to tailor calendar interfaces.
+
+This section steps through how to write a simple _echo_ plugin that
+passes a string from JavaScript to the native platform and back.  You
+can build far more complex plugins based on this simple model.  This
+section discusses the outward-facing JavaScript interface. For each
+corresponding native interface, see the list at the end of this
+section.  For detailed information on the plugin format, see the
+Plugin Specification.  For information on how to add existing plugins
+to an app, see The Command-line Interface.
+
+<!-- ## File and Directory Structure -->
+
+## The JavaScript Interface
+
+Plugins comprise a single JavaScript interface along with
+corresponding native code libraries for each supported platform.  The
+JavaScript provides the provides the front-facing interface, making it
+perhaps the most important part of the plugin.
+
+You can structure your plugin's JavaScript however you like, but you
+need to call `cordova.exec` to communicate with the native platform,
+as in the following example:
+
+        cordova.exec(function(winParam) {}, 
+                     function(error) {}, 
+                     "service",
+                     "action", 
+                     ["firstArgument", "secondArgument", 42, false]);
+
+The parameters work as follows:
+
+- `function(winParam) {}`: A success callback function. Assuming your
+  `exec` call completes successfully, this function executes along
+  with any parameters you pass to it.
+
+- `function(error) {}`: An error callback function. If the operation
+  does not complete successfully, this function executes with an
+  optional error parameter.
+
+- `"service"`: The service name to call on the native side. This
+  corresponds to a native class, for which more information is
   available in the native guides listed below.
 
-* `"action"`: The action name to call into. This is picked up by the
-  native class receiving the `exec` call, and, depending on the
-  platform, essentially maps to a class's method.  The native guides
-  listed below provide details.
+- `"action"`: The action name to call on the native side. This
+  generally corresponds to the native class method. See the native
+  guides listed below.
 
-* `[/* arguments */]`: Arguments to pass into the native environment.
+- `[/* arguments */]`: An array of arguments to pass into the native
+  environment.
 
-### Echo Plugin JavaScript Example
+## Sample JavaScript
+
+This example shows how to specify the plugin's JavaScript interface:
 
         window.echo = function(str, callback) {
             cordova.exec(callback, function(err) {
@@ -79,49 +86,45 @@ The parameters are detailed below:
             }, "Echo", "echo", [str]);
         };
 
-Let's dive into this. The plugin attaches itself to `window`,
-specifically to the `echo` function. Plugin users would then use it as
-follows:
+In this example, the plugin attaches itself to the `window` object as
+the `echo` function, which plugin users would call as follows:
 
         window.echo("echome", function(echoValue) {
             alert(echoValue == "echome"); // should alert true.
         });
 
-First, let's take a look at the last three arguments to the `exec`
-function. We will be calling the `Echo` "service", requesting the `echo`
-"action", and passing an array of arguments containing the echo string,
-which is the first parameter into the `window.echo` function.
+Look at the last three arguments to the `cordova.exec` function. The
+first calls the `Echo` _service_. The second requests the `echo`
+_action_. The third is an array of arguments containing the echo
+string, which is the `window.echo` function's the first parameter.
 
 The success callback passed into `exec` is simply a reference to the
-callback function that `window.echo` takes. We do a bit more for the
-error callback: if the native side fires off the error callback, we
-simply invoke the success callback and pass into it a "default"
-string.
-
-## Plugin Specification
-
-Cordova has a plugin specification available to enable automated
-installation of the plugin for Android, iOS, BlackBerry 10 and Windows
-Phone platforms. By structuring your plugin in a particular way and
-adding a `plugin.xml` manifest file, you can enable users to install
-your plugin via the command-line tooling.
-
-- Plugin Specification
+callback function `window.echo` takes. If the native platform fires
+the error callback, it simply calls the success callback and passes it
+a default string.
 
-## Native
+## Native Interfaces
 
 Once you define JavaScript for your plugin, you need to complement it
-with at least one native implementation. Details to do so for each
-platform are listed below.  These guides continue to build on the
-simple Echo Plugin example discussed above.
+with at least one native implementation. Details for each platform are
+listed below, and each builds on the simple Echo Plugin example above:
 
 - Android Plugins
+- iOS Plugins
 - BlackBerry Plugins
 - BlackBerry 10 Plugins
-- iOS Plugins
 - Windows Phone Plugins
 
-The Tizen platform currently does not support plugins.
+The Tizen platform does not support plugins.
+
+## Plugin Specification
+
+Cordova's plugin specification allows plugins to be installed
+automatically for Android, iOS, BlackBerry 10 and Windows Phone
+platforms. If you specify a `plugin.xml` manifest file and follow the
+specification's conventions for filename and directory structure,
+users can install your plugin using platform-specific command-line
+tooling.  See Plugin Specification for details.
 
 ## Publishing plugins
 
@@ -134,4 +137,4 @@ To publish a plugin you need to use the plugman tool and go through the
followin
     
 That is it!
 
-Other registry-based commands are available and `plugman --help` will give you a list of
what commands are available and how to use them.  
+Other registry-based commands are available and `plugman --help` will give you a list of
what commands are available and how to use them.


Mime
View raw message