Especificación de plugin

Especificación de plugin

El plugin.xml archivo es un documento XML en el plugins espacio de nombres: http://apache.org/cordova/ns/plugins/1.0 . Contiene un alto nivel plugin elemento que define el plugin y niños que definen la estructura del plugin.

Un elemento de plugin de muestra:

<?xml version="1.0" encoding="UTF-8"?>
<plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
    xmlns:android="http://schemas.android.com/apk/res/android"
    id="com.alunny.foo"
    version="1.0.2">

<plugin>elemento

El plugin es elemento superior del manifiesto del plugin. Cuenta con los siguientes atributos:

<engines>y <engine> elementos

Los elementos secundarios de la <engines> elemento especificar las versiones de los marcos basados en Apache Cordova que este plugin soporta. Un ejemplo:

<engines>
    <engine name="cordova" version="1.7.0" />
    <engine name="cordova" version="1.8.1" />
    <engine name="worklight" version="1.0.0" platform="android" scriptSrc="worklight_version"/>
</engines>

Similar a la <plugin> del elemento version atributo, la cadena de versión especificada debe coincidir con una cadena de mayor-menor-patch conforme a la expresión regular:

    ^\d+[.]\d+[.]\d+$

Elementos del motor también pueden especificar confuso acerca de los partidos para evitar la repetición y para reducir el mantenimiento cuando se actualiza la plataforma subyacente. Herramientas deben soportar un peso mínimo de > , >= , < y <= , por ejemplo:

<engines>
    <engine name="cordova" version=">=1.7.0" />
    <engine name="cordova" version="<1.8.1" />
</engines>

El '' etiquetas también cuenta con soporte por defecto para todas las plataformas principales Cordova existe en. Especifica la etiqueta de 'cordova' motor significa que todas las versiones de Cordova en cualquier plataforma deben satisfacer el atributo de versión de motor. También se puede enumerar sus versiones y plataformas específicas con el fin de reemplazar el motor de catch-all 'cordova':

<engines>
    <engine name="cordova" version=">=1.7.0" />
    <engine name="cordova-android" version=">=1.8.0" />
    <engine name="cordova-ios" version=">=1.7.1" />
</engines>

Aquí está una lista de la cesación de pagos que motores del '' las ayudas de la etiqueta: * 'cordova' * 'cordova-plugman' * 'cordova-android' * 'cordova-ios' * 'cordova-blackberry10' * 'cordova-wp7' * 'cordova-wp8' * 'cordova-windows8'

Especificar Marcos personalizados basados en Apache Cordova deben aparecer bajo la etiqueta de motor así:

<engines>
    <engine name="my_custom_framework" version="1.0.0" platform="android" scriptSrc="path_to_my_custom_framework_version"/>
    <engine name="another_framework" version=">0.2.0" platform="ios|android" scriptSrc="path_to_another_framework_version"/>
    <engine name="even_more_framework" version=">=2.2.0" platform="*" scriptSrc="path_to_even_more_framework_version"/>
</engines>

Un marco personalizado basado en Apache Cordova exige que un elemento motor incluye los siguientes atributos: 'nombre', 'versión', 'scriptSrc' y 'plataforma'.

plugman se anula con un código distinto de cero para cualquier plugin cuyo objetivo proyecto no cumple con las limitaciones del motor.

Si no <engine> etiquetas se especifican, plugman intenta instalar en el directorio del proyecto especificado cordova ciegamente.

<name>elemento

Un nombre legible para el plugin, cuyo contenido de texto contiene el nombre del plugin. Por ejemplo:

< nombre > Foo < / nombre >

Este elemento no es (todavía) localización de la manija.

<description>elemento

Una descripción legible para el plugin. El contenido del texto del elemento contiene la descripción del plugin. Un ejemplo:

<description>Foo plugin description</description>

Este elemento no es (todavía) localización de la manija.

<author>elemento

Nombre autor del plugin. El contenido del texto del elemento contiene el nombre del autor del plugin. Un ejemplo:

<author>Foo plugin description</author>

<keywords>elemento

Palabras clave plugin. El contenido del texto del elemento contiene palabras clave separadas por comas para describir el plugin. Un ejemplo:

<keywords>foo,bar</keywords>

<license>elemento

Licencia de plugin. El contenido del texto del elemento contiene la licencia del plugin. Un ejemplo:

<license>Apache 2.0 License</license>

<asset>elemento

Uno o más elementos listado los archivos o directorios que se copiarán en una aplicación Cordova www Directorio. Ejemplos:

<!-- a single file, to be copied in the root directory -->
<asset src="www/foo.js" target="foo.js" />
<!-- a directory, also to be copied in the root directory -->
<asset src="www/foo" target="foo" />

