Tutorial cómo crear temas de apariencia (themes) Liferay paso a paso desde cero

Google+

Desde entrepixels, queremos compartir nuestra experiencia en el desarrollo de temas de apariencia de Liferay explicando cómo crear un tema (theme) desde cero paso a paso. No es fácil encontrar mucha documentación sobre este tema en español, por lo que creemos que os puede resultar interesante.

Nosotros trabajamos habitualmente sobre Windows, pero explicaremos el proceso de forma que el contenido sea perfectamente válido para aquellas personas que trabajen bajo Linux o MAC. No nos basaremos ni en Eclipse, ni en Netbeans, ni en Liferay IDE.., para que cada uno pueda trabajar con la herramienta que se sienta más cómodo. Sólo necesitaremos tener instalado en nuestro equipo Java, Apache Ant y descargarnos una versión de Liferay con su plugin-sdk asociada. Para el ejemplo trabajaremos con Liferay 6.2, que es la última versión a día de hoy, y nosotros tenemos instaladas las java 1.7 y el apache ant 1.9.3. Para aquellos que no estéis muy familiarizados con la instalación y configuración de Java y Ant, os dejamos un par de enlaces de cómo configurar las variables de entorno para java y para apache ant.

Una vez tengamos funcionando las java y el apache ant, nos crearemos una carpeta (Por ejemplo "Liferay6.2"), donde copiaremos y descomprimiremos tanto nuestro Liferay, como nuestra sdk para plugins. Para evitarnos tener que configurar ficheros, es importante que separemos en dos carpetas el Liferay y la sdk de los plugins y las llamemos "bundles" y "plugins" respectivamente. En realidad el nombre importante es "bundles", la carpeta de plugins puede llamarse de otra forma, pero esta es la nomenclatura y estructura de carpetas habitual. Con ello evitaremos tener que configurar el "build.properties" de nuestros plugins con las rutas de Liferay. Nos quedará algo como esto:

Una vez tengamos nuestro Liferay con sus carpetas bien organizadas, procedemos a arrancar nuestro portal. Nosotros solemos trabajar con un Liferay bajo tomcat, por lo que nos vamos a nuestra carpeta "bundles->tomcat->bin" y ejecutamos el "startup" (.bat o .sh dependiendo de la plataforma bajo la que estemos). Cuando haya arrancado procedemos a crear nuestro nuevo tema de apariencia (theme) de Liferay. En entrepixels utilizamos la línea de comandos para crear nuestros temas de apariencia. Si utilizadas la IDE de Liferay hay opciones de menú específicas para ello, pero a nosotros nos resulta más cómodo hacerlo "a mano", pues tú tienes el control de todo. Bien, abrimos nuestra línea de comandos y nos situamos sobre la carpeta "plugins->themes". Procedemos a ejecutar el siguiente comando: create id_tema "nombre_tema", donde id_tema será el identificardor que queramos darle a nuestro tema y nombre_tema será el nombre que se muestre a la hora de utilizarlo en el portal.

Para la versión Liferay 6.2 la primera vez que creas un tema tarda un poquito, independientemente de lo potente que sea tu ordenador. Una vez pasada esta primera vez los temas se crean de forma mucho más ágil. Si todo ha ido bien, nos encontraremos con el siguiente mensaje en línea de comandos: "BUILD SUCCESSFUL Total Time: x seconds" y dentro de nuestra carpeta "plugins->themes" nos aparecerá una nueva carpeta con el nombre "id_tema-theme". Si no ha ido bien, lo más probable es que no tengas bien configuradas las variables de entorno de ant.

Ya tenemos nuestro nuevo tema de Liferay creado. Veamos ahora los primeros pasos a seguir. En primer lugar tenemos que decidir en qué tema nos vamos a basar, es decir, cuál va a ser nuestro tema padre. Para ello vamos a la carpeta raíz de nuestro tema y abrimos el fichero "build.xml".

Podemos heredar de cualquier tema que tengamos desplegado en nuestro Liferay, pero habitualmente lo haremos del classic, welcome (versión 6.2), _styled o _unstyled. Si heredamos del classic o el welcome, nuestro nuevo tema inicialmente tendrá visualmente un aspecto igual al del tema que hayamos heredado. Heredar de estos temas puede ser útil para hacer pruebas, o alguna demo rápida (o que casualmente queramos un tema muy parecido a alguno de ellos), pero lo más normal es que no sea así. Si lo hacemos para temas completamente diferentes nos pasaremos todo el rato sobreescribiendo los estilos del tema del que estemos heredando. Nosotros personalmente heredamos la mayoría de las veces del tema _styled, que es un tema que viene prácticamente “plano”, solamente tiene los estilos básicos de Liferay relacionados con configuraciones, el dock, etc. Por otro lado podemos heredar del tema “_unstyled” que nos dejará un Liferay completamente “desnudo”, es decir, habría que maquetarlo absolutamente todo. Veamos con una captura después de heredar del “_styled” y del “_unstyled” respectivamente para ver de lo que hablamos.

