martes, 7 de junio de 2016

Crear un plugin en apache-cordova

Un plugin es un pequeño programa que nos permitirá tener acceso a alguna de las características o funcionalidades del dispositivo, por medio de Apache-Cordova. Puedes encontrar gran número de plugins en:

http://cordova.apache.org/plugins/

Cada plugin constará de:


  1. Un archivo JavaScript que funciona como interfaz, 
  2. Un archivo plugin.xml (conocido como manifiesto) que sirve para configuración del API y 
  3. Un archivo con el código del lenguaje nativo de cada plataforma.


Puedes almacenar tu plugin en tu cuenta git y acceder al mismo por medio de la URL:

  $ cordova plugin add https://git-micuenta.com/cordova-plugin-miplugin.git


El manifiesto  o el archivo plugin.xml


Primero debemos contar con un archivo plugin.xml que es el archivo de configuración o "manifiesto" de nuestro plugin. Un ejemplo sencillo del mismo se muestra a continuación:

 <?xml version="1.0" encoding="UTF-8"?>

    <plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
            id="cordova-plugin-miplugin" version="0.0.1.">
        <name>miPlugin</name>
        <auhtor>Yo Mero</autho>
        <description>Un plugin muy sencilla</description>
        <license>Apache 2.0</license>
        <keywords>cordova,apache</keywords>

        <js-module src="www/miPlugin.js" name="device">
            <clobbers target="window.miPlugin" />
        </js-module>

        <platform name="android">
            <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>

La primera línea es el identificador de XML como cualquier archivo XML:

 <?xml version="1.0" encoding="UTF-8"?>

La siguiente línea determina el "name space" del xml y no debe cambiar, pero tiene como atributos el nombre del plugin y su número de versión en el formato "versión mayor.versión menor.parche" (si quieres conocer más sobre el manejo de versiones, entra a http://semver.org/). Es la etiqueta principal como cualquier archivo XML bien formado:

  <plugin xmlns="http://apache.org/cordova/ns/plugins/1.0" id="cordova-plugin-miplugin" version="0.0.1.">

Las siguientes líneas son para identificación del autor. Si quieres conocer más sobre las licencias de código abierto u "open source", entra a http://opensource.org/licenses

<name>miPlugin</name>
<auhtor>Yo Mero</autho>
<description>Un plugin muy sencilla</description>
<license>Apache 2.0</license>
<keywords>cordova,apache</keywords>

En el siguiente bloque de instrucciones indicamos dónde se encuentra el archivo js y con clobbers indicamos el objeto y la forma de llamarlo. También podemos añadirlo al objeto "navigator". Esta directiva copia el archivo js al proyecto de cordova y le dará acceso a tus rutinas cuando sean llamadas desde la aplicación.

<js-module src="www/miPlugin.js" name="device">
            <clobbers target="window.miPlugin" />
</js-module>

Las siguientes etiquetas nos indican los archivos fuente dependiendo de cada plataforma:

<!-- android -->
<platform name="android">
     <config-file target="res/xml/config.xml" parent="/*">
          <feature name="HelloPlugin">
               <param name="android-package" value="org.camden.plugin.HelloPlugin"/>
           </feature>

      </config-file>
      <source-file src="src/HelloPlugin.java" target-dir="src/org/camden/plugin" />

</platform>

Habría que añadir un bloque similar si el plugin es válido para más de una plataforma. La etiqueta <config-file> indica la ubicación física del archivo xml. El contenido del archivo es "incrustado" en el archivo config.xml de cordova donde se le indica en el parámetro "parent".

La etiqueta <feature> indica el nombre del plugin y sus parámetros (?)
La etiqueta <source-file> indica la ubicación y el nombre del archivo con el código fuente, el cual es escrito en el lenguaje base del dispositivo.El atributo "target-dir"  el directorio en el formato reverse-domain.

http://cordova.apache.org/docs/en/latest/plugin_ref/spec.html


El archivo JavaScript en un plugin

var helloplugin = {
    sayHello:function(name, successCallback, errorCallback) {
        cordova.exec(
            successCallback,
            errorCallback,
            'HelloPlugin',
            'sayHello',

            [{ "name": name }]
         );
    }
}

module.exports = helloplugin;

Primero creamos un objeto contenedor:

var helloplugin = {}

Dentro de este objeto creamos las acciones:

sayHello:function(name, successCallback, errorCallback) {}

La comunicación entre JavaScript y el lenguaje nativo (en este caso es Java) la realizamos por medio de la sentencia:
    cordova.exec(function(winParam) {},
                 function(error) {},
                 "service",
                 "action",
                 ["firstArgument", "secondArgument"]);

El primer parámetro dentro del método exec() es la función que ejecutaremos si todo marcha bien (successCallback). 
El segundo parámetro es el nombre de la función si las cosas no salen bien (errorCallback). 
El tercer parámetro es nombre del plugin que será utilizado (HelloPlugin).
El cuarto parámetro es la acción a pasar desde el código nativo.
El quinto parámetro es el valor que vamos a pasar al código nativo.

Fuera de la definición, regresamos el objeto que cordova lo hace disponible a la aplicación

module.exports = helloplugin;

Este plugin toma una cadena y regresa un mensaje (otra cadena).

No hay comentarios:

Publicar un comentario