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

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!

24 Comments

Please sign in to comment.

Hi Edoardo,
maybe you forgot to indicate which properties is useful to improve error handling....

Please sign in to reply.

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!

Please sign in to reply.

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

Please sign in to reply.

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.

Please sign in to reply.

Are there plans in the future for Developers to be able to turn on ADT for their custom portlets?

Please sign in to reply.

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.

Please sign in to reply.

Hi Eduardo , I have one question. how can I display document(image, Video) using ADT in asset publisher

Please sign in to reply.

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

Please sign in to reply.

Can we see this demo on 6.1 or I have to install it on 6.2?

Thanks in advance.

Please sign in to reply.

Hi Gabriel! This feature is available only in 6.2.

Please sign in to reply.

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.

Please sign in to reply.

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!

Please sign in to reply.

This seems to be interesting feature!!

Please sign in to reply.

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

Please sign in to reply.

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!

Please sign in to reply.

Eduardo,
You know the museum-theme has no build.xml file, yes?

Please sign in to reply.

I've added the build.xml files to the repository. Thanks!

Please sign in to reply.

Hi,

how can we retrieve datas from a structured Journal Article, in an asset publisher Display Template ?

Please sign in to reply.

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

Please sign in to reply.

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!!!

Please sign in to reply.

Muhammad et al: see https://www.liferay.com/community/forums/-/message_boards/message/34589425

Please sign in to reply.

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!

Please sign in to reply.

I did not know this functionality.
I'll use.
Thanks for sharing.

Please sign in to reply.

Menu Display

Blogs

Category Filter

The ADT concept

Implementation

Demo

Recommendations

Security

Performance

Context

Error handling

Learn more

Related Assets

More Blog Entries

Understanding Liferay 6.2 Release Candidates

Liferay Architecture: What would you like to know?