Como podemos ver el tema styled nos ayuda con la maquetación básica del portal y su funcionalidad, y a su vez apenas lleva estilos que haya que ir sobreescribiendo. Lanzarse a heredar del tema _unstyled sólo lo recomendamos para aquellos que necesiten un lavado de cara completo de Liferay, en el que incluso haya que cambiar los estilos que sólo va a ver el administrador o gestor de contenidos.

Ya tenemos decidido de qué tema vamos a heredar. Supongamos que heredamos del styled. ¿Cuál es el siguiente paso? Ahora vamos a compilar nuestro tema y desplegarlo en el portal. Para ello abrimos línea de comandos y nos situamos sobre la carpeta raiz de nuestro tema e introducimos el siguiente comando: ant clean deploy . El "clean" es opcional pero recomedable pues en alguna ocasión nos puede evitar problemas de que no se sobreescriban bien los cambios que vayamos haciendo en nuestro tema. Si todo ha ido bien nos encontraremos con algo como sigue.

Una vez ha terminado la compilación, en nuestra ventana del tomcat de Liferay veremos que ha detectado la presencia de un nuevo tema y procede a desplegarlo. Cuando termine nos encontraremos con un mensaje como este.

Si en alguno de estos puntos hemos tenido problemas de compilación o despligue miraremos los errores que nos pueda dar la tarea del ant o el tomcat al desplegar. El error más habitual podría ser que no hayas seguido la estructura y nomenclatura de carpetas (plugins y bundles) mencionadas anteriormente en este artículo.

Ya tenemos nuestro tema desplegado, y al realizar las tareas del ant nos han aparecido nuevas carpetas y ficheros en el tema. Estos se copian automáticamente del tema que hayamos heredado. Vamos a ver cómo nos aparece el tema en nuestro portal, y algunos detalles que debemos pulir antes de seguir adelante y explicar la estructura de un tema por dentro.

Podemos ver que aparece nuestro tema de Liferay, pero carece de thumbnail y el autor del mismo aparece como Liferay. Vamos proceder a cambiar esto. Para ello vamos a personalizar 4 aspectos.

• Thumbnail del tema.
• Screenshot del tema.
• Favicon del tema.
• Autor del tema.

Para el screenshot, el thumbnail crearemos dos dos .png con el aspecto final de nuestro portal: screenshot.png (el ancho que queramos, 1024px recomendado) y thumbnail.png (de 150px de ancho recomendado). Además tendremos nuestro favicon.ico personalizado. Para ubicarlos iremos a la carpeta “docroot->diffs”, crearemos una nueva carpeta dentro llamada “images” y allí los colocaremos. En la próxima compilación y despliegue del tema (ant clean deploy) aparecerán cambiados (el favicon es posible que se quede cacheado una buena temporada).

Para terminar con los cuatro puntos mencionados anteriormente debemos modificar el fichero “liferay-plugin-package.properties“. Para ello crearemos dentro de la carpeta "docroot->diffs" una nueva carpeta llamada "WEB-INF" en la que duplicaremos el fichero "liferay-plugin-package.properties" que nos podemos encontrar en la carpeta "docroot->WEB_INF" de nuestro tema. Editaremos este fichero duplicado (el que hemos copiado en "docroot->diffs->WEB-INF" no el original) con cualquier editor y pondremos nuestros datos.

Una vez modificado al seleccionar nuestro tema ya nos aparece todo correctamente.

Una vez llegados a este punto ya tenemos un tema creado por nosotros mismos con el que poder empezar a trabajar. A continuación explicaremos la estructura básica de un tema de Liferay. Pero antes hay un tema importante que hay que tener en cuenta. Siempre vamos a trabajar y a modificar ficheros dentro de la carpeta diffs (dentro de docroot). En la carpeta ráiz de docroot tenemos las carpetas base del tema del que hemos heredado. Si trabajamos sobre ellas, cada nueva compilación nos machacará los cambios que hayamos hecho con el código del tema que hayamos heredado. Si queremos cambiar cualquier fichero debemos crear la misma estructura de directorios dentro de la carpeta diffs y sobreescribir el fichero que deseemos. Sólo así nuestros cambios tendrán efecto. Por poner un ejemplo concreto, si quiero sobreescribir la "custom.css" del tema del que he heredado, debería crear dentro de diffs la carpeta "css", copiar el fichero custom.css y a partir de ahí comenzar a realizar los cambios oportunos. En este punto os recomendamos hacer algunas pruebas para que veáis de primera mano los resultados.

