Criteria Studio » commonJS

App Template para Titanium

J. Rayon — Sun, 12 Aug 2012 11:40:18 +0000

Hoy voy a crear un sencillo template de Titanium que podremos usar para empezar nuestras aplicaciones de cero. Nos servirá para sustituir el template que usa Titanium Studio al crear una aplicación en blanco.

La aplicación por defecto de Titanium Studio crea un tabGroup con dos ventanas. Yo voy a crear la misma aplicación, pero usando módulos commonJS. Además, ya dejamos preparada la estructura de directorios para que nuestra app pueda crecer correctamente desde un principio.

Antes de continuar, puede que te interesen estos artículos si no los has leído aún.JavaScript para Titanium (I), JavaScript para Titanium (II), CommonJS para Titanium

Resumen

Crearemos una app con un TabGroup con 3 tabs (secciones). Cada tab abre una ventana diferente. El mismo código nos permitirá distribuir una aplicación nativa android, iPhone y mobile web.

app.js

Empezamos por el punto de arranque de la app. Recuerda que todas las apps titanium arrancan desde app.js.

	(function(){

	var Mods = require('/ModulePaths');

	var TabGroup = require(Mods.TABGROUP);

	var tabGroup = new TabGroup();

	tabGroup.open();

	})();

view raw

app.js

hosted with ❤ by GitHub

Hay varias cosas que comentar. Primero, habrás observado que todo el fichero está envuelto en una función anónima que se autoejecuta (el hecho de que la función esté envuelta en unos paréntesis con otros paréntesis a continuación hace que la función se ejecute tras ser declarada). Como recordarás de la introducción a JavaScript, las funciones limitan el ámbito de las variables. Con esta función anónima, lo que hacemos es evitar que las variables Mods, TabGroup y tabGroup salten al ámbito global y por tanto puedan ser accesibles desde otras partes de la aplicación. Esta técnica sólo es necesaria (en principio) en el fichero app.js, ya que el resto de nuestros ficheros van a ser todos módulos commonJS, que limitan de por sí el ámbito de sus variables.

Lo primero que hace app.js es cargar un módulo llamado ModulePaths. Aunque esto no es obligatorio y no lo verás en todas las apps, es una costumbre que he puesto en práctica y que me ha demostrado tener varias ventajas. De momento, basta saber que ModulePaths contiene todas las sendas y nombres de ficheros del proyecto para no tener que recordarlos.

A continuación, cargo el módulo TabGroup (explicado más adelante). La línea 9 crea una instancia del módulo y finalmente se da la orden de abrir el tabGroup. Mucho ojo a las mayúsculas y minúsculas. Es una buena costumbre cargar los módulos en variables con mayúsculas (TabGroup) y las instancias de módulos con minúsculas (tabGroup).

app/ui/TabGroup.js

Este módulo devuelve una instancia de Titanium.UI.TabGroup, ya adaptada a nuestras necesidades. El hecho de poder cargar un componente de Titanium, modificarlo y ampliarlo a nuestro gusto y devolverlo como un componente nuevo, es tremendamente útil y lo desarrollaré a fondo en próximas entregas.

En todos mis módulos siempre lo primero que hago es cargar ModulePaths, a continuación defino los módulos que voy a usar en este módulo y finalmente se implementa el módulo desde module.exports.

	var Mods = require('/ModulePaths'); //load module paths

	var Window1 = require(Mods.WINDOW1),
	Window2 = require(Mods.WINDOW2),
	Window3 = require(Mods.WINDOW3);

	module.exports = function(_args) {


	var tabGroup = Ti.UI.createTabGroup();

	var win1 = new Window1();

	var win2 = new Window2();

	var win3 = new Window3();


	var tab1 = Ti.UI.createTab({
	window: win1,
	title:'Window 1',
	icon:'KS_nav_ui.png'
	});

	var tab2 = Ti.UI.createTab({
	window: win2,
	title:'Window 2',
	icon:'KS_nav_views.png'
	});

	var tab3 = Ti.UI.createTab({
	window: win3,
	title:'Window 3',
	icon:'KS_nav_ui.png',
	});


	tabGroup.addTab(tab1);
	tabGroup.addTab(tab2);
	tabGroup.addTab(tab3);


	return tabGroup;
	};

view raw

TabGroup.js

hosted with ❤ by GitHub

En este caso, declaro las tres ventanas que voy a necesitar en el proyecto (líneas 3-5) y defino el módulo en sí mismo con module.exports. Cada ventana Window1, Window2 y Window3 tiene un fichero .js donde se implementa su código. Más abajo muestro su contenido.

Línea 10, creo el tabGroup de titanium. Líneas 12-16 creo una instancia de cada una de las ventanas, líneas 19-40, creo los tabs del tabGroup, asigno las ventanas, títulos e iconos y finalmente devuelvo el tabGroup con todo listo para ser abierto.

