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:56 UTC
[14/14] docs commit: [CB-3825] BB10 native plugin
[CB-3825] BB10 native plugin
Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/685d0750
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/685d0750
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/685d0750
Branch: refs/heads/master
Commit: 685d0750f20aa0a7fa89522ab6fc3d8cee57045e
Parents: 4e709fe
Author: Mike Sierra <ms...@adobe.com>
Authored: Wed Oct 16 12:32:24 2013 -0400
Committer: Michael Brooks <mi...@michaelbrooks.ca>
Committed: Mon Oct 21 15:13:36 2013 -0700
----------------------------------------------------------------------
docs/en/edge/guide/platforms/android/plugin.md | 2 +-
.../edge/guide/platforms/blackberry/plugin.md | 2 +-
.../edge/guide/platforms/blackberry10/plugin.md | 157 +++++++++----------
docs/en/edge/guide/platforms/ios/plugin.md | 2 +-
docs/en/edge/guide/platforms/wp8/plugin.md | 2 +-
5 files changed, 79 insertions(+), 86 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/685d0750/docs/en/edge/guide/platforms/android/plugin.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/android/plugin.md b/docs/en/edge/guide/platforms/android/plugin.md
index 7cd0eae..a496d46 100644
--- a/docs/en/edge/guide/platforms/android/plugin.md
+++ b/docs/en/edge/guide/platforms/android/plugin.md
@@ -19,7 +19,7 @@ license: Licensed to the Apache Software Foundation (ASF) under one
# Android Plugins
-The section provides details for how to implement native plugin code
+This section provides details for how to implement native plugin code
on the Android platform. Before reading this, see Application Plugins
for an overview of the plugin's structure and its common JavaScript
interface. This section continues to demonstrate the sample _echo_
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/685d0750/docs/en/edge/guide/platforms/blackberry/plugin.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/blackberry/plugin.md b/docs/en/edge/guide/platforms/blackberry/plugin.md
index a3cfec9..2e076db 100644
--- a/docs/en/edge/guide/platforms/blackberry/plugin.md
+++ b/docs/en/edge/guide/platforms/blackberry/plugin.md
@@ -19,7 +19,7 @@ license: Licensed to the Apache Software Foundation (ASF) under one
# BlackBerry Plugins
-The section provides details for how to implement native plugin code
+This section provides details for how to implement native plugin code
on the BlackBerry platform. Before reading this, see Application
Plugins for an overview of the plugin's structure and its common
JavaScript interface. This section continues to demonstrate the sample
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/685d0750/docs/en/edge/guide/platforms/blackberry10/plugin.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/blackberry10/plugin.md b/docs/en/edge/guide/platforms/blackberry10/plugin.md
index cdeb629..57185d0 100644
--- a/docs/en/edge/guide/platforms/blackberry10/plugin.md
+++ b/docs/en/edge/guide/platforms/blackberry10/plugin.md
@@ -19,51 +19,46 @@ license: Licensed to the Apache Software Foundation (ASF) under one
# BlackBerry 10 Plugins
-The section provides details for how to implement native plugin code
+This section provides details for how to implement native plugin code
on the BlackBerry 10 platform. Before reading this, see Application
Plugins for an overview of the plugin's structure and its common
JavaScript interface. This section continues to demonstrate the sample
_echo_ plugin that communicates from the Cordova webview to the native
platform and back.
-This is a continuation of the Plugin Development Guide for
-Cordova. Once you have reviewed that content, now let's look at things
-we need to have the Echo plugin for the BlackBerry 10 platform. Recall
-that the Echo plugin basically returns whatever string a user provides
-to the `window.echo` function:
+The Echo plugin basically returns whatever string the `window.echo`
+function sends from JavaScript:
window.echo = function(str, callback) {
- cordova.exec(callback, function(err) {
- callback('Nothing to echo.');
- }, "Echo", "echo", [str]);
- };
+ cordova.exec(callback, function(err) {
+ callback('Nothing to echo.');
+ }, "Echo", "echo", [str]);
+ };
-A native BlackBerry 10 plugin for Cordova contains JavaScript code and
-may also contain native code. The Echo plugin example demonstrates how
-to invoke native functionality from JavaScript. The native and
-JavaScript code communicate with each other through a framework
-provided by JNEXT. Every plugin must also include a `plugin.xml` file.
+A Cordova plugin for BlackBerry 10 contains both JavaScript and native
+code, which communicate with each other through a framework provided
+by JNEXT. Every plugin must also include a `plugin.xml` file.
-## Creating the native part of your plugin
+## Creating the native class
To create the native portion of your plugin, open the BlackBerry 10
-NDK IDE and select File > New > BlackBerry Project > Native Extension
-> BlackBerry WebWorks. Enter your desired project name / location and
-click finish.
+NDK IDE and select __File → New → BlackBerry Project →
+Native Extension → BlackBerry WebWorks__. Enter the desired
+project name and location, then press __Finish__.
The project created by the IDE contains sample code for a memory
-plugin. You may replace or modify these files to include your own
-functionality.
+plugin. You may replace or modify these files to implement your own
+functionality:
- `*name*_js.hpp`: C++ header for the JNEXT code.
- `*name*_js.cpp`: C++ code for JNEXT.
The native interface for the JNEXT extension can be viewed in the
-plugin header file located in the public directory of your project. It
-also contains constants and utility functions that can be used in your
-native code. Your plugin must be derived from JSExt which is defined
-in plugin.h. That is, you must implement the following class:
+plugin header file located in the project's public directory. It also
+features constants and utility functions available from within native
+code. The plugin must be derived from `JSExt`, which is defined in
+`plugin.h`. That is, you must implement the following class:
class JSExt
{
@@ -75,8 +70,8 @@ in plugin.h. That is, you must implement the following class:
std::string m_id;
};
-Therefore, your extension should include the plugin.h header file. In
-the Echo example, you use JSExt as follows in the echo_js.hpp file:
+The extension should include the `plugin.h` header file. In the `Echo`
+example, you use `JSExt` as follows in the `echo_js.hpp` file:
#include "../public/plugin.h"
#include <string>
@@ -97,17 +92,17 @@ the Echo example, you use JSExt as follows in the echo_js.hpp file:
#endif // ECHO_JS_H_
-The `m_id` is an attribute that contains the JNEXT id for this
-object. The id is passed to the class as an argument to the
-constructor. It is needed to trigger events on the JavaScript side
-from native. The CanDelete method is used by JNEXT to determine
-whether your native object can be deleted. The InvokeMethod function
-is called as a result from a request from JavaScript to invoke a
-method of this particular object. The only argument to this function
-is a string passed from JavaScript that this method should parse in
-order to determine which method of the native object should be
-executed. Now we implement these functions in echo_js.cpp. For the
-Echo example, we implement InvokeMethod function as follows:
+The `m_id` attribute contains the `JNEXT` id for the object, which is
+passed to the class as an argument to the constructor. It is needed
+for the native side to trigger events on the JavaScript side. The
+`CanDelete` method determines whether the native object can be
+deleted. The `InvokeMethod` function is called as a result from a
+request from JavaScript to invoke a method of this particular
+object. The only argument to this function is a string passed from
+JavaScript that this method parses to determine which of the native
+object's methods should execute. These methods are implemented in
+`echo_js.cpp`. Here is the `InvokeMethod` function for the `Echo`
+example:
string Echo::InvokeMethod(const string& command) {
@@ -124,16 +119,16 @@ Echo example, we implement InvokeMethod function as follows:
}
}
-Your native plugin must also implement the following callback
+The native plugin must also implement the following callback
functions:
- `extern char* onGetObjList( void );`
- `extern JSExt* onCreateObject( const string& strClassName, const string& strObjId );`
-The `onGetObjList` function returns a comma separated list of classes
+The `onGetObjList` function returns a comma-separated list of classes
supported by JNEXT. JNEXT uses this function to determine the set of
-classes that JNEXT can instantiate. In our Echo plugin, we have the
+classes that JNEXT can instantiate. The `Echo` plugin implements the
following in `echo_js.cpp`:
char* onGetObjList() {
@@ -141,12 +136,12 @@ following in `echo_js.cpp`:
return name;
}
-The `onCreateObject ` function takes two parameters. The first
-parameter is the name of the class requested to be created from the
-JavaScript side. Valid names are those that are returned in
-`onGetObjList`. The second parameter is the unique object id for the
-class. This method returns a pointer to the created plugin object. In
-our Echo plugin, we have the following in `echo_js.cpp`:
+The `onCreateObject ` function takes two parameters. The first is the
+name of the requested class to be created from the JavaScript side,
+with valid names as those returned in `onGetObjList`. The second
+parameter is the class's unique object id. This method returns a
+pointer to the created plugin object. The `Echo` plugin implements the
+following in `echo_js.cpp`:
JSExt* onCreateObject(const string& className, const string& id) {
if (className == "Echo") {
@@ -155,12 +150,12 @@ our Echo plugin, we have the following in `echo_js.cpp`:
return NULL;
}
-##Creating the JavaScript part of your plugin
+## Creating the plugin's JavaScript
-The JavaScript portion of your plugin must contain the following files:
+The plugin must contain the following JavaScript files:
- `client.js`: This is considered the client side and contains the API
- that a Cordova application can call. The API in `client.js` calls
+ available to a Cordova application. The API in `client.js` calls
makes calls to `index.js`. The API in `client.js` also connects
callback functions to the events that fire the callbacks.
@@ -170,9 +165,9 @@ The JavaScript portion of your plugin must contain the following files:
communicate with the native side.
The client and server side (`client.js` and `index.js`) interacts
-through the `Cordova.exec `function. So, in `client.js` you invoke the
-`exec` function and provide the necessary arguments. In the Echo
-plugin, we have the following in the `client.js` file:
+through the `Cordova.exec` function. The `client.js` needs to invoke
+the `exec` function and provide the necessary arguments. The `Echo`
+plugin implements the following in the `client.js` file:
var service = "org.apache.cordova.blackberry.echo",
exec = cordova.require("cordova/exec");
@@ -183,34 +178,34 @@ plugin, we have the following in the `client.js` file:
}
};
-Now, `index.js` interacts with the native side using JNEXT. So you
-attach a constructor function named Echo to JNEXT. Within the
-constructor you perform the following key operations using the init
-function:
+The `index.js` component uses JNEXT to interact with the native
+side. Attaching a constructor function named `Echo` to JNEXT allows
+you to perform the following key operations using the `init` function:
- Specify the required module exported by the native side. The name of
the required module must match the name of a shared library file
- (.so file).
+ (`.so` file):
JNEXT.require("libecho")
- Create an object by using an acquired module and save the ID that's
- returned by the call. self.m_id =
- JNEXT.createObject("libecho.Echo"); When your application calls the
- echo function in `client.js`, that call in turn calls the echo
- function in `index.js`, where the PluginResult object sends a
- response (data) back to `client.js`. Since the args argument passed
- into the functions was converted by JSON.stringfy() and encoded as a
- URIcomponent, you must call the following:
+ returned by the call:
+
+ self.m_id = JNEXT.createObject("libecho.Echo");
+
+ When the application calls the `echo` function in `client.js`, that
+ call in turn calls the `echo` function in `index.js`, where the
+ `PluginResult` object sends data as a response back to `client.js`.
+ Since the `args` argument passed into the functions was converted by
+ `JSON.stringfy()` and encoded as a `URIcomponent`, you must call the
+ following:
data = JSON.parse(decodeURIComponent(args.data));
-You can now send the data back. Let’s put it all together:
+You can now send the data back, as in the following:
module.exports = {
-
echo: function (success, fail, args, env) {
-
var result = new PluginResult(args, env),
data = JSON.parse(decodeURIComponent(args.data)),
response = echo.getInstance().echo(data);
@@ -218,15 +213,14 @@ You can now send the data back. Let’s put it all together:
}
};
-## Architecture of the plugin
+## Plugin Architecture
-You can place the artifacts of the plugin, which includes the
-`plugin.xml` file, the source files (JavaScript, C++), and the binary
-files (`.so`) within any directory structure, as long as you correctly
-specify the file locations in the `plugin.xml` file. A typical
-structure looks like this:
+You can place the plugin's artifacts, including the `plugin.xml` file,
+the JavaScript and C++ source files, and the `.so` binary files within
+any directory structure, as long as you correctly specify the file
+locations in the `plugin.xml` file. Here is a typical structure:
-***your_project_directory*** (>plugin.xml)
+***project_directory*** (>plugin.xml)
- **www** (>client.js)
- **src**
@@ -234,16 +228,15 @@ structure looks like this:
- **device** (>*binary file* *.so)
- **simulator** (>*binary file* *.so)
-(The list shows the hierarchical relationship among the top-level
-directories. The parenthesis shows the contents of a given directory. All
+The list shows the hierarchical relationship among the top-level
+folders. The parenthesis shows the contents of a given directory. All
directory names appear in bold text. File names are preceded by the `>`
-sign.)
+sign.
-## Contents of the `plugin.xml` file
+## The `plugin.xml` file
-The `plugin.xml` file contains the namespace of the extension and other
-metadata. Define the namespace and specify other metadata for the Echo
-plugin as follows:
+The `plugin.xml` file contains the extension's namespace and other
+metadata. Set up the `Echo` plugin as follows:
<plugin xmlns="http://www.phonegap.com/ns/plugins/1.0"
id="org.apache.cordova.blackberry.echo"
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/685d0750/docs/en/edge/guide/platforms/ios/plugin.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/ios/plugin.md b/docs/en/edge/guide/platforms/ios/plugin.md
index 725f6dd..9e55127 100644
--- a/docs/en/edge/guide/platforms/ios/plugin.md
+++ b/docs/en/edge/guide/platforms/ios/plugin.md
@@ -19,7 +19,7 @@ license: Licensed to the Apache Software Foundation (ASF) under one
# iOS Plugins
-The section provides details for how to implement native plugin code
+This section provides details for how to implement native plugin code
on the iOS platform. Before reading this, see Application Plugins for
an overview of the plugin's structure and its common JavaScript
interface. This section continues to demonstrate the sample _echo_
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/685d0750/docs/en/edge/guide/platforms/wp8/plugin.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/wp8/plugin.md b/docs/en/edge/guide/platforms/wp8/plugin.md
index 34f1bab..194f682 100644
--- a/docs/en/edge/guide/platforms/wp8/plugin.md
+++ b/docs/en/edge/guide/platforms/wp8/plugin.md
@@ -19,7 +19,7 @@ license: Licensed to the Apache Software Foundation (ASF) under one
# Windows Phone Plugins
-The section provides details for how to implement native plugin code
+This section provides details for how to implement native plugin code
on the Windows Phone platform. Before reading this, see Application
Plugins for an overview of the plugin's structure and its common
JavaScript interface. This section continues to demonstrate the sample