Apéndice II: El archivo config.xml

Muchos aspectos del comportamiento de una aplicación, pueden controlarse con el archivo de configuración global config.xml, el cual se encuentra en el directorio xml, dentro de res.

Este archivo es independiente de la plataforma y esta basado en el formato especifico de la W3C (Empaquetado de aplicaciones web (Widgets)), ampliado para cumplir con las especificaciones de la API Cordova, con sus plugins y con la configuración de cada plataforma.

Para los proyectos que se han creado con el CLI, este archivo se encuentra en el directorio del nivel superior de www, de hecho se regenera en diferentes directorios dentro de platforms dependiendo de las plataformas, de modo que se puede encontrar en otros lugares diferentes al de la imagen dependiendo de la plataforma en la que se trabaje. (la imagen corresponde a un proyecto creado con CLI e importado a eclipse bajo la plataforma Android)

Elementos de la configuración del núcleo

El siguiente ejemplo muestra el varlor predeterminado de config.xml, al ser generado en el CLI por el comando create:

<widget id="com.example.hello" version="0.0.1">
        <name>HelloWorld</name>
        <description>
            A sample Apache Cordova application that responds to the deviceready event.
        </description>
        <author email="dev@callback.apache.org" href="http://cordova.io">
            Apache Cordova Team
        </author>
        <content src="index.html" />
        <access origin="*" />
        <preference name="Fullscreen" value="true" />
        <preference name="WebViewBounce" value="true" />
    </widget>

 

 Se puede observar que aparecen los siguientes elementos de configuración en el archivo, y que están admitidos para todas las plataformas soportadas por Cordova:

    • Atributo id de la etiqueta <widget>: el cual proporciona un identificador y un número de versión.
    • La etiqueta <name>: especifica el nombre formal de la aplicación, como aparece en la pantalla principal del dispositivo y como aparecerá dentro de la tienda de app.
    • Las etiquetas <descripcion> y <author>: especifican metadatos e información de contacto que pueden aparecer en los anuncios de la tienda app.
    • La etiqueta opcional <content>: la cual define la página de inicio de la aplicación. El valor predeterminado por defecto es el archivo index.html, que habitualmente se encuentra en el directorio www del proyecto.
  • Etiquetas <access>: definen el conjunto de dominios externos que pueden comunicarse con la aplicación. El valor determinado que se muestra, le permite acceder a cualquier servidor.
  • La etiqueta <preference>: establece varias opciones como pares de, nombre/valor de atributos, referidos a las preferencias name, siendo sensible a las mayúsculas. Muchas de estas preferencias son exclusivas de plataformas especificas.

Preferencias globales

Las siguientes preferencias se pueden aplicar a todas las plataformas:

  • Fullscreen: permite ocultar la barra de estado en la parte superior de la pantalla. El valor predeterminado es false:
<preferencename="Fullscreen"value="true"/>
  • Orientation: Permite bloquear la orientacion y evitar que se rote la pantalla en respuesta a los cambios de orientacion del  dispositivo. Los valores posibles son; default, landscape y protrait.
<preferencename="Orientation"value="landscape"/>

Nota: BlackBerry utiliza auto en lugar de default, si se especifica default en el xml global, BlackBerry lo traduce como auto en su compilación.

Preferencias de múltiples plataformas

  • DisallowOverscroll (boolean, valor predeterminado false): Si no se quiere que la interfaz regenere el scroll de la pantalla. Esto puede dar problemas, pero se arreglan tan solo poniendo el valor en true.
<preferencename="DisallowOverscroll"value="true"/>

Se aplca en iOs y Android.

  • BackgroundColor: Sirve para definir el color de fondo de la aplicacion, admitiendo un valor hexadecimasl de cuatro bytes, representando el primero el valor alfa y los demas el RGB stándard para los siguientes tres bytes.
<preferencename="BackgroundColor"value="0xff00ff00"/>

Se aplica en Android y BlackBerry, anulando los CSS disponibles.

  • HideKeyboardFomAccessryBar (boolean, valor predeterminado false): si se coloca en true, se oculta la barra de herramientas que aparece encima del teclado.
<preferencename="HideKeyboardFormAccessoryBar"value="true"/>

Se aplica solo en iOs y BlackBerry. En BlackBerry los valores válidos son enable o disable.

La etiqueta <feature>

Se utiliza el CLI para construir aplicaciones, se debe utilizar el comando plugin para activar las APIs. Esto no modifica el nivel superior de config.xml, de modo que la etiqueta <feature> no se aplica al flujo de trabajo.

Si se trabaja directamente en el SDK utilizando la plataforma especifica, utilizando su propio archivo config.xml, se introduce la etiqueta <feature> para permitir el acceso a plugins externos.

De forma general se sigue el siguiente formato:

    <featurename="Plugin"value="PluginID"/>

En numerosas ocasiones aparecen valores personalizados en el archivo config.xml de la plataforma específica. En el siguiente ejemplo se especifica el dispositivo de API para proyectos en Android.

<featurename="Device">
    <paramname="android-package"value="org.apache.cordova.device.Device"/>
</feature>