« Voltar

New Ways of Customization with Application Display Templates (Part I)

General Blogs 1 de Outubro de 2013 Por Eduardo P. Garcia Staff

 

Next week Liferay will hold the first Developer Conference (DevCon) in Berlin. Liferay experts from all around the world will meet up to share their experience and review the latest features of version 6.2.
 
We'll have the chance to introduce Application Display Templates (ADT), a new framework to add custom display options for portlets. Juan Fernández had already given us a glipse of the power of this new tool in one of his blogs last year. This time we'll go deeper into the technical details and even show you how to support ADT in your plugins.
 
In this first part of the blog, we'll focus on how ADT works and how to use it.
 

The ADT concept

Portlet Display Settings are the simpliest way to customize portlet display.  Unlike themes or hooks, they don't require deployment and they affect specific portlet instances. But, they are limited to those that come out of the box... Wouldn’t it be great to have as many of them as we wanted? As a user, this would simplify the task of customizing the portlet display. And as developers, we wouldn’t have to change our portlet configuration code every time a new setting is required.
 
That’s exactly what Application Display Templates  (also known as ADT) provides Adding custom display settigs to our portlets. Actually, this is not a new concept in Liferay. In some portlets such as Web Content, Document and Media or Dynamid Data Lists we can add as many display options (or templates) as we want.
 

Implementation

Since we already had similar features in Liferay, we tried not to reinvent the wheel with ADT. Actually, we aimed to reuse as much logic as possible. Basically, ADT is based on two preexisting Liferay components:
  • For the service layer, we used the Dynamic Data Mapping (DDM) portlet. It manages all the operations for structures and templates in every Liferay applications.
  • We used the existing Template Engine that renders Velocity or Freemarker templates based on a given context.
So we just had to add a new portlet to the Site Administration to manage the display templates, and provide a mechanism such that any portlet can define its own template context and show its custom display settings.
 

Demo

At this point some of you may believe that ADT is too good to be true. During the DevCon we'll do a demo to show how easy it is indeed to customize a portlet display with our new tool. Here you have a preview:
 
1. Adding a new ADT for the Media Gallery
 
2. Introducing the new advanced template editor to write a Freemarker script that displays our pictures in a fancy way using the  Masonry Library
 
3. Apply our new ADT to the Media Gallery...
 
..and check the effect
 
4. Extend our template to display a tooltip with more information about the pictures and include the ratings taglib.
 
You can checkout the complete demo from gihub and try it out yourself. (You will need to install the Resource Importer plugin to get the demo contents installed).
 

Recommendations

As we have seen, ADTs bring a great power. But if there's something we've learnt, is that with great power, comes great responsability!  Let’s go through some good practices  in ADT design:
 

Security

You may want to hide some classes or packages from the template context, to limit the operations that ADTs can perform on your portal. Liferay provides some portal  properties to define the restricted classes, packages and variables:
freemarker.engine.restricted.classes 
freemarker.engine.restricted.packages
freemarker.engine.restricted.variables 
velocity.engine.restricted.classes 
velocity.engine.restricted.packages
velocity.engine.restricted.variables

Performance

ADTs add extra processing task in portlet render. This inevitably has effect in the performance. To reduce this effect, make your ADT as minimal as possible: focus on the presentation and use the existing API for complex operations. Don't forget running performance tests and tuning the template cache options:
 
 
freemarker.engine.resource.modification.check.interval velocity.engine.resource.modification.check.interval

Context

The best way to make great ADTs is to know your template context well and what you can use from it. Now you don’t need to know them by heart thanks to the advanced tempalte editor!
 

Error handling

Finally, you can improve the error handling of your templates by setting these properties:
freemarker.engine.template.exception.handler
 velocity.engine.logger
 velocity.engine.logger.category

Learn more

An this is all for the first part of the introduction to ADT. Soon we'll go through the second part: Supporting ADTs in your plugins. In the meantime you can learn more about ADT in our User Guide or promt your questions in our Forums.
 
See you in Berlin! 

 

