Fichero de configuracion

En cada proyecto se incluye un fichero de configuración config.xml que nos permite establecer las principales opciones de configuración de nuestra aplicación de forma global (para todas las plataformas destino).

Este fichero se situa en la carpeta raíz del proyecto (app/config.xml), pero por cuestiones de compatibilidad con versiones anteriores de PhoneGap también está soportado desde la ruta: app/www/config.xml

Al compilar un proyecto (mediante el comando build o run del CLI) se crean versiones específicas de este fichero de configuración para cada plataforma, lo que nos permite establecer configuraciones más específicas. La ruta donde el fichero es copiado varía dependiendo de la plataforma, por ejemplo:

app/platforms/ios/AppName/config.xml
app/platforms/blackberry10/www/config.xml
app/platforms/android/res/xml/config.xml

Para más información sobre configuraciones específicas podéis consultar la sección "Configuration" de cada plataforma en:

http://docs.phonegap.com/en/edge/guide_platforms_index.md.html#Platform Guides

A continuación se describen las opciones de configuración generales para todas las plataformas, pero además de estas hay muchas específicas dependientes de la plataforma:

• iOS Configuration: http://docs.phonegap.com/en/edge/guide_platforms_ios_config.md.html#iOS Configuration

• Android Configuration: http://docs.phonegap.com/en/edge/guide_platforms_android_config.md.html#Android Configuration

• BlackBerry 10 Configuration: http://docs.phonegap.com/en/edge/guide_platforms_blackberry10_config.md.html#BlackBerry 10 Configuration

Elementos de configuración principales

A continuación se muestran las primeras líneas del fichero config.xml generado por defecto al crear un nuevo proyecto de PhoneGap. Esta configuración es compatible para todas las plataformas:

<widget id="com.example.hello" version="1.0.0">
    <name>HolaMundo</name>
    <description>
        Ejemplo de aplicación con PhoneGap
    </description>
    <author email="[e-mail]" href="http://miweb.com">
        Nombre autor
    </author>
    <content src="index.html" />
    <access origin="*" />
    <preference name="permissions" value="none" />
    <preference name="..." value="..." />
    ...
</widget>

Donde:

• <widget>: su atributo id especifica el paquete de la aplicación (usando el reverse-domain-name), y su atributo version es el número completo de versión de la app (siguiendo la notación major/minor/patch, ver más información en la sección "Versión de la aplicación").

• <name>: especifica el nombre del proyecto y de la app, es el que aparecería al instalar la app junto a su icono y en los markets.

• <description> y <author>: son metadatos e información de contacto que se utilizará al publicar la app en los markets.

• <content>: es un atributo opcional para indicar la página inicial de nuestro código. Por defecto se utilizará index.html.

• <access>: define un conjunto de dominios externos a los que se le permite acceder. Por defecto, al indicar * se le permite acceder a cualquier servidor. Para más información consultar la ayuda sobre Domain Whitelist.

• <preference>: establece opciones de configuración siguiendo la notación de pares nombre-valor, sin distinguir mayúsculas y minúsculas. En las siguientes secciones se tratarán estas opciones de configuración, las cuales pueden ser genéricas o específicas para algunas plataformas.

Las preferencias globales se aplicarán para todas las plataformas para las que se compile el proyecto.

• fullscreen permite mostrar u ocultar la barra de estado de la pantalla. El valor por defecto es false. Ejemplo:

<preference name="fullscreen" value="true" />

• orientation permite controlar si se ha de permitir que la pantalla gire o no. Los valores permitidos son: default, landscape, o portrait, siendo default el valor por defecto (el cual permite ambas orientaciones). Ejemplo:

<preference name="orientation" value="landscape" />

Además de todas estas opciones de configuración también es posible establecer los iconos y splashscreens que se utilizarán para cada plataforma. En las siguientes secciones veremos estos temas más en profundidad.

Iconos

Los iconos se pueden especificar utilizando la etiqueta <icon> en el fichero config.xml, por ejemplo:

