« Back

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

General Blogs October 1, 2013 By 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! 

 

Threaded Replies Author Date
Hi Edoardo, maybe you forgot to indicate... Daniele Baggio October 1, 2013 9:11 AM
Hi Daniele, Sorry, I did some copy-paste from... Eduardo P. Garcia October 1, 2013 9:36 AM
One of my most favorite 6.2 features, thanks... James Falkner October 1, 2013 9:58 AM
Good question! Liferay taglibs are fully... Eduardo P. Garcia October 1, 2013 10:59 AM
Are there plans in the future for Developers to... Bradley Wood October 2, 2013 9:43 AM
Hey Bradley, Yes, Developers can add support... Eduardo P. Garcia October 3, 2013 1:35 AM
Hi Eduardo , I have a question. How can i check... Luan Vo Ly March 13, 2015 12:05 AM
Hi Eduardo , I have one question. how can I... selam Aweke selam March 27, 2015 2:26 AM
Hey Eduardo I have one question, how can I... selam Aweke selam March 27, 2015 2:30 AM
Can we see this demo on 6.1 or I have to... Gabriel Leon Leyva October 2, 2013 10:55 AM
Hi Gabriel! This feature is available only in 6.2. Eduardo P. Garcia October 3, 2013 1:33 AM
Unless the library makes it easier to be the... Joseph Toman October 2, 2013 12:44 PM
lol Thanks for the tip Joseph, I've just fixed... Eduardo P. Garcia October 3, 2013 1:31 AM
This seems to be interesting feature!! Dhrutika Vyas October 2, 2013 10:35 PM
Hi Edoardo, I downloaded the the whole... Gwowen Fu October 3, 2013 5:30 PM
Hi Gwowen, Just follow these steps: 1. Start... Eduardo P. Garcia October 14, 2013 1:59 AM
Eduardo, You know the museum-theme has no... Joseph Toman October 14, 2013 2:55 PM
I've added the build.xml files to the... Eduardo P. Garcia October 17, 2013 12:46 AM
[...] Liferay Portal 6.2 has just been... Anonymous November 7, 2013 8:08 AM
Hi, how can we retrieve datas from a... Christophe Cariou December 10, 2013 8:55 AM
I tried building the museum-theme. It seemed to... Joseph Toman February 17, 2014 2:04 PM
Hi, Can any body help in getting Article Small... Muhammad Umer Zubair February 18, 2014 1:39 AM
Muhammad et al: see... James Falkner February 18, 2014 6:43 AM
[...] Application Display Templates have become... Anonymous July 16, 2014 1:26 PM
[...] The first Liferay DevCon has just started... Anonymous July 16, 2014 1:27 PM
Oh man, that picture gallery looks amazing. I... Enrique Valdes Lacasa December 19, 2014 12:33 PM

Hi Edoardo,
maybe you forgot to indicate which properties is useful to improve error handling....
Posted on 10/1/13 9:11 AM.
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!
Posted on 10/1/13 9:36 AM in reply to 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).
Posted on 10/1/13 9:58 AM in reply to 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.
Posted on 10/1/13 10:59 AM in reply to James Falkner.
Bradley Wood
Are there plans in the future for Developers to be able to turn on ADT for their custom portlets?
Posted on 10/2/13 9:43 AM in reply to Eduardo P. Garcia.
Can we see this demo on 6.1 or I have to install it on 6.2?

Thanks in advance.
Posted on 10/2/13 10:55 AM.
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.
Posted on 10/2/13 12:44 PM.
This seems to be interesting feature!!
Posted on 10/2/13 10:35 PM.
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!
Posted on 10/3/13 1:31 AM in reply to Joseph Toman.
Hi Gabriel! This feature is available only in 6.2.
Posted on 10/3/13 1:33 AM in reply to 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 ;-)
Posted on 10/3/13 1:35 AM in reply to 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
Posted on 10/3/13 5:30 PM.
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!
Posted on 10/14/13 1:59 AM in reply to Gwowen Fu.
Eduardo,
You know the museum-theme has no build.xml file, yes?
Posted on 10/14/13 2:55 PM.
I've added the build.xml files to the repository. Thanks!
Posted on 10/17/13 12:46 AM in reply to 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
Posted on 11/7/13 8:08 AM.
Hi,

how can we retrieve datas from a structured Journal Article, in an asset publisher Display Template ?
Posted on 12/10/13 8:55 AM.
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 .
Posted on 2/17/14 2:04 PM.
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!!!
Posted on 2/18/14 1:39 AM.
Muhammad et al: see https://www.liferay.com/community/forums/-/message_boards/message/34589425
Posted on 2/18/14 6:43 AM in reply to 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
Posted on 7/16/14 1:26 PM.
[...] 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
Posted on 7/16/14 1:27 PM.
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!
Posted on 12/19/14 12:33 PM.
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.
Posted on 3/13/15 12:05 AM in reply to Eduardo P. Garcia.
Hi Eduardo , I have one question. how can I display document(image, Video) using ADT in asset publisher
Posted on 3/27/15 2:26 AM in reply to 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
Posted on 3/27/15 2:30 AM in reply to Eduardo P. Garcia.