Guía de desarrollo de plugins

Un plugin es un paquete de código que permite a la webview de Cordova comunique a la aplicación con la plataforma nativa en la que se ejecuta. Los plugins proporcionan acceso a la funcionalidad del dispositivo que está normalmente disponible para aplicaciones basadas en web.

Los plugins comprenden una única interfaz JavaScript junto con bibliotecas de código nativo correspondiente para cada plataforma soportada. Esta sección analiza la estructura básica del plugin y la interfaz JavaScript.

Construyendo un Plugin

Los programadores de aplicaciones utilizan el comando plugin add para aplicar un plugin a un proyecto. El argumento de este comando es la dirección URL de un repositorio git que contiene el código del plugin. Este ejemplo implementa dispositivo API de Cordova:

cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-device.git

El repositorio del plugin debe contar con un archivo plugin.xml de alto nivel. Esta versión abreviada del plugin Device proporciona un ejemplo sencillo de como usarlo:

<?xml version="1.0" encoding="UTF-8"?>
    <plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
            id="org.apache.cordova.device" version="0.2.3">
        <name>Device</name>
        <description>Cordova Device Plugin</description>
        <license>Apache 2.0</license>
        <keywords>cordova,device</keywords>
        <js-module src="www/device.js" name="device">
            <clobbers target="device" />
        </js-module>
        <platform name="ios">
            <config-file target="config.xml" parent="/*">
                <feature name="Device">
                    <param name="ios-package" value="CDVDevice"/>
                </feature>
            </config-file>
            <header-file src="src/ios/CDVDevice.h" />
            <source-file src="src/ios/CDVDevice.m" />
        </platform>
    </plugin>

El atributo id de la etiqueta plugin utiliza el mismo formato de dominio reverso para identificar el paquete plugin. La etiqueta js-module especifica la ruta de acceso a la interfaz común de JavaScript. La etiqueta platform especifica un conjunto de código nativo para la plataforma iOS en este caso. Las etiquetas header-file y source-file especifican la ruta de acceso a archivos de la biblioteca.

Validación de un Plugin

Se puede utilizar la herramienta plugman para comprobar si el plugin está instalado correctamente para cada plataforma.

Para instalar plugman se necesita el siguiente comando de node:

$ npm install -g plugman

Asegúrese de que la página index.html de la aplicación hace referencia al interfaz del plugin, en este caso se encuentra en el mismo directorio fuente:

<script src="myplugin.js"></script>

Después hay que ejecutar un comando como el siguiente para comprobar las dependencias de la plataforma iOS se carguen adecuadamente:

$ plugman -platform ios /path/to/my/project/www /path/to/my/plugin

La interfaz de JavaScript

Se puede estructurar el código JavaScript del plugin a gusto del desarrollador, pero tiene que llamar siempre al cordova.exec para comunicarse con la plataforma nativa, usando la siguiente sintaxis:

cordova.exec(function(winParam) {},
             function(error) {},
             "service",
             "action",
             ["firstArgument", "secondArgument", 42, false]);

Aquí se explica cómo funciona cada parámetro:

  • function(winParam) {}: Una función que devuelve correcto. Asumiendo que la llamada exec se realiza correctamente, esta función se ejecuta junto con cualquiera de los parámetros pasados.
  • function(error) {}: Una función que devuelve incorrecto. Si la operación no se completa correctamente, esta función se ejecuta con un parámetro opcional de error.
  • "service": El nombre del servicio que se llama del lado nativo. Esto corresponde a una clase nativa.
  • "action": El nombre de la acción que se llama del lado nativo. Esto generalmente corresponde al método de la clase nativa.
  • [/* arguments */]: Un conjunto de argumentos que se pasarán al entorno nativo.

Publicación de Plugins

Una vez que se ha desarrollado el plugin, se tiene la opción de publicarlo y compartirlo con la comunidad. Los desarrolladores los instalan automáticamente usando ya sea plugman o la CLI Cordova.

Para publicar un plugin es necesario utilizar la herramienta plugman y seguir los siguientes pasos:

$ plugman adduser
$ plugman publish /path/to/your/plugin