producto añadido a tu cesta!

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

  • 4
  • 17 marzo, 2014
Liferay

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:

Captura de Estructura de directorios de Liferay

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.

Captura desde línea de comandos para crear un theme de Liferay

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.

Creación correcta de theme Liferay desde línea de comandos

Nueva carpeta con nuestro nuevo theme Liferay

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".

carpeta raíz tema de Liferayaspecto del fichero build.xml tema de Liferay

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.

heredando del tema _styled de Liferayheredando del tema _unstyled de Liferay

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.

compilamos tema de apariencia de Liferay
compilación correcta tema de apariencia de Liferay

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.

Despliegue tema de apariencia de Liferay correcto

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.

Seleccionar nuevo tema de Liferay

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).

Modificar thumbnail y favicon de un tema de Liferay

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.

Aspecto del fichero liferay-plugin-package.properties del tema de Liferay

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

seleccionar tema de Liferay personalizado

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.

Es importante realizar los cambios sobre la carpeta diffs

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.

Css en un tema de apariencia de Liferay

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.

Estructura main.css de Liferay Custom css de Liferay originalmente vacía

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.

Ficheros de la carpeta template de Liferay

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.

Ejemplo de portal_normal.vm de Liferay

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).

Código javascript del mail.js de Liferay

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.

