You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by pu...@apache.org on 2020/12/02 08:30:24 UTC
[cordova-docs] branch master updated: Improve Plugin documentation
(#971)
This is an automated email from the ASF dual-hosted git repository.
purplecabbage pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/cordova-docs.git
The following commit(s) were added to refs/heads/master by this push:
new e327c0a Improve Plugin documentation (#971)
e327c0a is described below
commit e327c0a678e809d636549ab00fe7fba101e4ca14
Author: Jan Piotrowski <pi...@gmail.com>
AuthorDate: Wed Dec 2 09:30:16 2020 +0100
Improve Plugin documentation (#971)
* fix lots of tiny things
- fix git repo url for `cordova plugin add` description
- add npm package name for `cordova plugin add` description
- change explanation of plugin.xml content to list
- fix description of plugin.id
- add several internal links
- move "Validating a Plugin using Plugman" to a better location
- fix formatting
* Update plugin.md
* Testing a Plugin during development (#975)
* clarify files, add headline for exec proxy
* alternative syntax for exec proxy
---
www/docs/en/dev/guide/hybrid/plugins/index.md | 91 ++++++++++++++---------
www/docs/en/dev/guide/platforms/android/plugin.md | 45 +++++------
www/docs/en/dev/guide/platforms/ios/plugin.md | 5 +-
www/docs/en/dev/guide/platforms/windows/plugin.md | 32 ++++++--
4 files changed, 109 insertions(+), 64 deletions(-)
diff --git a/www/docs/en/dev/guide/hybrid/plugins/index.md b/www/docs/en/dev/guide/hybrid/plugins/index.md
index d416dd9..070b079 100644
--- a/www/docs/en/dev/guide/hybrid/plugins/index.md
+++ b/www/docs/en/dev/guide/hybrid/plugins/index.md
@@ -52,16 +52,24 @@ for guidance.
## Building a Plugin
Application developers use the CLI's [plugin add command][cdv_plugin] to add a plugin to a project. The
-argument to that command is the URL for a _git_ repository containing
-the plugin code. This example implements Cordova's Device API:
+command takes the URL for a _git_ repository containing
+the plugin code as an argument. This example implements Cordova's Device API:
```bash
-cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-device.git
+cordova plugin add https://github.com/apache/cordova-plugin-device
+```
+
+If the plugin is published to _npm_, the command can also receive the package name as the argument:
+
+```bash
+cordova plugin add cordova-plugin-device
```
The plugin repository must feature a top-level `plugin.xml` manifest
file. There are many ways to configure this file, details for which
-are available in the [Plugin Specification](../../../plugin_ref/spec.html). This abbreviated version of the `Device` plugin provides a simple example to use as a model:
+are available in the [Plugin Specification](../../../plugin_ref/spec.html).
+
+This abbreviated version of the `Device` plugin provides a simple example to use as a model:
```xml
<?xml version="1.0" encoding="UTF-8"?>
@@ -86,39 +94,17 @@ are available in the [Plugin Specification](../../../plugin_ref/spec.html). This
</plugin>
```
-The top-level `plugin` tag's `id` attribute uses the same
-reverse domain format to identify the plugin package as the apps
-they're added to. The `js-module` tag specifies the path to the common
-JavaScript interface. The `platform` tag specifies a corresponding
-set of native code, for the `ios` platform in this case. The
-`config-file` tag encapsulates a `feature` tag that is injected into
+- The top-level `plugin` tag's `id` attribute usually follows the `cordova-plugin-{plugin name}` schema and matches the plugin's npm package name.
+- The `js-module` tag specifies the path to the [common
+JavaScript interface](#the-javascript-interface).
+- The `platform` tag specifies a corresponding
+set of native code, for the `ios` platform in this case.
+- The `config-file` tag encapsulates a `feature` tag that is injected into
the platform-specific `config.xml` file to make the platform aware of
-the additional code library. The `header-file` and `source-file` tags
+the additional code library.
+- The `header-file` and `source-file` tags
specify the path to the library's component files.
-## Validating a Plugin using Plugman
-
-You can use the `plugman` utility to check whether the plugin installs
-correctly for each platform. Install `plugman` with the following
-[node](http://nodejs.org/) command:
-
-```bash
-npm install -g plugman
-```
-
-You need a valid app source directory, such as the top-level `www`
-directory included in a default CLI-generated project, as described in the
-[Create your first app](../../cli/index.html) guide.
-
-Then run a command such as the following to test whether iOS
-dependencies load properly:
-
-```bash
-plugman install --platform ios --project /path/to/my/project/www --plugin /path/to/my/plugin
-```
-
-For details on `plugman` options, see [Using Plugman to Manage Plugins](../../../plugin_ref/plugman.html). For information on how to actually _debug_ plugins, see each platform's native interface listed at the bottom of this page.
-
## The JavaScript Interface
The JavaScript interface provides the front-facing interface, making it perhaps
@@ -199,6 +185,41 @@ listed below, and each builds on the simple Echo Plugin example above:
- [iOS Plugins](../../platforms/ios/plugin.html)
- [Windows Plugins](../../platforms/windows/plugin.html)
+## Testing a Plugin during development
+
+The simplest way to manually test a plugin during development is to create a
+Cordova app as usual and add the plugin with the `--link` option:
+
+```bash
+cordova plugin add ../path/to/my/plugin/relative/to/project --link
+```
+
+This creates a symbolic link instead of copying the plugin files, which enables you
+to work on your plugin and then simply rebuild the app to use your changes.
+
+## Validating a Plugin using Plugman
+
+You can use the `plugman` utility to check whether the plugin installs
+correctly for each platform. Install `plugman` with the following
+[node](http://nodejs.org/) command:
+
+```bash
+npm install -g plugman
+```
+
+You need a valid app source directory, such as the top-level `www`
+directory included in a default CLI-generated project, as described in the
+[Create your first app](../../cli/index.html) guide.
+
+Then run a command such as the following to test whether iOS
+dependencies load properly:
+
+```bash
+plugman install --platform ios --project /path/to/my/project/www --plugin /path/to/my/plugin
+```
+
+For details on `plugman` options, see [Using Plugman to Manage Plugins](../../../plugin_ref/plugman.html). For information on how to actually _debug_ plugins, see [each platform's native interface listed above](#native-interfaces).
+
## Publishing Plugins
You can publish your plugin to any `npmjs`-based registry, but the recommended one is the [npm registry](https://www.npmjs.com). Other developers can install your plugin automatically using either `plugman` or the Cordova CLI.
@@ -230,7 +251,7 @@ For more details on npm usage, refer to [Publishing npm Packages](https://docs.n
To surface the plugin in [Cordova Plugin Search](/plugins/), add the `ecosystem:cordova` keyword to the `package.json` file of your plugin before publishing.
-To indicate support for a particular platform, add a keyword in the format `**cordova-<platformName>**` to the list of keywords in package.json.
+To indicate support for a particular platform, add a keyword in the format `cordova-<platformName>` to the list of keywords in `package.json`.
Plugman's `createpackagejson` command does this for you, but if you did not use it to generate your `package.json`, you should manually edit it as shown below.
For example, for a plugin that supports Android, iOS & Windows, the keywords in `package.json` should include:
diff --git a/www/docs/en/dev/guide/platforms/android/plugin.md b/www/docs/en/dev/guide/platforms/android/plugin.md
index a6fd71c..3c1c14f 100644
--- a/www/docs/en/dev/guide/platforms/android/plugin.md
+++ b/www/docs/en/dev/guide/platforms/android/plugin.md
@@ -24,15 +24,18 @@ toc_title: Android
# Android Plugin Development Guide
This section provides details for how to implement native plugin code
-on the Android platform. Before reading this, see the [Plugin Development Guide][plugin-dev]
+on the Android platform.
+
+Before reading this, see the [Plugin Development Guide][plugin-dev]
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. For another sample, see also the comments in
[CordovaPlugin.java][cordova-plugin].
-Android plugins are based on Cordova-Android, which is built from an
-Android WebView with a native bridge. The native portion of an Android plugin
+Android plugins are based on Cordova-Android,
+which is built from an Android WebView with a native bridge.
+The native portion of an Android plugin
consists of at least one Java class that extends the `CordovaPlugin` class and
overrides one of its `execute` methods.
@@ -225,24 +228,24 @@ import org.json.JSONObject;
*/
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.");
+ }
}
}
-}
```
The necessary imports at the top of the file extends the class from
@@ -371,9 +374,9 @@ public void onRequestPermissionResult(int requestCode, String[] permissions,
}
```
-The switch statement above would return from the prompt and, depending on the requestCode that was passed in, would call the respective method. It should be noted that permission prompts may stack if the execution is not handled correctly, and that this should be avoided.
+The switch statement above would return from the prompt and, depending on the `requestCode` that was passed in, would call the respective method. It should be noted that permission prompts may stack if the execution is not handled correctly, and that this should be avoided.
-In addition to asking for permission for a single permission, it is also possible to request permissions for an entire group by defining the permissions array, as what is done with the Geolocation plugin:
+In addition to asking for permission for a single permission, it is also possible to request permissions for an entire group by defining the `permissions` array, as what is done with the Geolocation plugin:
```java
String [] permissions = { Manifest.permission.ACCESS_COARSE_LOCATION, Manifest.permission.ACCESS_FINE_LOCATION };
@@ -385,13 +388,13 @@ Then when requesting the permission, all that needs to be done is the following:
cordova.requestPermissions(this, 0, permissions);
```
-This requests the permissions specified in the array. It's a good idea to provide a publicly accessible permissions array since this can be used by plugins that use your plugin as a
+This requests the permissions specified in the array. It's a good idea to provide a publicly accessible `permissions` array since this can be used by plugins that use your plugin as a
dependency, although this is not required.
## Debugging Android Plugins
Android debugging can be done with either Eclipse or Android Studio, although Android
-studio is recommended. Since Cordova-Android is currently used as a library project,
+Studio is recommended. Since Cordova-Android is currently used as a library project,
and plugins are supported as source code, it is possible to debug the Java code inside
a Cordova application just like a native Android application.
diff --git a/www/docs/en/dev/guide/platforms/ios/plugin.md b/www/docs/en/dev/guide/platforms/ios/plugin.md
index ff5cbba..90be9f6 100644
--- a/www/docs/en/dev/guide/platforms/ios/plugin.md
+++ b/www/docs/en/dev/guide/platforms/ios/plugin.md
@@ -24,7 +24,9 @@ toc_title: iOS
# iOS Plugin Development Guide
This section provides details for how to implement native plugin code
-on the iOS platform. Before reading this, see [Plugin Development Guide][plugin-dev] for
+on the iOS platform.
+
+Before reading this, see [Plugin Development Guide][plugin-dev] 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
@@ -258,6 +260,7 @@ For JavaScript, you can attach Safari to the app running within the iOS Simulato
described in Domain [Whitelist Guide](../../appdev/whitelist/index.html). If you forget, an error is
logged in the Xcode console.
+[plugin-dev]: ../../hybrid/plugins/index.html
[CDVInvokedUrlCommand.h]: https://github.com/apache/cordova-ios/blob/master/CordovaLib/Classes/Public/CDVInvokedUrlCommand.h
[CDVPluginResult.h]: https://github.com/apache/cordova-ios/blob/master/CordovaLib/Classes/Public/CDVPluginResult.h
[CDVCommandDelegate.h]: https://github.com/apache/cordova-ios/blob/master/CordovaLib/Classes/Public/CDVCommandDelegate.h
diff --git a/www/docs/en/dev/guide/platforms/windows/plugin.md b/www/docs/en/dev/guide/platforms/windows/plugin.md
index dd07494..258e81d 100644
--- a/www/docs/en/dev/guide/platforms/windows/plugin.md
+++ b/www/docs/en/dev/guide/platforms/windows/plugin.md
@@ -31,7 +31,7 @@ a Windows Store app for Windows 8.1 phone and desktop, and Universal Windows Pla
Windows Cordova plugins are essentially a thin wrapper around existing WinJS provided functions, but assuming you will want to define your JS common interface for multiple devices, you will typically have one JS file that provides the API:
```js
-// inside file echoplugin.js
+// inside file www/echoplugin.js
var EchoPlugin = {
// the echo function calls successCallback with the provided text in strInput
// if strInput is empty, it will call the errorCallback
@@ -43,10 +43,12 @@ var EchoPlugin = {
The `cordova.exec` function is defined differently on every platform, this is because each platform has it's own way of communicating between the application js code, and the native wrapper code. But in the case of Windows, there is no native wrapper, so the exec call is there for consistency. So even though you could write the Windows specific code as a part of plugin's common JS code directly, this is not recommended and plugin authors should use the same exec API for Windows as for ot [...]
-On Windows, cordova provides a proxy that you can use to register an object that will handle all cordova.exec calls to an API. So in our case, we will assume that the code in `echoplugin.js` is handling cross platform relevant JavaScript, and we can simply write a proxy for Windows.
+### Plugin Exec Proxy
+
+On Windows, Cordova provides a proxy that you can use to register an object that will handle all `cordova.exec` calls to an API. So in our case, we will assume that the code in `echoplugin.js` is handling cross platform relevant JavaScript, and we can simply write a proxy for Windows.
```js
-// in file echoplugin.js
+// in file www/echoplugin.js
window.echo = function(str, callback) {
cordova.exec(callback, function(err) {
callback('Nothing to echo.');
@@ -55,7 +57,7 @@ window.echo = function(str, callback) {
```
```js
-// in file echopluginProxy.js
+// in file src/windows/echopluginProxy.js
cordova.commandProxy.add("Echo",{
echo:function(successCallback,errorCallback,strInput) {
if(!strInput || !strInput.length) {
@@ -66,11 +68,26 @@ cordova.commandProxy.add("Echo",{
}
}
});
+
+// or alternative syntax
+
+module.exports = {
+ echo: function(successCallback, errorCallback, strInput) {
+ if(!strInput || !strInput.length) {
+ errorCallback("Error, something was wrong with the input string. =>" + strInput);
+ }
+ else {
+ successCallback(strInput + "echo");
+ }
+ }
+};
+
+require('cordova/exec/proxy').add('Echo', module.exports);
```
-The `echoplugin.js` file will forward the `echo` function call to this proxy through the `cordova.exec` command and execute this implementation.
+The `www/echoplugin.js` file will forward the `echo` function call to this proxy through the `cordova.exec` command and execute this implementation in `src/windows/echopluginProxy.js`.
-The plugin.xml file will have the settings required for our plugin. In this case, we want to add our `echoplugin.js` file in the `www` directory and the `echopluginProxy.js` file inside the `windows` source code of our application. Details of these elements can be found in the [Plugin.xml](../../../plugin_ref/spec.html) reference.
+The `plugin.xml` file will have the settings required for our plugin. In this case, we want to add our `echoplugin.js` file in the `www` directory and the `echopluginProxy.js` file inside the `windows` source code of our application. Details of these elements can be found in the [Plugin.xml](../../../plugin_ref/spec.html) reference.
```xml
<?xml version="1.0" encoding="UTF-8"?>
@@ -94,7 +111,8 @@ The plugin.xml file will have the settings required for our plugin. In this case
</plugin>
```
-This gives us a working Windows JavaScript plugin that uses a common file ( echoplugin.js ) and uses a proxy to provide the Windows only portion of implementation ( echopluginProxy.js ). So how do we add native/managed code to this? Well we are going to start the same, the only difference will be what we do inside in echopluginProxy methods.
+
+This gives us a working Windows JavaScript plugin that uses a common file (`www/echoplugin.js`) and uses a proxy to provide the Windows only portion of implementation (`src/windows/echopluginProxy.js`). So how do we add native/managed code to this? Well we are going to start the same, the only difference will be what we do inside in echopluginProxy methods.
## Creating a Windows Plugin in C++ or managed code.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org