Todos <asset> etiquetas requieren ambos src y target atributos. Sólo web plugins contiene principalmente <asset> elementos. Cualquier <asset> elementos que están anidados dentro de <platform> elementos especifican activos específicos a una plataforma web, como se describe a continuación. Los atributos incluyen:

<js-module>elemento

La mayoría de plugins incluyen uno o más archivos JavaScript. Cada <js-module> tag corresponde a un archivo JavaScript y evita que los usuarios del plugin tener que añadir un <script> etiqueta para cada archivo. Mientras que <asset> etiquetas simplemente copien un archivo desde el subdirectorio plugin en www , <js-module> etiquetas son mucho más sofisticados. Se parecen a esto:

<js-module src="socket.js" name="Socket">
    <clobbers target="chrome.socket" />
</js-module>

Al instalar un plugin con el ejemplo anterior, socket.js se copia a www/plugins/my.plugin.id/socket.js y se agrega como una entrada a www/cordova_plugins.js . En el tiempo de carga, el código cordova.js XHR se utiliza para leer cada archivo e inyectar un <script> tag en HTML. Agrega una asignación para aplastar o combinar según sea apropiado, como se describe a continuación.

No envuelva el archivo con cordova.define , como se añade automáticamente. El módulo está envuelto en un cierre, con module , exports , y require en su alcance, como es normal para los módulos de AMD.

Detalles para el <js-module> etiqueta:

Si src no se resuelve en un archivo existente, plugman se detiene y revierte la instalación, emite una notificación del problema y sale con un código distinto de cero.

Anidación <js-module> elementos dentro de <platform> declara enlaces específicos a una plataforma JavaScript módulo.

<dependency>

El <dependency> etiqueta permite especificar otros plugins de los que depende el plugin actual. Mientras que las versiones futuras accederán a ellos desde los repositorios de plugin, en el corto plazo plugins se hace directamente referencia como URL por <dependency> etiquetas. Ellos están formateados como sigue:

<dependency id="com.plugin.id" url="https://github.com/myuser/someplugin" commit="428931ada3891801" subdir="some/path/here" />

En el futuro, se introducirán las limitaciones de la versión y existirá un repositorio plugin para buscar por nombre en lugar de URLs explícitas de apoyo.

Dependencia relativa caminos

Si establece la url de un <dependency> la etiqueta para "." y proporcionar una subdir , se instala el plugin dependiente del mismo local o remoto CVS como el plugin de padres que especifica la <dependency> etiqueta.

Tenga en cuenta que el subdir siempre especifica una ruta relativa a la raíz del repositorio git, no el plugin de padres. Esto es cierto incluso si ha instalado el plugin con una ruta local directamente a él. Plugman encuentra la raíz del repositorio git y luego encuentra el otro plugin de allí.

< plataforma >

El <platform> etiqueta identifica las plataformas que han asociado código nativo o requerir modificaciones en sus archivos de configuración. Herramientas utilizando esta especificación pueden identificar las plataformas soportadas e instalar el código en los proyectos de Córdoba.

Plugins sin <platform> etiquetas se asumen para ser sólo de JavaScript y por lo tanto, instalable en cualquier y todas las plataformas.

Una etiqueta de plataforma de muestra:

<platform name="android">
    <!-- android-specific elements -->
</platform>
<platform name="ios">
    <!-- ios-specific elements -->
</platform>

La necesaria name atributo identifica una plataforma como apoyo, asociando los niños del elemento con esa plataforma.

Nombres de la plataforma deben estar en minúsculas. Nombres de plataforma, como arbitrariamente elegidos, se enumeran:

< archivo fuente >

El <source-file> elemento identifica código ejecutable que debe instalarse en un proyecto. Ejemplos:

<!-- android -->
<source-file src="src/android/Foo.java"
                target-dir="src/com/alunny/foo" />
<!-- ios -->
<source-file src="src/ios/CDVFoo.m" />
<source-file src="src/ios/someLib.a" framework="true" />
<source-file src="src/ios/someLib.a" compiler-flags="-fno-objc-arc" />

Soporta los siguientes atributos:

< archivo config->

Identifica un archivo de configuración basado en XML para ser modificado, donde en ese documento la modificación debe ocurrir, y qué debería ser modificado.

Dos tipos de archivos que han sido probados para la modificación de este elemento son xml y plist archivos.

El config-file elemento sólo permite añadir nuevos niños a un árbol de documentos XML. Los niños son literales XML que se insertará en el documento de destino.

Ejemplo de XML:

