¿Cómo ejecutar código JavaScript después de que cambie de página en Liferay?

Bien sabido es que la interfaz de Liferay 7 fue transformada a una Single Page Application ó SPA -por sus siglas en inglés-. 

Los SPA son aplicaciones web que no precisamente hacen un redireccionamiento entre las páginas que contenga la aplicación, ya que la aplicación se carga una sola vez. Esto significa que la URL de nuestra aplicación no va cambiar de manera natural, eso también es manipulado manualmente (usualmente con un módulo de routing). Esto significa que si tu quieres ejecutar una bloque de código en común para todas las páginas, y dicho código lo añades en las configuraciones avanzadas globales, ya sea de public pages ó private pages, este código sólo será ejecutado la primera vez en que llegas a la aplicación.

Al darte cuenta de esto, es muy probable que pienses en poner este bloque de código en las configuraciones avanzadas de cada una de las páginas en donde deseas ejecutar ese código. Pero ¿qué pasaría si tuvieras un portal con diez páginas, y además manejas navegación de segundo nivel? Te darás cuenta de que esto no es mantenible, ya que cada vez que quieras modificar por alguna razón ese bloque de código, tendrás que hacerlo en todas las páginas donde agregaste ese código.

En las SPAs la manera de navegar entre páginas se le conoce como routing o enrutamiento. 

Algunos frameworks como Angular, Ember o Meteor han adoptado los principios de SPA, así que si ya has utilizado alguno de ellos, esto te debe ser familiar. Y bueno, Liferay 7 no es la excepción, ya que también tiene su manera de navegar entre páginas. 

Entonces, volviendo a nuestro problema inicial de cómo ejecutar un bloque de código en varias páginas sin tener que forzar un redireccionamiento y cargado de página por completo, en Liferay tenemos un objeto expuesto en el browser.

Este objeto tiene varias propiedades muy útiles, dentro de las cuales está nuestra SPA. Ésta propiedad nos ofrece otras propiedades donde podemos saber el tiempo de expiración de la cache de Liferay, notificaciones de usuario, paths que han sido excluidos, así como una propiedad llamada app

La propiedad app también tiene otras propiedades, pero para nuestro caso, nos importa la propiedad de events_, que como el nombre lo dice, cuenta con eventos que nos dicen en qué momento se ejecutan las siguientes acciones:

  • Comenzar a navegar entre las páginas
  • Antes de navegar
  • Al terminar de navegar

Con estos eventos, es suficiente para ejecutar nuestro código de manera exitosa al cambiar entre la diferentes páginas en nuestro SPA sin tener que recargar la(s) páginas.

Si has usado jQuery y sus eventos, esto te será familiar:

Lo anterior usa una función (on), la cual registra un evento y una acción a ejecutar a través de una función después de que se haya disparado el evento endNavigation.

Como puedes observar el evento endNavigation se dispara en el momento en que la navegación de nuestra SPA ha cambiado y terminado, es decir; imaginemos que te encuentras en la página Home te tu sito y en la navegación das un click a otra página llamada About Us, cuando la SPA haya terminado de llevarte de la página Home a la de About Us se ejecutará el código anterior.

Entonces, ahora ya sabes como ejecutar código JavaScript sin tener que recargar la página en Liferay 7.

No hay mucha documentación oficial sobre el objeto de Liferay 7 que está expuesto en el objeto global window, así que te recomiendo explorarlo un poco más para descubrir qué otras cosas podemos obtener de éste.

Importar Recursos en Liferay 7 desde el tema

Liferay provee a los desarrolladores de una herramienta que te fascilitará la importación de recursos como Pages, Structures, Templates, Applications Display Templates (ADTs), Web Content y Documents and Media a un Portal de Liferay.

Todo esto es posible gracias al modulo de importación de recursos de Liferay, mejor conocido como resource importer tool, la cual a traves del deploy de un Tema de Liferay hará toda la mágia.

Comencemos por saber que todos los recursos que deseemos importar desde el tema deben estar bajo el folder [theme-name]/src/WEB-INF/src/resources-importer.

Todos los assets a importar deben estar bajo la siguiente estrucutura de carpetas:

En la estrucutura anterior podemos notar que los recursos a importar estan separados por folders.

Estructuras

Las estructuras son aquellas que nos dan el esqueleto de campos ó elementos disponibles para crear contenido, campos que pueden ser de tipo texto, fecha, documento, html entre algunos otros.

Para poder añadir estos campos con el resource importer desde el tema, debemos crear un archivos con extensión JSON, el cual debe contener una propiedad array  (availableLanguageIds) para los idiomas, de igual manera tendrá una propiedad que define el idioma por defecto (defaultLanguageId) y para añadir nuestros campos tendremos nuevamente una propiedad array (fields), la cual contendrá un objecto por cada campo. Cada objeto tendrá el label, el name, el tipo de dato, propiedades booleanas que nos en las que definimos si el campo es repetible, si es indexable, si queremos mostrar el label entre algunas otras. Para tener un poco más claro esto, dale un vistazo a la estructura siguiente:

Plantillas (Templates)

Bien, ahora te preguntarás como puedes obtener la información de de los campos de una estructura, bueno, para eso tenemos los templates, los cuales fungen como plantillas para renderear los campos de una estrucutura.

Para añadir templates al resource importer, debemos crear un folder el cual debe de coincidir en nombre con el nombre del folder que va a contener a los articles, como por ejemplo:

Estos pueden ser escritos con sintaxis de Velocity ó Freemarker (el recomendado por Liferay) los cuales son motores para la generación de plantillas, estos separan la lógica de la vista y son server site, es decir, se compilan de lado del cliente.