17 Comentarios

  • Ana dice:

    Estupendo tutorial, de los mejores que se pueden encontrar de Liferay.

  • Jhoan dice:

    Buena tarde me parece muy interesante el tutorial he despejado muchas dudas, pero al momento de ejecutar mi tema me muestra este error, agradecería su ayuda.
    Gracias.

    Se ha producido un error inesperado del sistema.

    javax.servlet.jsp.JspException: com.liferay.portal.kernel.template.TemplateException: Unable to process template Prueba-theme_SERVLET_CONTEXT_/templates/portal_normal.ftl

  • jorge dice:

    Tengo una duda con respecto a velocity / freemarker, estoy trabajando con la última versión de liferay (6.2) que ha reemplazado todas las plantillas de velocity y ahora utiliza freemarker. Pasa que el ide para esta versión de Liferay (Eclipse Luna) tiene el editor de velocity deprecated y no he podido encontrar un plugin que me permita editar los archivos .VM. Cuando instalas liferay existe la posibilidad de escoger tu lenguaje por defecto entre velocity y freemarker pero es imposible (yo al menos no encontrado la forma) de editar archivos .vm con el eclipse incluído en el bundle de esta versión.

    Cualquier guía se agradecerá mil. Muchas gracias !

    • entrepixels dice:

      Hola Jorge.

      Nosotros no trabajamos con el IDE de Liferay, generalmente generamos los plugins necesarios con ant o maven y editamos los ficheros con el editor que más nos convenga (Dreamweaver, Notepad++, etc..).
      No nos consta que Liferay 6.2 haya sustituido velocity por freemarker, de hecho nosotros seguimos trabajando con velocity en nuestros temas de apariencia.

      A ver si alguien más ha tenido tu problema y nos puede arrojar un poco más de luz.

      Muchas gracias por pasarte!

      Un saludo!

  • José dice:

    Buenas tardes,
    estoy siguiendo los pasos del manual, he instalado todo y creado las variables sin problemas. Arranco bien el Liferay.
    Ahora bien, cuando quiero crear un tema y accedo al directorio themes y ejecuto el comando: create temaPrueba “Ejemplo uno”, la consola me devuelve el mensaje:
    “create” no se reconoce como un comando interno o externo, programa o archivo por lotes ejecutable.
    Me podéis decir a qué se puede deber…? Necesito algo de ayuda.
    Un saludo y mil gracias por el manual

    • entrepixels dice:

      Hola José.

      Tiene toda la pinta de que no tienes bien instalado “apache ant”. Requiere descargárselo (https://ant.apache.org/bindownload.cgi), descomprimirlo y meter sus variables de entorno correspondientes (http://eracleo.blogspot.com.es/2013/05/configuracion-e-instalacion-de-ant.html).

      Una vez instalado cierra la consola y vuelve a abrirla para que coja los cambios. Si tienes bien instalado apache ant, deberías escribir “ant” en la línea de comandos y darte algún tipo de error del tipo “build.xml not found”. Si te sale algo del estilo “no se reconoce como un comando …” es que no ha quedado bien instalado el ant. En caso de que haya ido bien ya deberías poder ejecutar el “create”.

      Un saludo.
      Juanra

  • […] vamos a poder seguir desarrollando temas como veníamos haciendo hasta ahora con el plugins sdk (ver tutorial para desarrollo de temas de apariencia en Liferay6.2), podremos pasar a trabajar con herramientas mucho más […]

  • es posible de agregar temas con bootstrap 3 de forma natural?

    • entrepixels dice:

      Hola Alejandro. En Liferay 6.2 no es posible de forma fácil, pues lleva integrado bootstrap 2.3.2 y en el momento que importar las css de bootstrap 3 deja de funcionar todo. Se puede hacer alguna “trampa” para poder usar bootstrap 3 modificando su propia css haciendo que todos los estilos queden envueltos por otra capa (por ejemplo .bs3) que luego aplicarías en la capa “content” de Liferay (div id=”content” class=”bs3″). Esto limitaría el uso de bootstrap 3 solamente al contenido (no aplicaría a dockbar, menús de configuración, etc…). El proceso es tedioso y siempre existen pequeños conflictos entre clases a las que se aplican estilos de la versión 2.3.2 y la 3 que hay que ir ajustando. Respecto al javascript no da problemas.

      Si usas una versión anterior de Liferay no hay problema pues no lleva ningún bootstrap “de serie”. Para Liferay 7, en principio, tampoco habría problema aunque no hemos probado todavía. Espero que te hayamos podido resolver tu duda.

      En resumen, para Liferay 6.2 siempre que puedas evitarlo, no uses bootstrap 3.

      Un saludo!

  • Weena dice:

    Muuuchas gracias por aqui documentándome antes de comenzar un nuevo proyecto! Un post que se le aprovecha el 100%!

  • Hector dice:

    Hola, estoy buscando mejorar la imagen de mi portal liferay, agradecería me puedan referenciar algún colega para esta labor a hchaves@soluproperty.com

  • Iván Rodríguez dice:

    Hola!
    Antes de nada, muchas gracias por el tutorial. Viene muy claro.
    De todos modos, me he quedado en los pasos iniciales. Estoy en Kubuntu.
    He hecho lo siguiente:
    1) Descomprimir el zip de Liferay en /opt y meter las carpetas que aparecen en una sola (bundles)
    2) Descomprimir el zip de los plugins en la carpeta de Liferay (queda separado bundles y plugins)
    3) He hecho la instalación de Liferay con MySQL y todo perfecto (la administración va genial)
    4) He instalado ANT en /usr/local/ant”, declarado el ANT_HOME y el PATH
    ANT_HOME=”/usr/local/ant
    PATH=”$PATH:/usr/local/ant/bin”
    export ANT_HOME
    export PATH
    5) Me meto en la carpeta del liferay:
    cd /opt/liferay6.2-CE/plugins/themes
    6) Y al ejecutar el comando
    ./create.sh temaPrueba /”Tema de Prueba”/
    Me sale este error:
    Buildfile: /opt/liferay6.2-CE/plugins/themes/build.xml

    BUILD FAILED
    /opt/liferay6.2-CE/plugins/themes/build.xml:5: The following error occurred while executing this line:
    /opt/liferay6.2-CE/plugins/build-common-plugins.xml:5: The following error occurred while executing this line:
    /opt/liferay6.2-CE/plugins/build-common.xml:57: The following error occurred while executing this line:
    /opt/liferay6.2-CE/plugins/build-common-ivy.xml:137: Directory /opt/liferay6.2-CE-SAE/plugins/.ivy creation was not successful for an unknown reason

    ¿A que puede deberse dicho error?
    Muchas gracias.

    Total time: 0 seconds

    • entrepixels dice:

      Hola Iván.

      No solemos trabajar con Linux. Se me ocurre que pueden ser dos cosas: o bien algún problema de rutas (revisaría los ficheros que dan error por si hay alguna ruta incorrecta), o bien problemas de permisos de escritura en la carpeta.

      Un saludo.
      Juanra

Dejanos tu comentario !

Tu correo electrónico no será publicado