<icon gap:platform="ios" height="57" src="www/res/icon/ios/icon-57.png" width="57" />

Donde:

• src: (requerido) localización de la imagen relativa a la carpeta del proyecto.

• gap:platform: (opcional) plataforma para la que se utilizará el icono.

• width: (opcional) ancho en píxeles.

• height: (opcional) alto en píxeles.

Para establecer un icono que se utilizará en todas las plataformas podemos establecer la siguiente configuración:

<icon src="icon.png" />

En caso de no especificar ningún logo por defecto se utilizará el icono de Apache Cordova.

Podemos utilizar tantas etiquetas como sea necesario para establecer los iconos para cada plataforma, incluso podemos indicar varios para una misma plataforma con distintos tamaños o densidades. Por ejemplo:

<icon gap:platform="android" gap:qualifier="ldpi" src="www/res/icon/android/icon-36-ldpi.png" />
<icon gap:platform="android" gap:qualifier="mdpi" src="www/res/icon/android/icon-48-mdpi.png" />
<icon gap:platform="android" gap:qualifier="hdpi" src="www/res/icon/android/icon-72-hdpi.png" />
<icon gap:platform="android" gap:qualifier="xhdpi" src="www/res/icon/android/icon-96-xhdpi.png" />

Otro ejemplo para establecer todos los iconos de iOS:

<icon gap:platform="ios" height="57" src="www/res/icon/ios/icon-57.png" width="57" />
<icon gap:platform="ios" height="72" src="www/res/icon/ios/icon-72.png" width="72" />
<icon gap:platform="ios" height="114" src="www/res/icon/ios/icon-57-2x.png" width="114" />
<icon gap:platform="ios" height="144" src="www/res/icon/ios/icon-72-2x.png" width="144" />

Splash Screens

Igual que la configuración de los iconos, PhoneGap también permite definir un splashscreen para las distintas plataformas, por ejemplo para Android y para iOS:

<gap:splash gap:platform="android" gap:qualifier="port-ldpi" src="www/res/screen/android/screen-ldpi-portrait.png" />
<gap:splash gap:platform="android" gap:qualifier="port-mdpi" src="www/res/screen/android/screen-mdpi-portrait.png" />
<gap:splash gap:platform="android" gap:qualifier="port-hdpi" src="www/res/screen/android/screen-hdpi-portrait.png" />
<gap:splash gap:platform="android" gap:qualifier="port-xhdpi" src="www/res/screen/android/screen-xhdpi-portrait.png" />

<gap:splash gap:platform="ios" height="480" src="www/res/screen/ios/screen-iphone-portrait.png" width="320" />
<gap:splash gap:platform="ios" height="960" src="www/res/screen/ios/screen-iphone-portrait-2x.png" width="640" />
<gap:splash gap:platform="ios" height="1136" src="www/res/screen/ios/screen-iphone-portrait-568h-2x.png" width="640" />
<gap:splash gap:platform="ios" height="1024" src="www/res/screen/ios/screen-ipad-portrait.png" width="768" />
<gap:splash gap:platform="ios" height="768" src="www/res/screen/ios/screen-ipad-landscape.png" width="1024" />

Versión de la aplicación

Tanto Android como iOS soportan una cadena con una nombre (o número) de versión alternativo además del que se utiliza en el market. En Android es el versionCode y en iOS el CFBundleVersion. A continuación se muestra como podemos establecer estas versiones en el config.xml:

<widget id="io.cordova.hellocordova"
    version="1.0.0"
    android-versionCode="7"
    ios-CFBundleVersion="3.3.3">

Si esta versión no se especifica se construirá a partir del atributo version. Como se ha indicado este atributo se construye siguiendo la notación major/minor/patch, por lo que se usarán estos valores de la forma:

// version = MAJOR.MINOR.PATCH-whatever
versionCode = PATCH + MINOR * 100 + MAJOR * 10000
CFBundleVersion = "MAJOR.MINOR.PATCH"