A continuación vamos a explicar brevemente la estructura de carpetas y ficheros que contienen a la hora de manejar un tema de apariencia (theme) de Liferay. Empezamos, en primer lugar con las css. El tema styled de Liferay viene por defecto con las siguientes css.

Como se puede observar, los nombres de las css, si estamos familiarizados con Liferay, son bastante intuitivos. Por norma general sólo modificaremos dos ficheros respecto a los originales (aunque por supuesto podremos incluir más). Los ficheros a modificar serían main.css y custom.css. El primero de ellos es el que incluye con "imports" todas las css que se utilizan. Podemos necesitar modificarlo para quitar alguna css de las que se importan (poco habitual), o para añadir ficheros css nuevos. Por otro lado “custom.css” es un fichero originalmente vacío, que se importa en último lugar en la main.css y es donde meteremos nuestro código personalizado. Al ser importado en último lugar en la “main.css” los estilos sobreescribirán cualquier clase definida anteriormente en cualquier otro fichero.

La carpeta imágenes tiene poco que explicar. En ella se almacenan las imágenes que vienen con el tema que hayamos heredado. Si queremos sobreescribir alguna imagen simplemente hemos de buscarla, replicar dentro de la carpeta diffs aquella estructura de carpetas donde se encuentre y poner nuestra nueva imagen con el mismo nombre que la imagen que queramos machacar. Es común y buena práctica crearnos una nueva carpeta (o varias) dentro de “images” donde metamos la imágenes nuevas que vayamos a usar para maquetar nuestro portal.

Pasamos ahora a la carpeta templates. En ella nos vamos a encontrar en ficheros velocity las diferentes estructuras html del portal. Es donde tendremos que tocar si queremos modificar la estructura HTML de nuestro portal.

El fichero init_custom.vm si no programamos velocity no lo tocaremos para nada. Se utiliza para declarar variables de dicho lenguaje que posterioremente queremos utilizar en cualquiera de los otros ficheros velocity. El fichero portal_normal.vm es el que contiene el marcado HTML con la estructura general de todas las páginas de la parte pública del portal. Es decir, cabecera con sus elementos, cuerpo (sólo se define el contenedor), y pie de página.

Al que no esté acostumbrado se le hará un poco raro ver el lenguaje velocity metido entre el html, pero se le coge el truco rápido. Desde portal_normal.vm se hace la llamada a la navegación principal con el siguiente comando #parse (“$full_templates_path/navigation.vm”) que viene a ser lo equivalente a un import, en este caso del fichero navigation.vm que contiene el menú principal de navegación de Liferay. Dentro de la capa con id="content", dentro de la portal_normal.vm también se hace una llamada al contenido central correspondiente de cada página con los siguientes comandos.


#if ($selectable)
$theme.include($content_include)
#else
$portletDisplay.recycle()

$portletDisplay.setTitle($the_title)

$theme.wrapPortlet("portlet.vm", $content_include)
#end


Nos quedan dos plantillas velocity por ver. portlet.vm contiene la estructura HTML de cada uno de los portlets. Básicamente es un section con su encabezado, el menú de opciones de cada portlet y el contenido del mismo. Si necesitamos cambiar algo de su estructura HTML es aquí donde debemos tocar. Por último portal_pop_up.vm contiene la estructura HTML de los popups que nos encontramos dentro del portal.

Vamos por último con la última carpeta que vamos a analizar. Se trata de la carpeta js. En ella nos encontraremos con un fichero main.js. Este fichero se ejecuta siempre que se carga una página y nos viene preparado con tres funciones interesantes que podemos utilizar. Recordamos que Liferay desde su versión 6.0 viene con su propio framework javascript incrustado por defecto, Alloy UI (AUI).

Todo el código que metamos dentro de la primera función se ejecutará al cargar la página. Es equivalente a un jQuery(ready) y similar (no igual) al window.load() de javascript. El código que incluyamos en la segunda función se ejecutará cada vez que se cargue un portlet de la página actual. Por último aquel código incluído dentro de la tercera función se ejecutará después de que todos los portltes de la página estén cargados.

Si queremos añadir nuevos ficheros javascript a nuestro portal, lo haremos directamente en la template portal_normal.vm, como si lo estuviesemos incluyendo en cualquier otro tipo de proyecto "<script src="…>

Y hasta aquí este tutorial de cómo crear temas de apariencia (themes) de Liferay paso a paso desde cero. Esperamos que os haya servido de utilidad.