app/ui/Window1.js

Las tres ventanas son prácticamente iguales, así que sólo explico la primera.

	module.exports = function(){

	var win = Ti.UI.createWindow({
	backgroundColor:'#fff',
	title: 'win 1'
	});


	var lbl = Ti.UI.createLabel({
	text:'This is Window 1',
	color:'#333'
	});

	win.add(lbl);

	return win;

	}

view raw

Window1.js

hosted with ❤ by GitHub

Es una ventana muy sencilla con una etiqueta. Como este módulo no tiene dependencias externas, no necesito llamar a ModulePaths ni ningún otro módulo. Simplemente crea una ventana de Titanium, le añade una etiqueta y devuelve la ventana.

Una de las ventajas de programar de esta manera, es que este módulo no se preocupa de cómo va a ser usado o por quién. En este caso, Window1 es instanciado por TabGroup en su línea 12, pero perfectamente nos la podríamos llevar a otro proyecto y reutilizarla sin a penas cambios.

ModulePaths.js

Como decía antes, el uso de un fichero índice de todos los ficheros del proyecto no es obligatorio. Perfectamente podríamos haber llamado cada ventana por su senda en TabGroup de este modo

1	var Window1 = require('/app/ui/Window1')

Sin embargo el uso de ModulePaths tiene varias ventajas.

Primero, que a medida que nuestro proyecto crezca, no necesitaremos recordar todas las sendas y nombres de archivo, sólo un identificador que asignaremos a cada módulo.

Segundo, que en proyectos complejos, podremos cambiar una versión de un fichero por otra, simplemente cambiando el nombre en ModulePaths. Por ejemplo, si tenemos un componente llamado VideoPlayer y queremos hacer pruebas con un fichero distinto sin modificar todo el proyecto, cambiaremos la senda en ModulePaths a un fichero nuevo (por ejemplo, VideoPlayerTest.js) y todo el proyecto cogerá esta referencia.

Tercero, más de una vez ocurre que hay que cambiar la estructura de carpetas de un proyecto. Si esto ocurriera, podemos mover los ficheros tranquilamente y después tan sólo tenemos que actualizar este fichero, y no cada módulo del proyecto.

Una última ventaja, si piensas desarrollar para mobile web, es que las sendas en esta plataforma no pueden empezar con la barra /, cosa que sí ocurre en el resto de plataformas. Trabajando con ModulePaths, podemos gestionar fácilmente estas diferencias.

	//avoid initial slash in paths under mobileweb platform

	var firstSeparator = (Ti.Platform.name === 'mobileweb') ? '' : '/';

	var ui = firstSeparator + 'app/ui/';

	module.exports = {
	TABGROUP: ui + 'TabGroup',
	WINDOW1: ui + 'Window1',
	WINDOW2: ui + 'Window2',
	WINDOW3: ui + 'Window3',

	STYLES: ui + 'Styles'

	}

view raw

ModulePaths.js

hosted with ❤ by GitHub

Como ves, el fichero únicamente asigna una senda a una clave que después es la que llamamos desde los módulos (por ejemplo Mods.WINDOW1 o Mods.TABGROUP).

Y para terminar…

Te recomiendo que vuelvas al código de app.js y vuelvas a leerlo desde el principio, ahora que ya sabes lo que contiene cada módulo te resultará más fácil entenderlo. El objetivo es dividir el código en partes funcionales lo más pequeñas posibles, lo que te permitirá crear código que reutilizarás con más facilidad en tus proyectos y mejorarán cuanto más los uses.

Y esto es todo! Puedes descargar el proyecto completo desde mi github en https://github.com/jaraen/TabGroupTemplate

App funcionando en el simulador de android

App funcionando en el simulador de iPhone

App funcionando en el navegador

CommonJS para Titanium

J. Rayon — Wed, 11 Jul 2012 12:19:11 +0000

CommonJS es un estandar de facto que permite encapsular código JavaScript en “módulos” que utilizaremos para crear nuestros propios componentes y librerías.

Con encapsular me refiero a la habilidad de crear una “burbuja” con código que tiene su propio ámbito de variables, de manera que ninguna de las que definamos en su interior contamina el ámbito global. En otro artículo hago una breve explicación de porqué es malo contaminar el ámbito global y como evitarlo. commonJS supone un nivel más de control sobre el ámbito de las variables.

El programador define el interfaz del módulo (las funciones y variables “públicas” a las que se podrá acceder desde fuera), de modo que para usarlo sólo tendremos que preocuparnos por conocer este interfaz y no lo que ocurre en su interior.

El buen uso de los módulos CommonJS facilita la reutilización de componentes entre proyectos, hace la trazabilidad más sencilla y obliga a estudiar mejor la interdependencia entre partes del proyecto.

