« Back to Layout...

Layout Template

Introduction #

Layout Templates are ways of choosing how your portlets will be arranged on a page. They make up the body of your page, the large area where you drag and drop your portlets to create your pages. Liferay Portal comes with several built-in layout templates, but if you have a complex page layout (especially for your home page), you may wish to create a custom layout template of your own.

Layout Templates are the easiest plugins to create. They comprise only a few files with simple table or CSS-based containers into which portlets can be dropped, as well as a thumbnail image of what the layout looks like. This thumbnail is displayed when the end user clicks Layout Template from the Dock menu.

Creating Layout Templates #

Creation of layout templates is done in a similar manner to the creation of portlets and themes. There is a layouttpl folder inside the plugins SDK where all new layout templates reside. To create a new layout template, you run a command in this folder similar to the one you used to create a new portlet or theme. For Linux and Mac, type:

./create.sh <project name> “<layout template title>”

For example, to create a layout template with a project folder of 3-columns and a theme title of 3 Columns, type:

./create.sh 3-columns “3 Columns”

On Windows, you would type:

create.bat 3-columns “3 Columns”

This command will create a blank layout template in your layouttpl folder.

Anatomy of a Layout Template #

Layout Template projects are very simple. Say, for example, you wanted to create the above 3 Columns layout template, with left and right columns that take up 20% of the available space, and a middle column that takes up 60%. This is a very common site layout and surprisingly, Liferay does not ship with it (though it does have a three evenly-spaced columns template).

To separate our template from the one that ships with Liferay, we'll call it “3 Columns II” as it will be the newer, slicker sequel. After running the above create Ant script, we have a new project with the layout pictured.

Our next step is to open the 3-columns-ii.tpl file and create our three column template. This file is for regular web browsers to use; Liferay will automatically detect the client being used to connect to the site and serve up the appropriate template. If the client is a phone, it will serve the 3_columns.wap-ii.tpl file.

Open the 3-columns-ii.tpl file in your text editor of choice. You will see that by default, it is a completely blank file. In future versions of the Plugins SDK, there may be a commented out template in there to help you get started. For now, though, we'll provide the code for you to use. Paste the following code into the file:

<div class="columns-3" id="content-wrapper">
	<table class="lfr-grid" id="layout-grid">
	<tr>
		<td class="lfr-column twenty" id="column-1" valign="top">
			$processor.processColumn("column-1")
		</td>
		<td class="lfr-column sixty" id="column-2" valign="top">
			$processor.processColumn("column-2")
		</td>
		<td class="lfr-column twenty" id="column-3" valign="top">
			$processor.processColumn("column-3")
		</td>
	</tr>
	</table>
</div>

You'll note that each table cell has a CSS class associated with it, as well as an ID. These may be customized by modifying the theme you are using to display the layout.

For the WAP version of the file, we'll use simpler syntax:

<table>
<tr>
	<td>
		$processor.processColumn("column-1")
	</td>
	<td>
		$processor.processColumn("column-2")
	</td>
	<td>
		$processor.processColumn("column-3")
	</td>
</tr>
</table>

