Config xml

El gap en Phonegap

Asi que... que es el archivo config.xml que esta en el raiz del proyecto?

Como vimos cuando estabamos firmando la aplicacion, gran parte de la mecanica del compilador usa archivos XML. Los XML son mas ampliamente aceptados que otros formatos de documentos jerarquizados, y fue la eleccion de la gente de Phonegap para generar un archivo que pudiera reglamentar y configurar una aplicacion ante cualquiera de los compiladores: ant (android), XCode (Mac), VisualStudio (Microsoft)

Dentro tiene un documento XML conformado por configuraciones y opciones para los aspectos basicos de la aplicacion. En su forma mas basica el config.xml se ve asi:

<?xml version='1.0' encoding='utf-8'?>
<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="*" />
</widget>

Define el comportamiento de la aplicacion, el nombre, la version, de donde va a sacar contenido, que permisos necesita, a que URLs podra consultar, etc, etc.

El archivo tiene un header de XML, obligado para estos formatos, no se cierra, simplemente es parte del standard de XML

Luego define un nodo (o tag) widget y toda la descripcion y configuracion es parte de ese nodo, es el nodo top level. Hagamos una referencia rapida de XML:

Header XML - Requerido

<?xml version='1.0' encoding='utf-8'?>

Nodo, propiedades y valores

<widget id="com.example.hello" version="0.0.1">
 ^^^^^^ ^^                     ^^^^^^^
    |    |_____propiedades________|
    |
  Nombre de nodo

Si miran el config.xml de nuestro proyecto se va a ver muy distinto pero no mas complejo. Tiene muchos valores definidos y opciones para la aplicacion, y son todas opciones que Phonegap pone por defecto ahi. Estos son valores y configuraciones que TODAS las app comparten, algo asi como un minimo denominador comun de apps. Vamos a ir viendo por partes los nodos y que hacen.

Basicos

Si vemos la configuracion basica:

<?xml version='1.0' encoding='utf-8'?>
<widget id="com.codenautas.interviewrecorder" version="1.0.0" xmlns="http://www.w3.org/ns/widgets" xmlns:gap="http://phonegap.com/ns/1.0">
    <name>Interview Recorder</name>
    <description>
        Hello World sample application that responds to the deviceready event.
    </description>
    <author email="support@phonegap.com" href="http://phonegap.com">
        codenautas
    </author>
    <content src="index.html" />
    <access origin="*" />
</widget>

Nodos

---

widget

Nodo top level o principal, lleva estas propiedades:

• id - {String}: el bendito id que les hice poner en todas las aplicaciones que hicimos. Es un FQCN (Fully Qualified Class Name) y se define como una propiedad del tag widget. Es lo que va a identificar la aplicacion en el dispositivo, sirve para que tanto el dispositivo como el store identifiquen univocamente nuestra aplicacion. Si otra aplicacion apareciera con el mismo id significaria que es un update o reemplazo de la primera. Ej: com.microsoft.internetexplorer, ar.gob.gcba.dgeyc, com.codenautas.interviewrecorder
• version - {SemVer String}: es un texto, pero con formato de versionamiento semantico (SemVer). Esto es, basicamente, un numero que representa una version especifica de una aplicacion o software. El primer digito es la version major, el segundo es el minor y el tercero representa el patch.
  • major: se cambia en ocasiones especiales, generalmente representa un cambio grande. Puede ser de estetica o funcionalidad interna. Pero particularmente en lexico programador es una alerta para cuando dependemos de una aplicacion o libreria: cuando los cambios que se introducen rompen compatibilidad es una obligacion cambiar el major version
  • minor: son cambios internos, caracteristicas nuevas, sutiles cambios de interfaz (generalmente porque una nueva feature o caracteristica debe ofrecer un elemento nuevo - boton, indicador - necesita este cambio)
  • patch: son generalmente fixes, hotfixes y bugfixes. Representan cambios que nos conviene adoptar si los hay, dado que es algo que el programador arreglo
• xmlns - {URL/String}: indica el namespace del XML. Dado un namespace la aplicacion que lee el XML puede buscar el estandar que rige ese XML en particular basandose en su namespace. Por lo general tambien representa la ubicacion de la documentacion pertinente a ese namespace
• xmlns:gap - {URL/String}: idem anterior, pero propietario de Phonegap

---

:gap:

Hay que aclarar que algunos nodos y propiedades tiene este prefixo/sufijo. No hay realmente documentacion sobre que refiere el prefijo gap: o sufijo :gap. Solo les puedo contar lo que, a prueba y error, sospecho.

Por lo general no es necesario, cuando aparece es porque el compilador online de Adobe Phonegap, PhonegapBuild, lo utiliza para configurar de manera particular algo. No entiendo bien por que, pero cuando compilamos desde nuestra maquina podemos remover estos prefijos/sufijos y la aplicacion va a funcionar igual y, de hecho, si no sacamos algunos no vamos a poder configurar correctamente el nodo o la propiedad.