Antes de continuar, si no sabes cómo se crean los objetos en JavaScript o quieres dar un repaso a las principales peculiaridades del lenguaje, echa un vistazo a los dos tutoriales de introducción a JavaScript para Titanium. Están aquí: 1 y 2

¿Que pinta tiene un modulo commonJS?

Se trata de un fichero JavaScript (.js) en el que encontraremos una serie de funciones y variables y un objeto especial llamado exports (no hay que definirlo, ya existe per sé).

Dentro del módulo pondremos todo nuestro código, pero sólo el que sea añadido a exports será accesible desde fuera.

TestModule.js:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

//Estas variables están disponibles en el módulo, pero no fuera de él
var variablePrivada1, varPrivada2, varPrivada3;

//este método sólo es visible dentro del fichero .js
function metodoPrivado(){

}

//este método es visible dentro y fuera del fichero
//por ser declarado como parte de exports
exports.metodoPublico = function(){

}

exports.saluda = function(){

alert('hola');

}

//Podemos convertir un método de privado a público añadiéndolo a exports
//Ojo, no ponemos parentesis, ya que lo que devuelve no es el resultado de metodoPrivado, si no la función en sí

exports.metodoYaNoEsPrivado = metodoPrivado;

//Y lo mismo con una propiedad

exports.propiedadPublica = variablePrivada1;

Ciclo de ejecución

Un aspecto importante a tener en cuenta es que un módulo commonJS sólo se interpreta la primera vez que es invocado. Esto implica varias cosas:

- Primero, que la carga de los distintos módulos se retrasa hasta que son necesarios, lo que hace que el arranque inicial suela ser más rápido

- Segundo y más importante: las variables que se declaren fuera de cualquier función del módulo tendrán un comportamiento estático (en el ejemplo, anterior, las declaradas en la línea 2). Solo se inicializan la primera vez y el resto de veces que invocamos al módulo no se inicializan de nuevo, conservando su último valor asignado. Aunque esto puede ser confuso al principio, es tremendamente útil a la hora de compartir información entre distintas partes del proyecto sin necesidad de usar variables globales.

Llamada desde Titanium

Para cargar un módulo commonJS desde Titanium utilizamos la orden require()

Dado un fichero TestModule.js que se encuentre en el raíz de nuestro proyecto (en la carpeta resources), lo cargaremos así (ojo, al hacer require no se pone la extensión del fichero)

1
2
3
4
5
6
7
8
9

var myTestModule = require('/TestModule');

//Podemos consultar una propiedad del módulo

Ti.API.info(myTestModule.propiedadPublica);

//y ejecutar sus métodos públicos

myTestModule.saluda();

Esta orden carga el módulo en una variable cuyo nombre, en este caso ‘myTestModule’, lo asignamos a nuestra conveniencia. Una vez cargado, myTestModule contiene el objeto exports que hemos ido implementando en la definición del módulo.

Patrones de uso

Existen varios patrones de uso de los módulos commonJS que se repiten confrecuencia en Titanium y conviene conocer desde un principio. Comentaré dos de ellos que usaré a menudo en próximos artículos.

Un Componente instanciable (o sea, reusable)

Una instancia es una copia de un objeto que tiene su propio ciclo de vida. Esto permite que varias instancias puedan sobrevivir simultáneamente con ciclos de vida diferentes e incluso con comportamientos diferentes sin depender necesariamente una de otra. Ejemplos de instancias son la mayoría de componentes UI de Titanium: un botón, un label, una ventana… En este caso, querremos que cada instancia del objeto no colisiones con el resto.

Supongamos que queremos crear un componente propio que extienda de uno existente. Lo “envolveremos” en un módulo commonJS, añadiéndole las nuevas funcionalidades. Como ejemplo, vamos a crear un botón especial con dos estados, de manera que su color cambie cada vez que se pulsa el botón:

SwitchButton.js:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

module.exports = function(args){

//inicializa args para asegurarse que existe
var args = args || {};
args.colorOn = args.colorOn || ''; //si no se ha definido colorOn, asigna ''
args.colorOff = args.colorOff || '';

//Creamos el botón nativo de Titanium
var btn = Ti.UI.createButton(args);

//quitamos la imagen de fondo, en iOS es necesario para ver bien el color
btn.backgroundImage = 'transparent';

//método privado que determina la imagen de fondo del botón
function setColor(){
btn.backgroundColor = btn.value ? btn.colorOn : btn.colorOff;
}

//al hacer click, cambia la imagen
btn.addEventListener('click', function(e){
btn.value = !btn.value;
setColor();
});

//inicializa la imagen del botón
setColor();

return btn;
};

Para utilizar nuestro componente en Titanium, deberemos crearlo con el operador new

app.js:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

var win = Ti.UI.createWindow();

//Cargamos el módulo en un objeto "Clase"
var SwitchButton = require('SwitchButton');