<config-file target="AndroidManifest.xml" parent="/manifest/application">
    <activity android:name="com.foo.Foo" android:label="@string/app_name">
        <intent-filter>
        </intent-filter>
    </activity>
</config-file>

Ejemplo de plist :

<config-file target="*-Info.plist" parent="CFBundleURLTypes">
    <array>
        <dict>
            <key>PackageName</key>
            <string>$PACKAGE_NAME</string>
        </dict>
    </array>
</config-file>

Soporta los siguientes atributos:

< plugins-plist >

Es anticuado ya que sólo se aplica a cordova-ios 2.2.0 y por debajo. Uso el <config-file> tag para las nuevas versiones de Córdoba.

Ejemplo:

<config-file target="config.xml" parent="/widget/plugins">
     <plugin name="ChildBrowser" value="ChildBrowserCommand"/>
</config-file>

Especifica una clave y un valor para añadir a la correcta AppInfo.plist archivo en un proyecto de Cordova iOS. Por ejemplo:

<plugins-plist key="Foo" string="CDVFoo" />

<resource-file>y<header-file>

Como archivos de código fuente, pero específicamente para plataformas como iOS que distinguen entre archivos de código fuente, encabezados y recursos. Ejemplos:

<resource-file src="CDVFoo.bundle" />
<resource-file src="CDVFooViewController.xib" />
<header-file src="CDVFoo.h" />

<lib-file>

Como fuente de recursos y archivos de encabezado, pero específicamente para plataformas como BlackBerry 10 que usan las bibliotecas generado por el usuario. Ejemplos:

<lib-file src="src/BlackBerry10/native/device/libfoo.so" arch="device" />
<lib-file src="src/BlackBerry10/native/simulator/libfoo.so" arch="simulator" />

Atributos soportados:

< marco >

Identifica un marco (generalmente parte de la plataforma/OS) de la cual depende el plugin.

Ejemplos:

<framework src="libsqlite3.dylib" />
<framework src="social.framework" weak="true" />

El src atributo identifica el marco, que plugman intenta agregar al proyecto de Cordova, de la manera correcta para una determinada plataforma.

Opcional weak atributo es un valor booleano que indica si el marco debe ser vinculado débilmente. El valor predeterminado esfalse.

<info>

Información adicional proporcionada a los usuarios. Esto es útil cuando usted requiere pasos adicionales que no se pueden automatizar fácilmente o están fuera de alcance de plugman. Ejemplos:

<info>
You need to install __Google Play Services__ from the `Android Extras` section using the Android SDK manager (run `android`).

You need to add the following line to your `local.properties`

android.library.reference.1=PATH_TO_ANDROID_SDK/sdk/extras/google/google_play_services/libproject/google-play-services_lib
</info>

Variables

En ciertos casos, puede necesitar un plugin realizar cambios de configuración depende de la aplicación de destino. Por ejemplo, para registrarse en C2DM en Android, una aplicación cuyo identificador de paquete es com.alunny.message requeriría un permiso tales como:

<uses-permission
android:name="com.alunny.message.permission.C2D_MESSAGE"/>

En estos casos donde se inserta el contenido de la plugin.xml archivo no es conocido antes de tiempo, variables pueden ser indicadas por un signo de dólar seguido por una serie de letras mayúsculas, dígitos o subrayados. Para el ejemplo anterior, el plugin.xml archivo incluiría esta etiqueta:

<uses-permission
android:name="$PACKAGE_NAME.permission.C2D_MESSAGE"/>

plugman reemplaza a referencias a variables con el valor especificado, o la cadena vacía si no se encuentra. El valor de la variable referencia puede ser detectado (en este caso, de la AndroidManifest.xml archivo) o especificado por el usuario de la herramienta; el proceso exacto depende de la herramienta especial.

plugman puede solicitar a los usuarios especificar variables requiere de un plugin. Por ejemplo, las llaves de la API para C2M y Google Maps pueden especificarse como un argumento de línea de comandos:

plugman --platform android --project /path/to/project --plugin name|git-url|path --variable API_KEY=!@CFATGWE%^WGSFDGSDFW$%^#$%YTHGsdfhsfhyer56734

Para hacer obligatorio, la variable de la <platform> etiqueta debe contener un <preference> etiqueta. Por ejemplo:

<preference name="API_KEY" />

plugman comprueba que estas preferencias requeridas son pasadas en. Si no, debe advertir al usuario cómo pasar la variable y la salida con un código distinto de cero.

Ciertos nombres de variable deben ser reservados, que figuran a continuación.

$PACKAGE_NAME

El dominio reverso estilo identificador único para el paquete, correspondiente a la CFBundleIdentifier en iOS o el package atributo del nivel superior manifest elemento en un AndroidManifest.xml archivo.