New Ways of Customization with Application Display Templates (Part I)
Community 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.
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.
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).
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:
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
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:
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!
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
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!