The Liferay UI Taglib #

This is an unfinished attempt to document Liferay 5.2's UI taglib for JSP developers. I haven't found any current and extensive information about it, so I'm learning it the hard way. Any insight and additions from more skilled developers highly appreciated!

For introductory taglib reference, install the liferay-ui-taglib-demo-portlet from the community plugins. This provides editable examples for tags including user-display, Breadcrumb, calendar, captcha, icon and toggle-area. For complete information about taglibs, browse or search in the com.liferay.taglib.ui package under util-taglibs/src in the Liferay source code.

Developer background #

Check out Liferay Core Development Guidelines, especially Liferay UI Guidelines. Also interesting might be Introduction to Liferay for new developers, but this is mostly outdated.

UI setup #

The Liferay UI taglib contains custom user interface tags, e.g. for error reporting or i18n.

If you have the Liferay source download, the taglib definition is located in /util-taglib/src/META-INF/liferay-ui.tld. The java classes are in /util-taglib/src/com/liferay/taglib/ui, and the JSP fragments are in portal-web/docroot/html/taglib/ui

See also the Liferay wiki page "How to search for a taglib's code" for more information.

To use UI, add this import line into your JSP:

<%@ taglib uri="http://liferay.com/tld/ui" prefix="liferay-ui" %>

API reference #

error #

"error" shows user feedback if something went wrong. It is shown in the portlet, using the "portlet-msg-error" CSS class. Per default, this renders a red box with the error message.

Displaying the error requires (at least) two steps

1. indicate that an error should be displayed using

com.liferay.portal.kernel.servlet.SessionErrors.add(PortletRequest portletRequest, String key)

1. display a relevant message for this key on the JSP using

<liferay-ui:error message="message" key="key"/>

example

<%
	SessionErrors.add(renderRequest, "key");
%>

<liferay-ui:error message="this-is-an-error" key="key" />

key must be unique. There seem to be another way of displaying errors directly from an Exception. The syntax is

<liferay-ui:error exception="<%= Exception.class %>" message="message" />

, but I haven't gotten this to work.

message #

"message" displays a localized message for a key. The key can be one of the predefined keys from Liferay (see Language_xx.properties in /portal-impl/src/content), or a custom key introduced with a hook. The translation does not support formatting, i.e. you cannot add HTML into the Language_xx.properties file.

example

<liferay-ui:message key="no" />

will print "no" translated to your selected language. Some more information on i18n in Liferay

tags-summary #

this tag displays tag and/or category information for web content.

parameters:

• className = name of class of resource to retrieve tags for
• classPK = resource primary key
• folksonomy (optional): true = show user created tags as well as categories, false = show only categories. default is false

example:

<liferay-ui:tags-summary 
   className="<%= JournalArticle.class.getName() %>" 
   classPK="<%=article.getResourcePrimKey()%>" 
   folksonomy="false" />

journal-article #

this tag displays a journal article using the template defined by the user.

parameters:

• articleId = uniqueID of content article
• groupId = group of user
• showTitle = show title of article true or false
• templateId = which of the defined templates for this journal article to use. Note that there is a bug (reported here) in liferay versions before 6.0.2 where templateId is ignored.

example:

<liferay-ui:journal-article 
  articleId="<%=menuIdString%>" 
  groupId="<%=groupId%>" />

breadcrumb #

This tag displays a series of links representing page hierarchy. It will display links or text depending on the displayStyle parameter. It does not display user navigation history. parameters:

• displayStyle: 1 = links to pages in child-parent hierarchy. 2 = text but no links
• portletURL:
• selLayout:

example:

<liferay-ui:breadcrumb portletURL="<%=portletURL%>" selLayout="<%=selLayout%>" displayStyle="<%=displayStyle%>" />

tabs #

this tag displays a set of DHTML tabs.

example:

<liferay-ui:tabs 
     names="Welcome,Breadcrumb,Calendar,Captcha,Panel,Table,Icon,Input" 
     tabsValues="welcome,breadcrumb,calendar,captcha,panel,table,icon,input" 
     param="tab" 
     url="<%= portletURL %>"
/>

ratings #

see Adding Rating to a portlet

Related documents #

• Using quotes inside taglibs
• Alloy UI Forms (aui) - new UI forms for Liferay 6.0
• Ajax Toolkit