Using Application Display Templates on Liferay DXP 7.0

Table of Contents

1. Introduction to Application Display Templates (ADT)
2. Working with an ADT: Media Gallery
3. Using the API: Creating an ADT for Wiki
4. Exporting / Importing ADTs
5. Frequently Asked Questions and Troubleshooting

---

Introduction

Application display templates work similarly to site and page templates, but at the portlet level. The application display template (ADT) framework allows portal administrators to override the default display templates, removing limitations to the way site content is displayed. With ADTs, users can define custom display templates used to render asset-centric applications. For example, blog entries can be displayed horizontally instead of vertically, or assets in the asset publisher portlet can be listed in different sizes.

While users could develop their own custom hooks or portlets to achieve the same goals of having a personalized look and feel, the default application display templates offers the advantage of being out of the box. The default framework is designed specifically to be used with the existing assets. Developers can use the existing APIs and source code as the basis for their own ADTs.

Choosing the Global context makes the template available across all sites but the ADT can be included on the site level. To choose a site to apply the ADT:

1. Navigate to the Site Administration dropdown list by clicking the Compass icon.
   
2. If the Global context is selected, the Application Display Templates page of Site Administration's Configuration Menu shows a list of available sample templates.
   
   
3. These sample templates differ from the default templates already configured in the apps. If a specific site is chosen to host the template, users must create a new custom template for that site's apps.
   
4. To create a new template in Liferay DXP version, click the gray plus button.
   

The list below specifies the apps that can be customized using ADTs.

• Asset Publisher
• Blogs
• Breadcrumb
• Categories Navigation
• Documents and Media
• Language Selector
• Navigation Menu
• RSS Publisher
• Site Map
• Tags Navigation
• Wiki

Customizing Media Gallery

This section describes using an Application Display Template on the Media Gallery portlet. By itself, the Media Gallery offers users a way to store and display media files distinctly from the main Documents Portlet. The default look and feel is like an archive. Using ADT, the Media Gallery becomes something more impressive.

1. Add the Media Gallery application to a page by navigating to Add > Applications > Content Management > Media Gallery.
2. Click the app's Add button > Multiple Media and select two custom photos to display. Then click Save, and navigate back to the main application screen.
3. Notice the default format of the pictures. To change the display template for this app, navigate to Options > Configuration.
4. From the Display Template drop-down menu, select Carousel. Then click Save.
   
   Figure 4: After applying the Carousel ADT, pictures are displayed as a carousel slide show.
   The Media Gallery application is now transformed into a carousel slide show.

Customizing the user interface of Liferay DXP's bundled apps provides the ultimate customization experience for Liferay users.

---

Using the API

Developers can also use APIs to create ADTs.

• The Application Display Templates (ADT) portlet is built on top of the Dynamic Data Mapping and Templates APIs.
• Specific API: ADT specific API is very simple. It's mainly based only on two clases (PortletDisplayTemplateUtil and BasePortletDisplayTemplateHandler) which will be explained later.
• Service API: ADT has no service API (thus, no specific tables in DB), but it reuses DDM service API. All the information is stored in the DDMTemplate table. For ADT the classNameId field of the DDMTemplate table is that of the entity being rendered by the ADT (e.g. Blogs), and the classPK field is 0.
• DDM service API can be accessed from plugins and via Web Services.
• Template API: ADT reuses the existing Freemarker and Velocity template rendering API also used for themes, layouts and web content.

 

Creating a custom ADT

To leverage the ADT API, there are several steps users need to follow. These steps involve registering portlets to use ADTs, defining permissions, and exposing the ADT functionality to users. Use the following steps:

1. Create and register a custom *PortletDisplayTemplateHandler component. Liferay provides the BasePortletDisplayTemplateHandler as a base implementation for users to extend. Check the TemplateHandler interface Javadoc to learn about each template handler method.
   The Component annotation ties the handler to a specific portlet setting the property javax.portlet.name as the portlet name of the portlet. The same property should be found in the portlet class. For example:

   	@Component(
   		immediate = true,
   		property = {
   			"javax.portlet.name="AssetCategoriesNavigationPortletKeysASSET_CATEGORIES_NAVIGATIONserviceTemplateHandlerclasspreEachofthemethodsinthisclasshaveasignificantroleindefiningandimplementingADTsforthecustomportletViewthelistbelowforadetailedexplanationforeachmethoddefinedspecificallyforADTsbrbrbgetClassNamebDefinesthetypeofentrytheportletisrenderingbrbgetNamebDeclaresthenameoftheADTtypetypicallythenameoftheportletbrbgetResourceNamebSpecifieswhichresourceisusingtheADTegaportletforpermissioncheckingThismethodmustreturntheportletsFullyQualifiedPortletIDFQPIbrbgetTemplateVariableGroupsbDefinesthevariablesexposedinthetemplateeditorliolAsanexamplecodePortletDisplayTemplateHandlercodeimplementationlookatWikiPortletDisplayTemplateHandlerjavaolliSincetheabilitytoaddADTsisnewtotheportletconfigurethepermissionssothatadministrativeuserscangrantpermissionstotherolesthatwillbeallowedtocreateandmanagedisplaytemplatesOnlegacyPortal62addtheactionkeycodeADD_PORTLET_DISPLAY_TEMPLATEcodetotheuportletsusrcmainresourcesresourceactionsdefaultxmlfilepreltxmlversion"1.0"?>
   	<!DOCTYPE resource-action-mapping PUBLIC "-//Liferay//DTD Resource Action Mapping 7.0.0//EN" "http://www.liferay.com/dtd/liferay-resource-action-mapping_7_0_0.dtd">
   		vresource-action-mapping>
   
       ...
   
       		< portlet-resource >
           		<portlet-name> yourportlet </portlet-name>
           		<permissions>
               		<supports>
                   		<action-key> ADD_PORTLET_DISPLAY_TEMPLATE </action-key>
                   		<action-key>ADD_TO_PAGE </action-key>
                   		<action-key>CONFIGURATION </action-keyv
                  	 	<action-key>VIEW </action-key>
               	</supports>
               	</permissions>
       		</portlet-resource>
   
       ...
   		</resource-action-mapping>
   	

2. Now that the portlet officially supports ADTs expose the ADT option to other users. Just include the tag in the JSP file used to control the portlet's configuration.
   
   For example, it may be helpful to insert an in the configuration JSP file:

   	<aui:fieldset>
   		<div class="display-template">
           	<liferay-ddm:template-selector
               		classNameId="<%= YourEntity.class.getName() %>"
               		displayStyle="<%= displayStyle %>"
               		displayStyleGroupId="<%= displayStyleGroupId %>"
               		refreshURL="<%= PortalUtil.getCurrentURL(request) %>"
               		showEmptyOption="<%= true %>"
           	/>
   		</div>
   	</aui:fieldset>
   	

   In this JSP, the tag specifies the Display Template drop-down menu to be used in the portlet's Configuration menu. The variables displayStyle and displayStyleGroupId are preferences that the portlet stores when using this taglib and the portlet uses the BaseJSPSettingsConfigurationAction or DefaultConfigurationAction. Otherwise, obtain the value of those parameters and store them manually in the configuration class.
   As an example JSP, see the Wiki application's configuration.jsp.
3. Users must now extend their view code to render their portlet with the selected ADT. This allows users to decide which part of the view will be rendered by the ADT and what will be available in the template context.
   
   First, initialize the Java variables needed for the ADT:

   	<%
   	String displayStyle = GetterUtil.getString(portletPreferences.getValue("displayStyle", StringPool.BLANK));
   	long displayStyleGroupId = GetterUtil.getLong(portletPreferences.getValue("displayStyleGroupId", null), scopeGroupId);
   	%>
   	

   Next, test if the ADT is configured, grab the entities to be rendered, and render them using the ADT. The tag <liferay-ddm:template-renderer> aids with this process. It will automatically use the selected template or render its body if no template is selected.
   Here is some example code that demonstrates implementing this:

   <liferay-ddm:template-renderer
       className="<%= YourEntity.class.getName() %>"
       contextObjects="<%= contextObjects %>"
       displayStyle="<%= displayStyle %>"
       displayStyleGroupId="<%= displayStyleGroupId %>"
       entries="<%= yourEntities %>"
   >
   
       <%-- The code that will be rendered by default when there is no
       template available should be inserted here. --%>
   
   </liferay-ddm:template-renderer>
   

   In this step, users initialized variables dealing with the display settings (displayStyle and displayStyleGroupId) and passed them to the tag along with other parameters listed below:
   className: your entity's class name.
   contextObjects: accepts a Map<String, Object> with any object users want to the template context.
   entries: accepts a list of your entities (e.g., List<YourEntity>).
   
   For an example that demonstrates implementing this, see configuration.jsp.

    

4. To see this custom portlet in action, users can create a new custom template and modify the Wiki portlet.
   1. Users on Liferay DXP can click the left side menu Site Administration > Configuration > Application Display Templates.
   2. Click Add > ${your template}
   3. In the template editor, give the template a name.
   4. Enter FreeMarker or Velocity code into the editor. Sample:

      			<#if entries?has_content>
      				Quick List:
      				<ul>
      				<#list entries as curEntry>
      					<li>${curEntry.name} - ${curEntry.streetAddress}, ${curEntry.city}, ${curEntry.stateOrProvince}</li>
          				</#list>
          			</ul>
      			</#if>
      			

   5. Go to the custom portlet and select Options > Configurations. Click Display Template drop down. Select the custom ADT and click Save.

---

Exporting and Importing templates

Users have the options of exporting and importing their application display templates from one site to another in a LAR format. This is very easy to do. Nevertheless, keep in mind that LARs can be imported only on the same major version of Liferay (e.g. 6.1 LARs cannot be imported into 6.2 and 6.2 LARs cannot be imported into DXP).

1. Select the application display template to be exported.
2. Click three dots (Options) menu.
3. Click Export.
4. Give the LAR a name: Wiki ADT1 or use the default name.
   
5. Click Export using the default settings.
6. Download the LAR.
   
7. Navigate to the site where the template is to be imported.
8. Click three dots (Options) menu.
9. Click Import.
10. Drag and drop the LAR or use the file explorer.
    
11. Continue using the default settings until the Import screen.
12. Click Import. Verify that the template has been imported successfully. The ADT is now available on the second site.

---

Frequently Asked Questions and Troubleshooting

How secure is ADT?

In terms of Java security, users may want to hide some classes or packages from the template context; users can limit the operations that ADTs can perform on the portal. Liferay provides some portal system settings; in DXP, navigate to the Control Panel > Configuration > System Settings > Foundation > FreeMarker/Velocity Engine, to define the restricted classes, packages, and variables. In particular, users may want to add serviceLocator to the list of default values assigned to the FreeMarker and Velocity Engine Restricted variables.

What kind of performance tuning do I need?

When the portlet is rendered, using application display templates will introduce additional processing tasks. Liferay best practices suggest making custom templates as minimal as possible and use the existing API for more complex operations. Users should evaluate the end goals and the expectations on the server loads. Users should run their own performance tests as well. Lastly, users can tune the template cache by navigating to Systems Settings > Foundation > Freemarker/Velocity Engine and configure the Resource Modification check field.