//creamos nuestra instancia de la clase SwitchButton:
var btn = new SwitchButton({
width:180, height:35, title:'hazme click!',
colorOn: '#fff',
colorOff:'#999'
});

win.add(btn);
win.open();

Con esta técnica, podríamos añadir tantos botones como fueran necesarios, cada uno con sus características de tamaño y color y cada uno con sus propios addEventListeners.

Tienes un ejemplo más avanzado de SwitchButton usando imágenes de fondo y disparando un evento propio en mi proyecto TitanTricks

Patrón de configuración

A menudo ocurre que distintas partes de la aplicación deben compartir una serie de datos “estáticos” sobre la aplicación. Cosas como el nombre de la app, la url de un servicio web al que debe acceder o distintas configuraciones de estilo.

Config.js

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

var config = {

name: 'miApp', //nombre de la aplicacion

autoPlay: false, //iniciar video automáticamente

//Start and finish paths with a slash '/'
photosPath: '/content/photos/',

imagesPath: '/content/imgs/',

songsPath: '/content/audio/',

serverUrl: 'http://www.myserver.com/webservice.php'

};

//decimos al módulo que el objeto exports es igual al objeto config
module.exports = config;

Como puedes ver, en vez de extender exports con una propiedad config, en este caso directamente asignamos config al módulo. Esta técnica es igual de válida que la de extender exports. Lo único que no debes hacer nunca dentro de un mismo módulo es mezclar ambas técnicas: o extiendes exports o igualas module.exports a un objeto tuyo. La experiencia te dirá cuando usar una u otra, te he mostrado un ejemplo de cada caso para que te suene a la hora de diseñar tu propio módulo.

Ahora, en nuestra aplicación, podremos invocar al módulo Config sin necesidad de instanciarlo:

App.js

1
2
3
4
5
6
7

var Config = require('Config');

//Podemos usar Config sin necesidad de instanciarlo, porque exports ya contiene las propiedades que esperamos

alert('Bienvenido a ' + Config.name);

Ti.API.info('Las fotos están en ' + Config.photosPath);

Este tipo de patrón también es muy útil para separar los estilos de la programación pura. Podemos tener un fichero de estilos fácilmente reutilizables y modificables al que invocar desde cualquiera de nuestros módulos. Podríamos, por ejemplo, cambiar los colores de todas las ventanas sólo con cambiar el color en este fichero.

Styles.js

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

//Cargamos el módulo Config en nuestro módulo Styles
var Config = require('Config');

module.exports = {

Window: {

backgroundColor:'#fff'

},

LabelTitle: {

top:0, width:Ti.UI.FILL, height: 40,
text: Config.name,
backgroundColor:'#000',
color:'#fff',
font:{fontSize:24}

}

}

Y ahora en App.js…

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

//Cargamos los módulos necesarios
var $$ = require('Styles');
var LabelTitle = require('LabelTitle');
var SwitchButton = require('SwitchButton');

var win = Ti.UI.createWindow($$.Window);

var lblTile = new LabelTitle($$.LabelTitle);

//creamos nuestra instancia de la clase SwitchButton:
var btn = new SwitchButton({
width:180, height:35, title:'hazme click!',
colorOn: '#fff',
colorOff:'#999'
});

win.add(lblTitle);
win.add(btn);

win.open();

Me gusta usar $$ siempre como nombre del módulo de estilos. Es fácil de recordar, rápido de escribir y recordar (manía que adquirí del estilo de programación de tweetanium, una app que hizo escuela en los principios de Titanium). El hecho de que sean dos símbolos $$ no tiene ninguna otra implicación como nombre de variable.

Esto es to, esto es todo amigos

Estos dos patrones son suficientes para empezar a montar la arquitectura de la aplicación. Por supuesto que hay más e intentaré mostrarlos en sucesivos tutoriales.

Mi objetivo, una vez superados los conceptos básicos de JavaScript y sabiendo qué son y cómo funcionan los módulos commonJS, es mostraros como crear una arquitectura sólida, escalable y segura para una aplicación móvil con Titanium. En la próxima entrega crearemos una plantilla para comenzar todas nuestras aplicaciones desde una base e iremos viendo como superar los distintos obstáculos que nos encontraremos en la comunicación entre componentes. Siempre, por supuesto, intentando seguir el manual de buenas prácticas.

En entregas posteriores, desarrollaré algunos problemas típicos de programación, como la llamada a métodos asíncronos, componentes UI avanzados, optimización de código y lo que se me vaya ocurriendo (se aceptan retos, ruegos y sugerencias).

Hasta entonces, os recomiendo probar y desmenuzar la app TitanTricks, un proyecto iOS+Android de demostración/experimentación con Titanium. También existe TitanTricksMobileWeb, para su versión web.

¿Te interesa Titanium y JavaScript? Sígueme en @jrayon