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:
- WEB-INF
-src
-resources-importer <--- Directorio base.
-document_library
-documents <--- Directorio donde debes agregar el contenido de tipo document and media(imágenes, videos, documentos).
-journal
-articles <--- Directorio donde debes añadir el contenido web.
-structures <--- Directorio que contiene las estrucuturas
-templates <--- Directorio para los templates.
-templates
-application_display
-asset_entry <--- Directorio para ATDs (Application Display Templates).
sitemap.json <--- Este archivo provee todo el mapping de los recursos que vamos a importar.
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:
{
"availableLanguageIds": [
"en_US"
],
"defaultLanguageId": "en_US",
"fields": [
{
"label": {
"en_US": "Summary"
},
"predefinedValue": {
"en_US": ""
},
"style": {
"en_US": ""
},
"tip": {
"en_US": "A short, clear description that states the main facts or ideas of the content. "
},
"dataType": "string",
"indexType": "keyword",
"localizable": true,
"name": "summary",
"readOnly": false,
"repeatable": false,
"required": false,
"showLabel": true,
"type": "textarea"
},
{
"label": {
"en_US": "Body"
},
"predefinedValue": {
"en_US": ""
},
"style": {
"en_US": ""
},
"tip": {
"en_US": ""
},
"dataType": "html",
"fieldNamespace": "ddm",
"indexType": "keyword",
"localizable": true,
"name": "body",
"readOnly": false,
"repeatable": false,
"required": false,
"showLabel": true,
"type": "ddm-text-html"
},
{
"label": {
"en_US": "Thumbnail"
},
"predefinedValue": {
"en_US": ""
},
"style": {
"en_US": ""
},
"tip": {
"en_US": "This image is shown when the item is in a list. Suggested size: 150px wide x 100px high."
},
"dataType": "document-library",
"fieldNamespace": "ddm",
"indexType": "keyword",
"localizable": true,
"name": "thumbnail",
"readOnly": false,
"repeatable": false,
"required": false,
"showLabel": true,
"type": "ddm-documentlibrary"
},
{
"label": {
"en_US": "Image"
},
"predefinedValue": {
"en_US": ""
},
"style": {
"en_US": ""
},
"tip": {
"en_US": ""
},
"dataType": "document-library",
"fieldNamespace": "ddm",
"indexType": "keyword",
"localizable": true,
"name": "image",
"readOnly": false,
"repeatable": false,
"required": false,
"showLabel": true,
"type": "ddm-documentlibrary"
},
{
"label": {
"en_US": "Attachment"
},
"predefinedValue": {
"en_US": ""
},
"style": {
"en_US": ""
},
"tip": {
"en_US": ""
},
"dataType": "document-library",
"fieldNamespace": "ddm",
"indexType": "",
"localizable": false,
"name": "attachment",
"readOnly": false,
"repeatable": false,
"required": false,
"showLabel": true,
"type": "ddm-documentlibrary"
}
]
}
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.
<#-- start getting entry data -->
<#assign entryID = .vars['reserved-article-id'].data >
<#assign entryTitle = .vars['reserved-article-title'].data >
<#assign entryAuthor = .vars['reserved-article-author-name'].data >
<#assign entryAuthorEmail = .vars['reserved-article-author-email-address'].data >
<#assign entryPublishDate = .vars['reserved-article-display-date'].data >
<#assign entrySummary = summary.getData() >
<#assign entryBody = body.getData() >
<#assign entryImage = image.getData() >
<#if entryImage?? && entryImage != "">
<#assign entryImageAltText = entryImage>
</#if>
<#assign entryThumbnail = thumbnail.getData()>
<#-- end getting entry data -->
<h1>${entryTitle}</h1>
<#--<p>hello world start</p>
<liferay-portlet:runtime portletName="com_liferay_hello_world_web_portlet_HelloWorldPortlet" />
<p>hello world end</p>-->
<p class="text-muted">${entryAuthor} | ${entryPublishDate}</p>
<div class="well">
<p>${entrySummary}</p>
</div>
<#if entryImage?? && entryImage != "">
<div class="panel panel-default content-image">
<img src="${entryImage}" alt="${entryImageAltText}" class="img-responsive">
</div>
<#if entryImageAltText?? && entryImageAltText != "">
<p class="text-muted" style="font-weight: bold; font-size: .8em; margin-bottom: 20px; margin-top: -10px;"><i class="glyphicon glyphicon-camera"></i> ${entryImageAltText}</p>
</#if>
</#if>
${entryBody}
<style>
/* hide the back arrow and title included by ful_content.jsp [https://github.com/liferay/com-liferay-asset/blob/76dcfe6d2b86be772f179223b81d9c6f2c495786/asset-publisher-web/src/main/resources/META-INF/resources/display/full_content.jsp]
@todo: develop a custom version of the asset publisher that does not include this.
*/
.portlet-content-container > .portlet-body > div > div.h2 > span {
display: none;
}
</style>
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.
<?xml version="1.0"?>
<root available-locales="en_US" default-locale="en_US">
<dynamic-element name="summary" type="text_box" index-type="keyword">
<dynamic-content language-id="en_US"><![CDATA[This is the Title]]></dynamic-content>
</dynamic-element>
<dynamic-element name="body" type="text_area" index-type="keyword">
<dynamic-content language-id="en_US">
<![CDATA[<p>This is the Content.</p>]]></dynamic-content>
</dynamic-element>
<dynamic-element name="thumbnail" type="document_library" index-type="keyword">
<dynamic-content language-id="en_US" type="journal"><![CDATA[ [$FILE=content_02.jpg$] ]]></dynamic-content>
</dynamic-element>
<dynamic-element name="image" type="document_library" index-type="keyword">
<dynamic-content language-id="en_US" type="journal"><![CDATA[ [$FILE=content_04.jpg$] ]]></dynamic-content>
</dynamic-element>
</root>
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.
<#if entries?has_content>
<!-- start header html -->
<div class="panel panel-default">
<div class="panel-heading">
<h3 class="panel-title">All News</h3>
</div>
<ul class="list-group">
<!-- end header html -->
<!-- start item loop -->
<#list entries as entry>
<#assign renderer = entry.getAssetRenderer()>
<#assign className = renderer.getClassName() >
<#if className == "com.liferay.journal.model.JournalArticle" >
<#assign journalArticle = renderer.getArticle() >
<#assign document = saxReaderUtil.read(journalArticle.getContent()) >
<!-- start item data -->
<#assign entryViewURL = assetPublisherHelper.getAssetViewURL(renderRequest, renderResponse,entry) />
<#assign entryTitle = entry.getTitle(locale) />
<#assign entryPublishDate = dateUtil.getDate(entry.getPublishDate(), "dd MMM yyyy", locale) />
<#assign entryAuthor = entry.getUserName() />
<#assign entrySummary = document.valueOf("//dynamic-element[@name='summary']") />
<#assign entryBody = document.valueOf("//dynamic-element[@name='body']") />
<#assign entryThumbnail = document.valueOf("//dynamic-element[@name='thumbnail']") />
<!-- end item data -->
<!-- start item html -->
<li class="list-group-item">
<div class="media">
<div class="media-left">
<a href="${entryViewURL}">
<div class="media-object" alt="..." style="width: 150px; height: 100px; background-image: url(${entryThumbnail}); background-repeat: no-repeat; background-position: center; background-size: cover"></div>
</a>
</div>
<div class="media-body">
<h4 class="media-heading"><a href="${entryViewURL}">${entryTitle}</a></h4>
<div class="text-muted small">${entryAuthor} | ${entryPublishDate} </div>
${entrySummary}
</div>
<div class="media-right">
<a href="<@getEntryEditURL />"><span class="glyphicon glyphicon-pencil" aria-hidden="true"></span></a>
</div>
</div>
</li>
<!-- end item html -->
<!-- start macros -->
<#macro getEntryEditURL>
<#if renderer.hasEditPermission(themeDisplay.getPermissionChecker())>
<#assign redirectURL = renderResponse.createRenderURL() />
${redirectURL.setParameter("struts_action", "/asset_publisher/add_asset_redirect")}
${redirectURL.setWindowState("pop_up")}
<#assign editPortletURL = renderer.getURLEdit(renderRequest, renderResponse, windowStateFactory.getWindowState("pop_up"), redirectURL) />
<#if validator.isNotNull(editPortletURL)>
<#assign entryEditURL = "javascript:Liferay.Util.openWindow({dialog: {width: 960}, id:'" + renderResponse.getNamespace() + "editAsset', title: '" + entryTitle + "', uri:'" + htmlUtil.escapeURL(editPortletURL.toString()) + "'});" />
${entryEditURL}
</#if>
</#if>
</#macro>
<!-- end macros -->
</#if>
</#list>
<!-- end item loop -->
<!-- start footer -->
</ul>
</div>
<!-- end footer -->
</#if>
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.
{
"publicPages": [
{
"columns": [
[
{
"portletId": "com_liferay_asset_publisher_web_portlet_AssetPublisherPortlet",
"portletPreferences": {
"assetLinkBehavior": "viewInPortlet",
"delta": "3",
"displayStyle": "ddmTemplate_NEWS-AND-EVENTS-ARCHIVE",
"displayStyleGroupId": "${groupId}",
"portletSetupPortletDecoratorId": "barebone",
"showAddContentButton": "false"
}
}
]
],
"friendlyURL": "/home",
"layoutTemplateId": "1_column",
"name": "Home"
},
{
"columns": [
[
{
"portletId": "com_liferay_asset_publisher_web_portlet_AssetPublisherPortlet",
"portletPreferences": {
"assetLinkBehavior": "viewInPortlet",
"delta": "3",
"displayStyle": "ddmTemplate_NEWS-AND-EVENTS-ARCHIVE",
"displayStyleGroupId": "${groupId}",
"portletSetupPortletDecoratorId": "barebone",
"showAddContentButton": "false"
}
}
]
],
"friendlyURL": "/my-workspace",
"layoutTemplateId": "1_column",
"name": "My Workspace"
},
{
"columns": [
[
{
"portletId": "com_liferay_asset_publisher_web_portlet_AssetPublisherPortlet",
"portletPreferences": {
"assetLinkBehavior": "viewInPortlet",
"delta": "3",
"displayStyle": "ddmTemplate_NEWS-AND-EVENTS-ARCHIVE",
"displayStyleGroupId": "${groupId}",
"portletSetupPortletDecoratorId": "barebone",
"showAddContentButton": "false"
}
}
]
],
"friendlyURL": "/my-life",
"layoutTemplateId": "1_column",
"name": "My Life"
},
{
"columns": [
[
{
"portletId": "com_liferay_asset_publisher_web_portlet_AssetPublisherPortlet",
"portletPreferences": {
"assetLinkBehavior": "viewInPortlet",
"delta": "3",
"displayStyle": "ddmTemplate_NEWS-AND-EVENTS-ARCHIVE",
"displayStyleGroupId": "${groupId}",
"portletSetupPortletDecoratorId": "barebone",
"showAddContentButton": "false"
}
}
]
],
"friendlyURL": "/about-us",
"layoutTemplateId": "1_column",
"name": "About Us"
}
]
}
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:
resources-importer-target-class-name=com.liferay.portal.kernel.model.Group resources-importer-target-value=My New Liferay Site
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.