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

Eduardo P. García
Eduardo P. García
3 Minute Read

 

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!  
    
 
   
 
  
 
  
  
  
 







































































	

	

		




	

	
		
			


































	
		



	



		
			

				


	




	
		
			
				
					







































	

	








	

				

				
					
						


	

		


















	































	


	

	
		

			

























































	

	


































































	

		

		
			
				
					
				
			
		

		
	









				
				

				

				

				


































































	

		

		
			
				
					
				
			
		

		
	









				


































































	

		

		
			
				
					
				
			
		

		
	









				


































































	

		

		
			
				
					
				
			
		

		
	









				


































































	

		

		
			
				
					
				
			
		

		
	









				


































































	

		

		
			
				
					
				
			
		

		
	









				


































































	

		

		
			
				
					
				
			
		

		
	









				


































































	

		

		
			
				
					
				
			
		

		
	









				


































































	

		

		
			
				
					
				
			
		

		
	









				


































































	

		

		
			
				
					
				
			
		

		
	









				


































































	

		

		
			
				
					
				
			
		

		
	









				


































































	

		

		
			
				
					
				
			
		

		
	










				
					





















































	
		
			
				Page Comments
			
		
	

	




				

				
					

					


						

							






























	

		

			

				

					thumbnail
				


				

				

					

						

							

								Daniele Baggio

								

								
							


							

								12 Years Ago

								

								

								
							

						

					

				


				
					

						
							

							
						
					

				
			


			

				

					

					


































































	

		

		
			
				
					
				
			
		

		
	









					


































































	

		

		
			
				
					
				
			
		

		
	









				


				

					

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


					
				


				

					
						

							
								
									
									
										
											Please sign in to reply.
										
									
								
							
						

					

					
						

							


















	
	
		
	




	
		
		
			

				

				
			

		
		
		
	

	





						

					
				

			

		


		

			

				

					

						
					


					

						


						

							






















































	
		
			
		
	








							

							






















































	
		
			
		
	







						


						
					

				

			

		


		

			






























	

		

			

				

					thumbnail
				


				

				

					

						

							

								Eduardo P. Garcia

								

								

									

									
										Daniele Baggio

										

									
								
							


							

								12 Years Ago

								

								

								
							

						

					

				


				
					

						
							

							
						
					

				
			


			

				

					

					


































































	

		

		
			
				
					
				
			
		

		
	









					


































































	

		

		
			
				
					
				
			
		

		
	









				


				

					

						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.
										
									
								
							
						

					

					
						

							


















	
	
		
	




	
		
		
			

				

				
			

		
		
		
	

	





						

					
				

			

		


		

			

				

					

						
					


					

						


						

							






















































	
		
			
		
	








							

							






















































	
		
			
		
	







						


						
					

				

			

		


		

			






























	

		

			

				

					thumbnail
				


				

				

					

						

							

								James Falkner

								

								

									

									
										Eduardo P. Garcia

										

									
								
							


							

								12 Years Ago

								

								

								
							

						

					

				


				
					

						
							

							
						
					

				
			


			

				

					

					


































































	

		

		
			
				
					
				
			
		

		
	









					


































































	

		

		
			
				
					
				
			
		

		
	









				


				

					

						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.
										
									
								
							
						

					

					
						

							


















	
	
		
	




	
		
		
			

				

				
			

		
		
		
	

	





						

					
				

			

		


		

			

				

					

						
					


					

						


						

							






















































	
		
			
		
	








							

							






















































	
		
			
		
	







						


						
					

				

			

		


		

			






























	

		

			

				

					thumbnail
				


				

				

					

						

							

								Eduardo P. Garcia

								

								

									

									
										James Falkner

										

									
								
							


							

								12 Years Ago

								

								

								
							

						

					

				


				
					

						
							

							
						
					

				
			


			

				

					

					


































































	

		

		
			
				
					
				
			
		

		
	









					


































































	

		

		
			
				
					
				
			
		

		
	









				


				

					

						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.
										
									
								
							
						

					

					
						

							


















	
	
		
	




	
		
		
			

				

				
			

		
		
		
	

	





						

					
				

			

		


		

			

				

					

						
					


					

						


						

							






















































	
		
			
		
	








							

							






















































	
		
			
		
	







						


						
					

				

			

		


		

			






























	

		

			

				

					
				


				

				

					

						

							

								Bradley Wood

								

								

									

									
										Eduardo P. Garcia

										

									
								
							


							

								12 Years Ago

								

								

								
							

						

					

				


				
					

						
							

							
						
					

				
			


			

				

					

					


































































	

		

		
			
				
					
				
			
		

		
	









					


































































	

		

		
			
				
					
				
			
		

		
	









				


				

					

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


					
				


				

					
						

							
								
									
									
										
											Please sign in to reply.
										
									
								
							
						

					

					
						

							


















	
	
		
	




	
		
		
			

				

				
			

		
		
		
	

	





						

					
				

			

		


		

			

				

					

						
					


					

						


						

							






















































	
		
			
		
	








							

							






















































	
		
			
		
	







						


						
					

				

			

		


		

			






























	

	


		

			






























	

		

			

				

					
				


				

				

					

						

							

								Luan Vo Ly

								

								

									

									
										Eduardo P. Garcia

										

									
								
							


							

								10 Years Ago

								

								

								
							

						

					

				


				
					

						
							

							
						
					

				
			


			

				

					

					


































































	

		

		
			
				
					
				
			
		

		
	









					


































































	

		

		
			
				
					
				
			
		

		
	









				


				

					

						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.
										
									
								
							
						

					

					
						

							


















	
	
		
	




	
		
		
			

				

				
			

		
		
		
	

	





						

					
				

			

		


		

			

				

					

						
					


					

						


						

							






















































	
		
			
		
	








							

							






















































	
		
			
		
	







						


						
					

				

			

		


		

			






























	

		

			

				

					thumbnail
				


				

				

					

						

							

								selam Aweke selam

								

								

									

									
										Luan Vo Ly

										

									
								
							


							

								10 Years Ago

								

								

								
							

						

					

				


				
					

						
							

							
						
					

				
			


			

				

					

					


































































	

		

		
			
				
					
				
			
		

		
	









					


































































	

		

		
			
				
					
				
			
		

		
	









				


				

					

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


					
				


				

					
						

							
								
									
									
										
											Please sign in to reply.
										
									
								
							
						

					

					
						

							


















	
	
		
	




	
		
		
			

				

				
			

		
		
		
	

	





						

					
				

			

		


		

			

				

					

						
					


					

						


						

							






















































	
		
			
		
	








							

							






















































	
		
			
		
	







						


						
					

				

			

		


		

	


	


		

	


	


		

	


	


		

	


	


		

			






























	

		

			

				

					thumbnail
				


				

				

					

						

							

								selam Aweke selam

								

								

									

									
										Eduardo P. Garcia

										

									
								
							


							

								10 Years Ago

								

								

								
							

						

					

				


				
					

						
							

							
						
					

				
			


			

				

					

					


































































	

		

		
			
				
					
				
			
		

		
	









					


































































	

		

		
			
				
					
				
			
		

		
	









				


				

					

						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.
										
									
								
							
						

					

					
						

							


















	
	
		
	




	
		
		
			

				

				
			

		
		
		
	

	





						

					
				

			

		


		

			

				

					

						
					


					

						


						

							






















































	
		
			
		
	








							

							






















































	
		
			
		
	







						


						
					

				

			

		


		

	


	


		

	


	


		

	


	


						

							






























	

	


						

							






























	

		

			

				

					thumbnail
				


				

				

					

						

							

								Joseph Toman

								

								
							


							

								12 Years Ago

								

								

								
							

						

					

				


				
					

						
							

							
						
					

				
			


			

				

					

					


































































	

		

		
			
				
					
				
			
		

		
	









					


































































	

		

		
			
				
					
				
			
		

		
	









				


				

					

						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.
										
									
								
							
						

					

					
						

							


















	
	
		
	




	
		
		
			

				

				
			

		
		
		
	

	





						

					
				

			

		


		

			

				

					

						
					


					

						


						

							






















































	
		
			
		
	








							

							






















































	
		
			
		
	







						


						
					

				

			

		


		

			






























	

		

			

				

					thumbnail
				


				

				

					

						

							

								Eduardo P. Garcia

								

								

									

									
										Joseph Toman

										

									
								
							


							

								12 Years Ago

								

								
									-
									
										Edited
									
								

								
							

						

					

				


				
					

						
							

							
						
					

				
			


			

				

					

					


































































	

		

		
			
				
					
				
			
		

		
	









					


































































	

		

		
			
				
					
				
			
		

		
	









				


				

					

						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.
										
									
								
							
						

					

					
						

							


















	
	
		
	




	
		
		
			

				

				
			

		
		
		
	

	





						

					
				

			

		


		

			

				

					

						
					


					

						


						

							






















































	
		
			
		
	








							

							






















































	
		
			
		
	







						


						
					

				

			

		


		

	


	


		

	


	


						

							






























	

	


						

							






























	

		

			

				

					
				


				

				

					

						

							

								Gwowen Fu

								

								
							


							

								12 Years Ago

								

								

								
							

						

					

				


				
					

						
							

							
						
					

				
			


			

				

					

					


































































	

		

		
			
				
					
				
			
		

		
	









					


































































	

		

		
			
				
					
				
			
		

		
	









				


				

					

						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.
										
									
								
							
						

					

					
						

							


















	
	
		
	




	
		
		
			

				

				
			

		
		
		
	

	





						

					
				

			

		


		

			

				

					

						
					


					

						


						

							






















































	
		
			
		
	








							

							






















































	
		
			
		
	







						


						
					

				

			

		


		

			






























	

		

			

				

					thumbnail
				


				

				

					

						

							

								Eduardo P. Garcia

								

								

									

									
										Gwowen Fu

										

									
								
							


							

								12 Years Ago

								

								

								
							

						

					

				


				
					

						
							

							
						
					

				
			


			

				

					

					


































































	

		

		
			
				
					
				
			
		

		
	









					


































































	

		

		
			
				
					
				
			
		

		
	









				


				

					

						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.
										
									
								
							
						

					

					
						

							


















	
	
		
	




	
		
		
			

				

				
			

		
		
		
	

	





						

					
				

			

		


		

			

				

					

						
					


					

						


						

							






















































	
		
			
		
	








							

							






















































	
		
			
		
	







						


						
					

				

			

		


		

	


	


		

	


	


						

							






























	

	


						

							






























	

		

			

				

					thumbnail
				


				

				

					

						

							

								Christophe Cariou

								

								
							


							

								11 Years Ago

								

								

								
							

						

					

				


				
					

						
							

							
						
					

				
			


			

				

					

					


































































	

		

		
			
				
					
				
			
		

		
	









					


































































	

		

		
			
				
					
				
			
		

		
	









				


				

					

						Hi,

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


					
				


				

					
						

							
								
									
									
										
											Please sign in to reply.
										
									
								
							
						

					

					
						

							


















	
	
		
	




	
		
		
			

				

				
			

		
		
		
	

	





						

					
				

			

		


		

			

				

					

						
					


					

						


						

							






















































	
		
			
		
	








							

							






















































	
		
			
		
	







						


						
					

				

			

		


		

	


	


						

							






























	

		

			

				

					thumbnail
				


				

				

					

						

							

								Joseph Toman

								

								
							


							

								11 Years Ago

								

								

								
							

						

					

				


				
					

						
							

							
						
					

				
			


			

				

					

					


































































	

		

		
			
				
					
				
			
		

		
	









					


































































	

		

		
			
				
					
				
			
		

		
	









				


				

					

						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.
										
									
								
							
						

					

					
						

							


















	
	
		
	




	
		
		
			

				

				
			

		
		
		
	

	





						

					
				

			

		


		

			

				

					

						
					


					

						


						

							






















































	
		
			
		
	








							

							






















































	
		
			
		
	







						


						
					

				

			

		


		

	


	


						

							






























	

		

			

				

					
				


				

				

					

						

							

								Muhammad Umer Zubair

								

								
							


							

								11 Years Ago

								

								

								
							

						

					

				


				
					

						
							

							
						
					

				
			


			

				

					

					


































































	

		

		
			
				
					
				
			
		

		
	









					


































































	

		

		
			
				
					
				
			
		

		
	









				


				

					

						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.
										
									
								
							
						

					

					
						

							


















	
	
		
	




	
		
		
			

				

				
			

		
		
		
	

	





						

					
				

			

		


		

			

				

					

						
					


					

						


						

							






















































	
		
			
		
	








							

							






















































	
		
			
		
	







						


						
					

				

			

		


		

			






























	

	


		

	


	


						

							






























	

		

			

				

					thumbnail
				


				

				

					

						

							

								Enrique Valdes Lacasa

								

								
							


							

								10 Years Ago

								

								

								
							

						

					

				


				
					

						
							

							
						
					

				
			


			

				

					

					


































































	

		

		
			
				
					
				
			
		

		
	









					


































































	

		

		
			
				
					
				
			
		

		
	









				


				

					

						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.
										
									
								
							
						

					

					
						

							


















	
	
		
	




	
		
		
			

				

				
			

		
		
		
	

	





						

					
				

			

		


		

			

				

					

						
					


					

						


						

							






















































	
		
			
		
	








							

							






















































	
		
			
		
	







						


						
					

				

			

		


		

	


	


						

							






























	

		

			

				

					
				


				

				

					

						

							

								Alberto de Francisco Martín

								

								
							


							

								10 Years Ago

								

								

								
							

						

					

				


				
					

						
							

							
						
					

				
			


			

				

					

					


































































	

		

		
			
				
					
				
			
		

		
	









					


































































	

		

		
			
				
					
				
			
		

		
	









				


				

					

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


					
				


				

					
						

							
								
									
									
										
											Please sign in to reply.
										
									
								
							
						

					

					
						

							


















	
	
		
	




	
		
		
			

				

				
			

		
		
		
	

	





						

					
				

			

		


		

			

				

					

						
					


					

						


						

							






















































	
		
			
		
	








							

							






















































	
		
			
		
	







						


						
					

				

			

		


		

	


	


						

						
					

				
			





















































	

	






		


		

		
	




	
	
					
				
			
		
	
	


	


			

		
	



	

		
		







	








 
Related Assets...
 
More Blog Entries...