Comentar
Respostas do tópico Autor Data
Hi Edoardo, maybe you forgot to indicate... Daniele Baggio 1 de Outubro de 2013 09:11
Hi Daniele, Sorry, I did some copy-paste from... Eduardo P. Garcia 1 de Outubro de 2013 09:36
One of my most favorite 6.2 features, thanks... James Falkner 1 de Outubro de 2013 09:58
Good question! Liferay taglibs are fully... Eduardo P. Garcia 1 de Outubro de 2013 10:59
Are there plans in the future for Developers to... Bradley Wood 2 de Outubro de 2013 09:43
Hey Bradley, Yes, Developers can add support... Eduardo P. Garcia 3 de Outubro de 2013 01:35
Hi Eduardo , I have a question. How can i check... Luan Vo Ly 13 de Março de 2015 00:05
Hi Eduardo , I have one question. how can I... Biniword Aweke Konjit 27 de Março de 2015 02:26
Hey Eduardo I have one question, how can I... Biniword Aweke Konjit 27 de Março de 2015 02:30
Can we see this demo on 6.1 or I have to... Gabriel Leon Leyva 2 de Outubro de 2013 10:55
Hi Gabriel! This feature is available only in 6.2. Eduardo P. Garcia 3 de Outubro de 2013 01:33
Unless the library makes it easier to be the... Joseph Toman 2 de Outubro de 2013 12:44
lol Thanks for the tip Joseph, I've just fixed... Eduardo P. Garcia 3 de Outubro de 2013 01:31
This seems to be interesting feature!! Dhrutika Vyas 2 de Outubro de 2013 22:35
Hi Edoardo, I downloaded the the whole... Gwowen Fu 3 de Outubro de 2013 17:30
Hi Gwowen, Just follow these steps: 1. Start... Eduardo P. Garcia 14 de Outubro de 2013 01:59
Eduardo, You know the museum-theme has no... Joseph Toman 14 de Outubro de 2013 14:55
I've added the build.xml files to the... Eduardo P. Garcia 17 de Outubro de 2013 00:46
[...] Liferay Portal 6.2 has just been... Anônimo 7 de Novembro de 2013 08:08
Hi, how can we retrieve datas from a... Christophe Cariou 10 de Dezembro de 2013 08:55
I tried building the museum-theme. It seemed to... Joseph Toman 17 de Fevereiro de 2014 14:04
Hi, Can any body help in getting Article Small... Muhammad Umer Zubair 18 de Fevereiro de 2014 01:39
Muhammad et al: see... James Falkner 18 de Fevereiro de 2014 06:43
[...] Application Display Templates have become... Anônimo 16 de Julho de 2014 13:26
[...] The first Liferay DevCon has just started... Anônimo 16 de Julho de 2014 13:27
Oh man, that picture gallery looks amazing. I... Enrique Valdes Lacasa 19 de Dezembro de 2014 12:33
I did not know this functionality. I'll use.... Alberto de Francisco Martín 15 de Julho de 2015 05:13

Hi Edoardo,
maybe you forgot to indicate which properties is useful to improve error handling....
Postado em 01/10/13 09:11.
Hi Daniele,

Sorry, I did some copy-paste from my notes for the DevCon. I removed some parts to avoid writing the longest blog entry ever :-P. But since you're curious, I've added the portal properties mentioned in the recommendations.

Thanks!
Postado em 01/10/13 09:36 em resposta a Daniele Baggio.
One of my most favorite 6.2 features, thanks for this post! I see the use of taglibs in there - is that allowed with ADTs (I assume it is, since your example has it, but was surprised to see this since I don't think that taglibs are available from generic web content templates).
Postado em 01/10/13 09:58 em resposta a Eduardo P. Garcia.
Good question! Liferay taglibs are fully supported in freemarker (only partially supported in velocity) for ADT, but not for Web Content templates. Even when both portlets use DDM and the Template Engine, they have different template contexts. Injecting more elements into the context is not "free" in terms of performance, so we've decided not to add taglibs in the web content template context by now.
Postado em 01/10/13 10:59 em resposta a James Falkner.
Bradley Wood
Are there plans in the future for Developers to be able to turn on ADT for their custom portlets?
Postado em 02/10/13 09:43 em resposta a Eduardo P. Garcia.
Can we see this demo on 6.1 or I have to install it on 6.2?

Thanks in advance.
Postado em 02/10/13 10:55.
Unless the library makes it easier to be the leader of a murderous cult, I think you might mean the Masonry Library. :-) The link is good, the anchor text not so much. Thanks for the post, ADT look like a useful feature.
Postado em 02/10/13 12:44.
This seems to be interesting feature!!
Postado em 02/10/13 22:35.
lol Thanks for the tip Joseph, I've just fixed it. So for those of you who don't know it, Masonry is a JavaScript grid layout library that works by placing elements in optimal position based on available vertical space. Really cool!
Postado em 03/10/13 01:31 em resposta a Joseph Toman.
Hi Gabriel! This feature is available only in 6.2.
Postado em 03/10/13 01:33 em resposta a Gabriel Leon Leyva.
Hey Bradley,

