[CB-3827] new 'hybrid' tree contains webview & plugins exposition
Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/96526bf2 Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/96526bf2 Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/96526bf2 Branch: refs/heads/3.0.x Commit: 96526bf2b5ca380f1910fe1d829860ddb2b22eea Parents: f0ec003 Author: Mike Sierra <[email protected]> Authored: Thu Jul 18 16:26:36 2013 -0400 Committer: Michael Brooks <[email protected]> Committed: Thu Jul 18 14:05:24 2013 -0700 ---------------------------------------------------------------------- docs/en/edge/guide/hybrid/plugins/index.md | 120 +++++++++++++++++++++++ docs/en/edge/guide/hybrid/webviews/index.md | 26 +++++ docs/en/edge/guide/plugins/index.md | 120 ----------------------- docs/en/edge/guide/webviews/index.md | 26 ----- 4 files changed, 146 insertions(+), 146 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/96526bf2/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 new file mode 100644 index 0000000..64896fd --- /dev/null +++ b/docs/en/edge/guide/hybrid/plugins/index.md @@ -0,0 +1,120 @@ +--- +license: Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + 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 + + 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 + specific language governing permissions and limitations + under the License. +--- + +# 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: + +1. `function(winParam) {}` - Success function callback. Assuming your + `exec` call completes successfully, this function is 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 is invoked (optionally + with an error parameter). +3. `"service"` - The service name to call into on the native side. This + is mapped to a native class, about which more information is + available in the native guides listed 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. + The native guides listed below provide details. +5. `[/* arguments */]` - Arguments to pass 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. + +## 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 + +## Native + +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. + +- Android Plugins +- BlackBerry Plugins +- BlackBerry 10 Plugins +- iOS Plugins +- Windows Phone Plugins + +The Tizen platform currently does not support plugins. http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/96526bf2/docs/en/edge/guide/hybrid/webviews/index.md ---------------------------------------------------------------------- diff --git a/docs/en/edge/guide/hybrid/webviews/index.md b/docs/en/edge/guide/hybrid/webviews/index.md new file mode 100644 index 0000000..937db59 --- /dev/null +++ b/docs/en/edge/guide/hybrid/webviews/index.md @@ -0,0 +1,26 @@ +--- +license: Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + 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 + + 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 + specific language governing permissions and limitations + under the License. +--- + +# Embedding WebViews + +> Implement the Cordova WebView in your own project. + +- Android WebViews +- iOS WebViews + http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/96526bf2/docs/en/edge/guide/plugins/index.md ---------------------------------------------------------------------- diff --git a/docs/en/edge/guide/plugins/index.md b/docs/en/edge/guide/plugins/index.md deleted file mode 100644 index 64896fd..0000000 --- a/docs/en/edge/guide/plugins/index.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -license: Licensed to the Apache Software Foundation (ASF) under one - or more contributor license agreements. See the NOTICE file - distributed with this work for additional information - 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 - - 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 - specific language governing permissions and limitations - under the License. ---- - -# 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: - -1. `function(winParam) {}` - Success function callback. Assuming your - `exec` call completes successfully, this function is 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 is invoked (optionally - with an error parameter). -3. `"service"` - The service name to call into on the native side. This - is mapped to a native class, about which more information is - available in the native guides listed 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. - The native guides listed below provide details. -5. `[/* arguments */]` - Arguments to pass 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. - -## 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 - -## Native - -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. - -- Android Plugins -- BlackBerry Plugins -- BlackBerry 10 Plugins -- iOS Plugins -- Windows Phone Plugins - -The Tizen platform currently does not support plugins. http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/96526bf2/docs/en/edge/guide/webviews/index.md ---------------------------------------------------------------------- diff --git a/docs/en/edge/guide/webviews/index.md b/docs/en/edge/guide/webviews/index.md deleted file mode 100644 index 937db59..0000000 --- a/docs/en/edge/guide/webviews/index.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -license: Licensed to the Apache Software Foundation (ASF) under one - or more contributor license agreements. See the NOTICE file - distributed with this work for additional information - 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 - - 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 - specific language governing permissions and limitations - under the License. ---- - -# Embedding WebViews - -> Implement the Cordova WebView in your own project. - -- Android WebViews -- iOS WebViews -