WAP doesn't have the benefit of CSS, so we will have to settle for three evenly-spaced columns. The other file you need to customize is the 3-columns-ii.png file. The default file in the project is a blank layout template preview. You'll need to customize it in an image manipulation program such as the GIMP (http://www.gimp.org), Adobe Photoshop, or Ulead PhotoImpact.

Since this is a Developer's Guide, we won't go into how to customize the graphic. Suffice it to say that it can be modified to look similar to the example below. This should make it blend in somewhat with the other layout template preview icons.

Once you have customized the icon, all that is left is to deploy the layout template, as the various configuration files have been already generated properly by the Ant scripts in the Plugins SDK.

Development Notes #

A layout template describes how various columns and rows are arranged to display the portlets. Layout templates are located in the deployed servlet's html/layouttpl/standard and html/layouttpl/custom directories as a series of .tpl files. The templates are defined in the source tree at /portal/portal-web/docroot/html/layouttpl/custom. They appear to be Velocity files.

The layout templates that are available to a portal are described (initially) in WEB-INF/liferay-layout-templates.xml (as well as WEB-INF/liferay-layout-templates-ext.xml). These layouts are read in by com.liferay.portal.service.impl.LayoutTemplateLocalUtil (which is called by MainServlet at startup time, or by com.liferay.portal.deploy.HotDeployLayoutTemplateListener if deployed at runtime). Layout definitions are held in in-memory collections of com.liferay.portal.model.LayoutTemplate objects (and not in the database).

Each "layout" (a.k.a. page) has a layout template associated with it. The layout template is stored in the layout-template-id property in a "portlet layout"'s "type settings."

Unconfirmed (but this is how the rest of Liferay works): To add additional templates in the extension environment, create the file in the /ext/ext-web/docroot/html/layouttpl/custom directory, make a new version of /ext/ext-web/docroot/html/WEB-INF/liferay-layout-templates-ext.xml, declare your additions in that file, and re-deploy the extension environment.

The typical structure of .tpl file is

  		<td class="lfr-column" colspan="2" id="column-1" valign="top">
  			$processor.processColumn("column-1")
  		</td>

$processor.processColumn("column-1") creates an area where the portlets could be added. You can create as many of the areas like that as you want.

Unconfirmed: the id of the container element (td or div) for each column should be the column name (in the example above "column-1").

For Liferay 6.0: Required structure of a .tpl file is

<div id="main-content" role="main">
    <div class="portlet-layout">
        <div class="portlet-column" id="column-1">
	    $processor.processColumn("column-1")
	</div>
	<div class="portlet-column" id="column-2">
	    $processor.processColumn("column-2")
	</div>
    </div>
</div>

where "main-content" is pushed aside when install more applications is open, class="portlet-column" is required for defining the part of the page containing a portlet column, and the id must match the column name. The only required part of the layout.tpl is a <div> or <td> with a class="portlet-column"

Another thing to take care about is the WEB-INF/liferay-layout-templates.xml (as well as WEB-INF/liferay-layout-templates-ext.xml). Add something like:

  	<custom>
       ...
  		<layout-template id="1_column" name="1 Column">
  			<template-path>/layouttpl/custom/1_column.tpl</template-path>
  			<wap-template-path>/layouttpl/custom/1_column.wap.tpl</wap-template-path>
  			<thumbnail-path>/layouttpl/custom/1_column.png</thumbnail-path>
  		</layout-template>
       ...
  	</custom>

You can also specify wap layout there.

OR

Create a stand-alone .WAR file that contains the layout definitions, and hot deploy.

For a template, download the latest source and cd to layouttpl/sample-pack-01-layouttpl.war

1. Make some changes to the files

2. Create a war

   jar -cvf ../mylayout.war *

3. Copy war file to your deploy directory.

Available variables in template #

Variable Type Description
processor com.liferay.portlet.layoutconfiguration.util.velocity.TemplateProcessor $processor.processColumn("column-1")
request javax.servlet.http.HttpServletRequest
pageContext javax.servlet.jsp.PageContext
portletConfig com.liferay.portlet.PortletConfigImpl
renderRequest javax.portlet.RenderRequest
renderResponse javax.portlet.RenderResponse
themeDisplay com.liferay.portal.theme.ThemeDisplay Javadoc 5.2
company com.liferay.portal.model.Company
user com.liferay.portal.model.User Javadoc 5.2
realUser com.liferay.portal.model.User
layout com.liferay.portal.model.Layout Javadoc 5.2
layouts java.util.List<???>
plid java.lang.Long
layoutTypePortlet com.liferay.portal.model.LayoutTypePortlet Javadoc 5.2
portletGroupId java.lang.Long
locale java.util.Locale
timeZone java.util.TimeZone
theme com.liferay.taglib.util.VelocityTaglib
colorScheme com.liferay.portal.model.ColorScheme
portletDisplay com.liferay.portal.theme.PortletDisplay

Related Articles #

4 Attachments
136190 Views
Average (1 Vote)
The average rating is 5.0 stars out of 5.
Comments
Threaded Replies Author Date
What about use DIV instead HTML table to build... Ivano Carrara March 12, 2009 9:12 AM
check the following link: ... Abdulaziz Fawaz March 25, 2009 1:18 AM
Thanks, there is one thing to add , if we using... Wasim Shaikh July 8, 2010 7:13 AM
Can someone please provide a url to the "latest... D. T. May 18, 2009 11:16 AM
To create a hot deployable war file, you have... Gloria Muñoz January 22, 2010 12:36 AM
how can I include a navigation menu in a... Antonieta A. Olivares January 30, 2010 10:43 AM
I would like to do the same thing as you... Thomas Viel February 10, 2010 1:51 AM
i had developed my own layout using plugin sdk ... sasi kala March 8, 2010 3:28 AM
Hi Sasikala, If you have already deployed the... Namrata Hangal January 17, 2011 4:05 AM
Hi All, I used above same suggested code but... Jignesh Vachhani May 30, 2011 11:34 PM
is there going to be a wiki page for how... Bradley Wood June 7, 2011 11:36 AM
Has there been a solution to this request? John Nguyen September 4, 2013 7:48 AM
Is there any template for the 'processColumns'... Alex Wallace December 1, 2009 7:53 AM
This default layout structure will not permit... Jevon Wright December 14, 2011 6:13 PM
If I have 4 div in my custom layout, and if I... Chintan Akhani September 15, 2012 4:27 AM

What about use DIV instead HTML table to build a Liferay 5.1.x Layout?
Thank you!
Posted on 3/12/09 9:12 AM.
check the following link:

http://lportal.svn.sourceforge.net/viewvc/lportal/plugins/trunk/themes/samp­le-div-based-theme/docroot/_diffs/layouttpl/custom/div_2_col.tpl?revision=12125
Posted on 3/25/09 1:18 AM in reply to Ivano Carrara.
Can someone please provide a url to the "latest source" as mentioned above in the instructions to create a hot deployable war file for custom layout template?

Thanks.
Posted on 5/18/09 11:16 AM.
Is there any template for the 'processColumns' method? I'd like to present portlets as tabs within a column, not stacked on top of each other...

Thanks!
Posted on 12/1/09 7:53 AM.
To create a hot deployable war file, you have to run the target "ant deploy" within your new layouttpl folder, once you've customized the blank skeleton generated using the "create.sh" command.

The new war will be copied to "dist" folder inside the plugins SDK.

You don't need any extra source code.
Posted on 1/22/10 12:36 AM in reply to D. T..
how can I include a navigation menu in a layout, so my page will expand or not depending on the size of the menu
Posted on 1/30/10 10:43 AM in reply to Gloria Muñoz.
I would like to do the same thing as you Antonieta, have you find a solution ?
Posted on 2/10/10 1:51 AM in reply to Antonieta A. Olivares.
i had developed my own layout using plugin sdk
i wanted to use that layout for my community home page
how can i get it
can anybody pls help me
Posted on 3/8/10 3:28 AM in reply to Thomas Tom.
Thanks, there is one thing to add , if we using DIV based layout template , Then in CSS we must have to give min-height to the div containers. So when we drag and drop Portlets we can view the active area.
Thanks
Posted on 7/8/10 7:13 AM in reply to Affar Le Rafee.
Hi Sasikala,

If you have already deployed the layout that you have created, you should be able to see it in Page Layout options.

Simply select your layout and hit Save!

This should work!

Regards,
Namrata
Posted on 1/17/11 4:05 AM in reply to sasi kala.
Hi All,

I used above same suggested code but in mu case drag & drop functionality is not working.
Could anyone have solution for that ?
Posted on 5/30/11 11:34 PM in reply to Namrata Hangal.
Bradley Wood
is there going to be a wiki page for how layouts are in LR 6.0, for example
using browser sniffing for <IE8 to use tables.
Posted on 6/7/11 11:36 AM in reply to Jignesh Vachhani.
This default layout structure will not permit drag/drop of portlets. To enable drag/drop on custom layouts, you must have a <div id="main-content" role="main"> surrounding the layout itself.

See: http://www.liferay.com/community/forums/-/message_boards/message/7658822/maximiz­ed

You might also need to adapt one of the existing layout structures, e.g. in TOMCAT_HOME/webapps/ROOT/layouttpl/custom/xxx.tpl.
Posted on 12/14/11 6:13 PM.
If I have 4 div in my custom layout, and if I want different height for all four different div than how can I achieve this?
Posted on 9/15/12 4:27 AM in reply to Jevon Wright.
Has there been a solution to this request?
Posted on 9/4/13 7:48 AM in reply to Antonieta A. Olivares.