Yes, Developers can add support for ADT in their custom portlets. The second part of this blog will describe the steps and provide an example. Just hold on ;-)
Postado em 03/10/13 01:35 em resposta a Bradley Wood.
Hi Edoardo,

I downloaded the the whole liferay-plugins-DEVCON2013 branch but don't know how to install the demo, could you show the instructions?

Thanks!
Gwowen Fu
Postado em 03/10/13 17:30.
Hi Gwowen,

Just follow these steps:

1. Start a Liferay 6.2 server (use the latest release available)
2. Download and deploy these plugins from the repo: resources-importer-web, museum-theme
3. If everything has gone well, a new site "Museum" should have been created in your server. This site contains all the settings, docs, templates... Just browse its pages and see how ADT works.

Let me know if it worked for you!
Postado em 14/10/13 01:59 em resposta a Gwowen Fu.
Eduardo,
You know the museum-theme has no build.xml file, yes?
Postado em 14/10/13 14:55.
I've added the build.xml files to the repository. Thanks!
Postado em 17/10/13 00:46 em resposta a Joseph Toman.
[...] Liferay Portal 6.2 has just been released. One of it’s interesting new features are Application display templates (ADT), that promise to allow easy and flexible rendering of content, without... [...] Read More
Postado em 07/11/13 08:08.
Hi,

how can we retrieve datas from a structured Journal Article, in an asset publisher Display Template ?
Postado em 10/12/13 08:55.
I tried building the museum-theme. It seemed to build fine, but when I added a page and dropped the Media Gallery Portlet on it, there was no Museum Masonry ADT. Unzipping the LAR shows that it's there, it just wasn't imported. I had to add it by copying from your screen shot emoticon .
Postado em 17/02/14 14:04.
Hi,
Can any body help in getting Article Small Image Id (Abstract) code for Application Display Templates to be used in Asset Publisher. This will help in generating latest news, etc
Thanks!!!
Postado em 18/02/14 01:39.
Muhammad et al: see https://www.liferay.com/community/forums/-/message_boards/message/34589425
Postado em 18/02/14 06:43 em resposta a Muhammad Umer Zubair.
[...] Application Display Templates have become one of the most popular features in Liferay Portal 6.2. Last year we reviewed how to use this powerful tool to customize some Liferay portlets. Furthermore... [...] Read More
Postado em 16/07/14 13:26.
[...] The first Liferay DevCon has just started in Berlin and we just can't wait to present the world all new features in version 6.2. So I'm writing the second part of my blog about New Ways of... [...] Read More
Postado em 16/07/14 13:27.
Oh man, that picture gallery looks amazing. I am just starting to develop ADTs. I can feel the force in them. I am not sure if this could be dangerous though...like if I would like to enable the $serviceLocator in them. If I had to ask for something this Christmas to Liferay, it would be more documentation about good practices to follow in the configuration and implementation of ADTs. In any way, excellent feature!
Postado em 19/12/14 12:33.
Hi Eduardo , I have a question. How can i check permission to display edit in Blogs using Freemarker templates . I see in view_entry_content.jsp this code : BlogsEntryPermission.contains(permissionChecker, entry, ActionKeys.UPDATE) but i don't know how to use it in freemarker template.
Hope your answer soon. Thanks.
Postado em 13/03/15 00:05 em resposta a Eduardo P. Garcia.
Hi Eduardo , I have one question. how can I display document(image, Video) using ADT in asset publisher
Postado em 27/03/15 02:26 em resposta a Luan Vo Ly.
Hey Eduardo I have one question, how can I display Document library info(like video, image) in asset publisher using ADT. the default asset publisher displays using abstract. but I want to create my own template
Postado em 27/03/15 02:30 em resposta a Eduardo P. Garcia.
I did not know this functionality.
I'll use.
Thanks for sharing.
Postado em 15/07/15 05:13.