---

name

Configura un valor String que representa el nombre visible de la aplicacion. Es el nombre que aparecera en el store y bajo el icono cuando lo veamos en el dispositivo

---

description

Configura un valor String que representa la descripcion de la aplicacion. No recuerdo donde verla en el dispositivo, pero es utilizada por el store para describirla.

---

author

Configura un valor String que representa el nombre o identificacion del autor. Puede llevar 2 propiedades

• email- {Email/String}: la direccion de correo electronico del autor
• href - {URL/String}: el sitio web/dominio del autor

---

content

Es un nodo sin valor, solo configura la propiedad src como el archivo que va a usar para el contenido inicial de la aplicacion. Es es, indefectiblemente para aplicaciones de Phonegap, index.html

---

access origin

Indica que sitios podra consultar la aplicacion. Por defecto se configura con un asterisco (*) indicando que puede consultar cualquier sitio de internet.

---

preference

Luego de la configuracion basica aparecen los tag preference. Estos son tags que solo definen pares de variables/valores a traves de 2 propiedades:

• name: el nombre de la variable o configuracion
• value: el valor que se le va a asignar a la variable

La documentacion de Cordova hace la distincion de FullScreen y Orientation como globales, refiriendose a que se aplican a todas las plataformas:

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

Se supone que el resto son para plataformas especificas o para mas de una plataforma pero no para todas.

---

platform

El tag platform se usa para englobar tags preference que queremos para alguna plataforma especifica. Por ejemplo podriamos querer que en Android se ve FullScreen, pero no asi en iOS:

  <platform name="android">
    <preference name="Fullscreen" value="true" />
  </platform>
  <platform name="ios">
    <preference name="Fullscreen" value="false" />
  </platform>

Principalmente vamos a utilizar este tipo de preferencias selectivas cuando estemos configurando los iconos y splashes.

---

icon

Define el icono para utilizar para la aplicacion. Por defecto se Phonegap lo configura como:

    <icon src="icon.png" />

Basicamente el tag icon solo recibe la propiedad src, que es el path al icono que queremos usar. Si miramos en el config.xml que nos deja Phonegap vemos que tenemos un monton de iconos con propiedades extra: gap:platform y gap:qualifier. Estas 2 propiedades solo sirven usando el servicio de compilacion PhonegapBuild, para nosotros no tienen ningun efecto. Veremos mas en detalle en la seccion de iconos.

Android

El tag icon puede llevar la propiedad density para los iconos que son para Android. Density representa la densidad de pixels por pulgada que soporta la pantalla del dispositivo. Las densidades conocidas hasta el momento son:

• ldpi: Low Density Per Inch, baja resollucion
• mdpi: Medium DPI, media resolucion
• hdpi: High DPI, alta resolucion
• xhdpi: Xtra High DPI ... (empieza la fruta)
• xxhdpi: Xtra Xtra High DPI
• xxxhdpi: Al infinito y mas alla Cada una representa una resolucion de pantalla aproximada, luego lo veremos en detalle.

iOS

Para plataformas iOS podemos proveer la dimension del icono a traves de las propiedades ancho (width) y alto (height)

---

splash

Al igual que el tag icon, el tag splash define cuales van a ser las splashes de nuestra aplicacion (la pantalla que aparece mientras la aplicacion se carga) a traves de la propiedad src.

Van a notar que en nuestro config.xml estos tags estan cambiados por algo como:

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

Nuevamente, estos tags con prefijo gap: (tanto los tags como las propiedades) no tendran ningun efecto.

Las propiedades del tag splash son iguales a las del tag icon con la diferencia que los valores para la propiedad density llevan por delante los prefijos:

• land-: indica el splash es para cuando el dispositivo esta landscape (horizontal). Ej: land-hdpi, land-ldpi, etc
• port-: indica que el splash es para utilizar en portrait (vertical). Ej: port-ldpi, port-xxhdpi, etc.

Esta excepcion no existe para las plataformas iOS ya que indicamos las dimensiones en ancho y alto y el dispositivo sabra cual tiene que usar en cada caso.

Resumen

Por lo general las cosas configurables a traves de tags preference son estandar, no necesitamos cambiarlas, pero puede haber ocasiones en que tengamos que configurar algo de manera especial y estos tags van a ser el primer lugar para mirar.

Aclaracion:

A medida que avanzan las versiones de:

• Phonegap
• Cordova
• Android
• iOS
• WindowsPhone hay documentacion que queda vieja, hay features que las plataformas ya no soportan, o features nuevos de las plataformas que no hay manera de configurar porque Cordova todavia no implemento la manera. Esto lo menciono porque muchas veces va a pasar que intentan configurar algo y no responde como deberia, ante la duda, siempre Google.

A continuacion vamos a ver como configurar correctamente los iconos y splashes

Ref: The Config.xml