« Zurück zu 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 Anhänge
152842 Angesehen
Durchschnitt (1 Stimme)
Die durchschnittliche Bewertung ist 5.0 von max. 5 Sternen.
Kommentare
Antworten im Thread Autor Datum
What about use DIV instead HTML table to build... Ivano Carrara 12. März 2009 09:12
check the following link: ... Abdulaziz Fawaz 25. März 2009 01:18
Thanks, there is one thing to add , if we using... Wasim Shaikh 8. Juli 2010 07:13
Can someone please provide a url to the "latest... D. T. 18. Mai 2009 11:16
To create a hot deployable war file, you have... Gloria Muñoz 22. Januar 2010 00:36
how can I include a navigation menu in a... Antonieta A. Olivares 30. Januar 2010 10:43
I would like to do the same thing as you... Thomas Viel 10. Februar 2010 01:51
i had developed my own layout using plugin sdk ... sasi kala 8. März 2010 03:28
Hi Sasikala, If you have already deployed the... Namrata Hangal 17. Januar 2011 04:05
Hi All, I used above same suggested code but... Jignesh Vachhani 30. Mai 2011 23:34
is there going to be a wiki page for how... Bradley Wood 7. Juni 2011 11:36
Has there been a solution to this request? John Nguyen 4. September 2013 07:48
Is there any template for the 'processColumns'... Alex Wallace 1. Dezember 2009 07:53
This default layout structure will not permit... Jevon Wright 14. Dezember 2011 18:13
If I have 4 div in my custom layout, and if I... Chintan Akhani 15. September 2012 04:27

What about use DIV instead HTML table to build a Liferay 5.1.x Layout?
Thank you!
Gepostet am 12.03.09 09:12.
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
Gepostet am 25.03.09 01:18 als Antwort auf 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.
Gepostet am 18.05.09 11:16.
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!
Gepostet am 01.12.09 07:53.
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.
Gepostet am 22.01.10 00:36 als Antwort auf 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
Gepostet am 30.01.10 10:43 als Antwort auf Gloria Muñoz.
I would like to do the same thing as you Antonieta, have you find a solution ?
Gepostet am 10.02.10 01:51 als Antwort auf 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
Gepostet am 08.03.10 03:28 als Antwort auf 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
Gepostet am 08.07.10 07:13 als Antwort auf 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
Gepostet am 17.01.11 04:05 als Antwort auf 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 ?
Gepostet am 30.05.11 23:34 als Antwort auf 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.
Gepostet am 07.06.11 11:36 als Antwort auf 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.
Gepostet am 14.12.11 18:13.
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?
Gepostet am 15.09.12 04:27 als Antwort auf Jevon Wright.
Has there been a solution to this request?
Gepostet am 04.09.13 07:48 als Antwort auf Antonieta A. Olivares.