En el código anterior tenemos un template el cual obtiene el título de una noticia, el autor, el resumen (summary), el cuerpo (body), el thumbnail y una imagen. Todos estos campos son puestos entre tags de HTML para darle cuerpo y forma a nuestras noticias.

Documentos

Para el caso del directorio documents pudes agregarlos directamente bajo este los recursos de tipo imágen, video ó algún otro documento como PDF, XLS, DOCX, etc. o bien, puedes crear subfolders para separar y tener mejor ordenados estos tus ducumentos.

Contenido Web (Articles)

Para añadir contenido debes agregar un folder contenedor dentro de articles. Al igual que con los documentos, tu puedes agregar un folders extra para ordenar de mejor manera tu contenido.

Por ejemplo un folder llamado news, entonces nos quedaría algo así:

../journal/articles/web content/news

Por otro lado el contenido que deseemos añadir debe estar en formato XML.

Como podemos ver en el bloque anteior, todos los elementos que añadimos en nuestra estructura son nodos de XML con que agregan el contenido a traves del tag <dynamic-element> que a su vez contiene el tag <dynamic-content>. Dentro de este ultimo tag tenenos una notación particular ![CDATA[ …]] dentro de la cual va el contenido, como el summary, body y las imágenes. 

El tag <dynamic-element> tiene como atributos el nombre del elemento, el tipo y el tipo de indexamiento, los cuales fueron proporcionados en el JSON de la estrucutura.

El tag <dynamic-content> tiene como atributos el idioma y el tipo de contenido.

Aplication Display Templates (ADTs)

Los Applications Display Templates o ADTs son utiles para renderear un set de articles, los cuales pueden ser iterados usando sintaxis de Freemarker. Para poder agregar ADTs a nuestro resource importer requerimos de un folder llamdo asset_entry el cual debe estar bajo application_display. 

En la imágen anterior se puede ver la estructura de directorios explicada anteriormente. A continuación el código del ADT News and Events Archive.

 

Sitemap

Pareciera que ya tenemos todo listo para importar nuestros recurso, pero no, aún falta algo muy importante, el archivo sitemap.json 

En este archivo especificaremos las páginas que deseamos crear, los layout templates que queremos usar para cada página, el mapping de nuestro contenido web, los assets y la configuración de los portlets la cual es porporcionada por el tema.

La primera propiedad de nuestro archivo json, es un array con el tipo de páginas que queremos incluir en el importer, publicPages (páginas publicas) ó privatePages (páginas privadas). Posteriormente un objeto que contiene porpiedades que definen el friendlyURL (url amigable), layoutTemplateId (plantilla a utilizar en nuestra página), name (nombre de nuestra página). También contiene un array de columnas (columns) donde añadiremos nuestros portlets (esto no significa que las columnas sean el layout, para eso esta el layoutTemplateId) los cuales son añadidos en la propiedad portletId y portletPreferences, en está ultima propiedad es donde definimos configuraciones para nuestro portlet, por ejempo, si tenemos un Asset Publisher Portlet, este tiene configuraciones como el tipo de ADT con el que va a presentar los articles, configuración de estilos con el portlet decorator, el comportamiento del los links para ver el contenido en otra página o en el mismo portlet entre algunas otras.

Vamos a imaginar que deseamos crear cuatro páginas publicas llamadas home, my workspace, my life, about us, las cuales usarán un layout template de  una columna, y en el que cada página solo contendrá un portlet, en este caso el asset publisher portlet. Para hacer un poco más ulustrativa esta idea, a continuación el sitemap.json.

 

Ya casi terminamos, lo unico que nos falta es decirle a nuestro tema donde deseamos hacer importar recurso al momento de hacer deploy de nuestro tema ya que por defecto, Liferay crea un site template para importar nuestros recursos, pero como le digo eso? bien, cuando construimos un tema usando el theme genarator tool, automáticamente se crea un archivo llamado liferay-plugin-package.properties.

Con las propiedades resources-importer-target-class-name y resources-importer-target-value=[site name] le podemos especificar un site, solo debemos de estar seguros del nombre de site que estamos proporcionando, ya que si nos equivocaramos, podríamos perder contenido que ya tengamos creado en Liferay.

Para nuestro ejemplo, agregaremos esas propiedades de la siguiente manera:

Ahora solo a hacer el deploy de nuestro tema para importar contenido en nuestro ambiente de Liferay.

Para más información puedes consultar la documentación oficial de resource importer de Liferay.

Iterar campos repetibles en un Application Display Template de Liferay 7

Una de las cosas más complicadas de comprender es cómo usar los llamados repeatable fields en un Application Display Template (ADT) en Liferay 7; debido a que no disponemos de tanta documentación oficial. Por tal motivo quisiera compartir contigo un ejemplo de una ADT para el famoso Asset Publisher; comencemos:

  1. Imagina que tienes una Estructura (Structure) con un campo de tipo “Documents and Library” llamado attachment el cual ha sido configurado como repeatable=true.
  2. Ahora bien, necesitas crear un listado de todos los attachments y obtener tanto el link al documento, como su etiqueta (label).

Lo más importante en el código de Freemarker anterior es que estamos utilizando una query de XPath para obtener todos los nodos del XML que representa nuestro Journal Article:

Acto seguido procedemos a iterar ese NodeList, usando la instrucción #list de Freemarker:

Tip. Si tienes dudas qué es una ADT; esta es la definición oficial de la documentación de Liferay:

The application display template (ADT) framework allows Liferay administrators to override the default display templates, removing limitations to the way your site’s content is displayed. With ADTs, you can define custom display templates used to render asset-centric applications. For example, you may want to show blog entries horizontally instead of vertically, or list your assets in the asset publisher application in different sizes.
https://dev.liferay.com/discover/portal/-/knowledge_base/6-2/using-application-display-templates