liferay faces doc 3.1.0 rc1

8/12/2019 Liferay Faces Doc 3.1.0 RC1

1/120

Liferay Faces

Reference Documentation

3.1.0-RC1


2/120

Liferay FacesCopyright 2000-2012 Liferay, Inc. All rights reserved.

Legal Notice

Copyright 2000-2012 Liferay, Inc. All rights reserved. This copyrighted material is made available to anyone wishingto use, modify, copy, or redistribute it subject to the terms and conditions of the LGPL 2.1 license.
http://www.gnu.org/licenses/lgpl-2.1.txt


3/120

Liferay Faces 3.1.0-RC1 iii

Part 1: Liferay Faces Alloy. ......................................................................... 11. Overview .......................................................................................... 32. UIComponent Tags ......................................................................... 5

2.1. The aui:button-row tag ........................................................... 62.2. The aui:column tag ................................................................ 62.3. The aui:field tag ..................................................................... 82.4. The aui :fieldset tag ............................ .................................. 102.5. The aui:form tag .................................. ................................ 112.6. The aui:layo ut tag ................................... ............................. 112.7. The aui:list t ag ...................................................... ............... 122.8. The aui:list t ag ............................................ ......................... 132.9. The aui:text- box-list tag ....................................................... 1 42.10. The aui:text -box-list-item tag ............... ............................... 15

3. Composite Compo nent Tags ... .................................................... 173.1. The aui -cc:button tag .......................................... ................. 173.2. The aui-cc:in put tag .................................................. ........... 193.3. The aui-cc:m essage tag .................. .................................... 213.4. The aui-cc:m essages tag ............... ...................................... 213.5. The aui-cc:s elect tag ..................... ....................................... 23

Part 2: Liferay Faces Bridg e. ................. ................................................... 254. Overview ...... ............................................. ..................................... 275. Portlet Standard .. .................................................... ...................... 29

5.1. Overview .... ....................................... ................................... 29

5.2. Portlet Lifecy cle ..................................... .............................. 295.3. Portlet Mode s ........................... ............................................ 305.4. Portlet Wind ow States ................ ......................................... 315.5. Portlet Prefe rences ........... ................................................... 315.6. Inter-Po rtlet Communication ................................................ 32

6. Portlet Bridge Standard .. ............................................................. 356.1. Ov erview .................................... .......................................... 356.2. Portlet Bridg e 1.0 ................................ ................................. 356.3. Portlet Bridg e 2.0 ....................................... .......................... 356.4. Portlet Bridg e 3.0 .................................... ........................... 356.5. Portlet Lifecy cle and JSF Lifecycle .... .................................. 36

7. Liferay Faces Brid ge Configuration ............ ................................ 377.1. Overvie w .................................................. ............................ 377.2. Bridge Requ est Scope ...................................... ................... 377.3. PreDestroy & BridgePreDestroy Annotati ons ....................... 397.4. Portlet Conta iner Abilities .......... .......................................... 417.5. Portlet Name space Optimization .......................................... 427.6. Resolving X ML Entities .................. ...................................... 437.7. Resource Bu ffer Size ................... ........................................ 43

8. JSF Portlet Develo pment ......................... .................................... 45


4/120

iv Liferay Faces 3.1.0-RC1

8.1. Overview .............................................................................. 458.2. Liferay Faces Bridge ............................................................ 458.3. JSF and PortletPreferences ................................................. 468.4. JSF ExternalContext and the Portlet API ............................. 50

8.4.1. Getting the PortletRequest and PortletResponseObjects ................................................................................ 50

8.5. JSF and Inte r-Portlet Communication .................................. 518.5.1. Portle t 2.0 Public Render Parameters ....................... 528.5.2. Portle t 2.0 Events ......... ............................................ 548.5.3. Portle t 2.0 Shared Session S cope ............................ 56

9. JSF Component T ags ......................................... .......................... 599.1. Overview .... ..................................... ..................................... 599.2. Bridge UICo mponent Tags .............................. .................... 59

9.2.1. The b ridge:inputFile tag ........ .................................... 599.3. Portlet 2.0 U IComponent Tags ............................................ 619.3.1. The p ortlet:actio nURL tag ......................................... 629.3.2. T he portlet:namespace tag ....................................... 639.3.3. T he portlet:param tag ........ ........................................ 649.3.4. T he portlet:ren derURL tag ........................................ 659.3 .5. The portlet:resourceURL tag ..................................... 66

10. Liferay Portal ..... ....................................................................... ... 6910.1. Overview .. ...................................................................... .... 6910.2. JavaScript Concerns .......................................................... 69

11. ICEfaces 3 Portle t Development ........................................ ........ 7111.1. Overview .. ......................... ................................................. 7111.2. ICEfac es Direct-To-DOM RenderKit .............. .................... 7111.3. ICEfaces Aj ax Push and Inter-Portlet C ommunication ........ 7211.4. ICEfaces T hemes and Port al Themes ............................... 7611.5. ICEfac es Themes and Lif eray Themes .............................. 78

Part 3: Liferay Faces Portal. ... ........................................................ .......... 7912. Overview .................... .................................................... .............. 8113. LiferayFacesContext .............................................. ..................... 8314. Liferay Faces Portal E xpression Language Additions ............ 85

14.1. i18n .................. .................................................... .............. 8714.2. liferay ....... ......................................................... ................. 8814.3. liferay.companyI d .............................................. ................. 8814.4. liferay.docu mentLibraryURL ....................... ........................ 8814.5. liferay.grou pUser ............ .................................................... 8914.6. liferay. imageGalleryURL ............ ........................................ 8914.7. liferay.imageUR L .............................................................. .. 8914.8. liferay.layout ..... ....................................... ........................... 8914.9. liferay.permissio nChecker .................................................. 9 0

14.10. liferay.port alURL ....................................................... ....... 90


5/120

Liferay Faces 3.1.0-RC1 v

14.11. liferay.portlet ..................................................................... 9014.12. liferay.portraitURL ............................................................ 9014.13. liferay.theme ..................................................................... 9014.14. liferay.themeDisplay ......................................................... 9114.15. liferay.themeImageURL .................................................... 9114.16. liferay.themeImagesURL .................................................. 9114.17. liferay.user ....................................................................... 9114.18. liferay.userHasPortletPermission ..................................... 92

15. Liferay Faces Portal UIComponent Tags .................................. 9315.1. The liferay-ui:input-editor tag ............................................. 9315.2. The liferay-security:permissionsURL tag ............................ 95

16. Liferay Faces Portal Composite Component Tags .................. 9916.1. The liferay-ui:ice-info-data-paginator tag ............................ 99

16.2. The liferay-ui:ice-nav-data-paginator tag .......................... 10016.3. The liferay-ui:icon tag ...................................................... 10117. Liferay Faces Portal Liferay Theme Integration ..................... 103

17.1. ThemeDisplay .................................................................. 10317.2. Theme Icons .................................................................... 10317.3. Validation Messages (User Feedback) ............................ 103

18. Liferay Faces Por tal Liferay Language Po rtlet Integration .... 105Part 4: Migration from portl etfaces.org. . .................................................. 107

19. Migration Guide ........................................... ............................. 10919.1. BridgeRequ estAttributeListener .......... .............................. 109

19.2. Configuratio n Option Names .................................. .......... 11019.3. File Upload ........................... ............................................ 11119.4. Facelet Tag Library Namespaces ................... ................. 11119.5. GenericFac esPortlet ............................................ ............. 11219.6. Liferay FacesContext ........... ............................................. 11219.7. L ogging .................................................... ........................ 11319.8. Portlet Preferences .......................................................... 113


6/120

vi Liferay Faces 3.1.0-RC1


7/120


8/120


9/120

Liferay Faces 3.1.0-RC1 3

Chapter 1. Overview

Liferay Faces Alloy is a JAR that JSF developers can add as a dependencyto their portlet WAR projects in order to utilize Alloy UI in a way that isconsistent with JSF development.

The project home page can be found athttp://www.liferay.com/community/liferay-projects/liferay-faces/alloy
http://www.liferay.com/community/liferay-projects/liferay-faces/alloy


10/120

4 Liferay Faces 3.1.0-RC1


11/120


Chapter 2. UIComponent TagsLiferay Faces Alloy provides the following UIComponent tags as part of itscomponent suite.

Table 2.1. UIComponent Tags

Tag Description

aui:button-row Renders a span element with CSSclass name "aui-button-holder" thatwill be positioned by Alloy UI CSS.

aui:column Renders a div element with CSSclass name "aui-column" that will bepositioned by Alloy UI CSS.

aui:field Renders a span element with CSSclass name "aui-field" that will bepositioned by Alloy UI CSS.

aui:fieldset Renders a fieldset element with CSSclass name "aui-fieldset" that will bepositioned by Alloy UI CSS.

aui:formRenders a form element with CSSclass name "aui-form" that will bepositioned by Alloy UI CSS.

aui:layout Renders a div element with CSSclass name "aui-layout" that will bepositioned by Alloy UI CSS.

aui:list Renders a ul element with CSS classname "aui-list" that will be positionedby Alloy UI CSS.

aui:list-item Renders an li element with CSSclass name "aui-listitem" that will bepositioned by Alloy UI CSS.

aui:text-box-list Renders a div element with CSSclass name "aui-textboxlist" that willbe positioned by Alloy UI CSS.

aui:text-box-list-item Renders an li element with CSS classname "aui-textboxlistentry" that willbe positioned by Alloy UI CSS.


12/120

Chapter 2. UIComponent Tags


2.1. The aui:button-row tag

The aui:button-row tag renders a span element with CSS class name

"aui-button-holder" that will be positioned by Alloy UI CSS.

Table 2.2. Attributes

Attribute Type Description Required

id String The identifier ofthe component

false

cssClass String The name of aCSS class that

is to be renderedwithin the classattribute.

false

rendered Boolean Boolean flagindicating whetheror not thiscomponent isto be renderedduring the RENDER_RESPONSEphase of the JSFlifecycle. Thedefault value istrue.

false

styleClass String The name of aCSS class thatis to be renderedwithin the classattribute.

false

2.2. The aui:column tag

The aui:column tag renders a div element with CSS class name "aui-column"that will be positioned by Alloy UI CSS.


13/120

The aui:column tag




id String The identifier ofthe component false

columnWidth String The width of thecolumn.

false

cssClass String The name of aCSS class thatis to be renderedwithin the classattribute.

false

first Boolean Boolean flagindicating whetheror not this is thefirst column. Thedefault value isfalse.

false

last Boolean Boolean flagindicating whetheror not this is thelast column. Thedefault value isfalse.

false


false


false


14/120


15/120

The aui:field tag






false

inlineLabel String The position ofthe label. Validvalues are: left,right.

false

label String The text valuefor the renderedlabel.

false


false


false

type String The type of field.Valid valuesare: checkbox,boolean, menu,select.

false


16/120



2.4. The aui:fieldset tag

The aui:fieldset tag renders a fieldset element with CSS class name

"aui-fieldset" that will be positioned by Alloy UI CSS.




false

column Boolean Boolean flagindicating whether

or not this is acolumn. Thedefault value isfalse.

false


false

label String The text valuefor the renderedlabel.

false


false


false


17/120

The aui:form tag


2.5. The aui:form tag

The aui:form tag renders a form element with CSS class name "aui-form"

that will be positioned by Alloy UI CSS.




false

rendered Boolean Boolean flagindicating whether

or not thiscomponent isto be renderedduring the RENDER_RESPONSEphase of the JSFlifecycle. Thedefault value istrue.

false


false

2.6. The aui:layout tag

The aui:layout tag renders a div element with CSS class name "aui-layout"that will be positioned by Alloy UI CSS.


18/120







false


false


false

2.7. The aui:list tag

The aui:list tag renders a ul element with CSS class name "aui-list" that willbe positioned by Alloy UI CSS.


19/120

The aui:list tag






false


false


false

2.8. The aui:list tag

The aui:list tag renders an li element with CSS class name "aui-listitem"that will be positioned by Alloy UI CSS.


20/120







false


false


false

2.9. The aui:text-box-list tag

The aui:text-box-list tag renders a div element with CSS class name"aui-textboxlist" that will be positioned by Alloy UI CSS.


21/120

The aui:text-box-list-item tag






false


false


false

2.10. The aui:text-box-list-item tag

The aui:text-box-list-item tag renders an li element with CSS class name"aui-textboxlistentry" that will be positioned by Alloy UI CSS.


22/120






false


false


false

styleClass String The name of aCSS class that

is to be renderedwithin the classattribute.

false


23/120


Chapter 3. Composite ComponentTags

Liferay Faces Alloy provides the following Facelet Composite Componenttags as part of its component suite.

Table 3.1. Facelet Composite Component Tags

Tag Description

aui-cc:button Renders a div with CSS classname "aui-button" and a child inputelement with CSS class name"aui-button-input".

aui-cc:input Renders either an input (type=text),textarea, input (type="secret"),input (type="checkbox"), or input(type="radio") with appropriate AlloyUI CSS class names, according tothe value of the type attribute.

aui-cc:message Encapsulates a standard JSFh:message tag with JSR 286 (Portlet2.0) CSS class names.

aui-cc:messages Encapsulates a standard JSFh:messages tag with JSR 286 (Portlet2.0) CSS class names.

aui-cc:select Encapsulates a standardJSF h:selectOneMenutag with CSS class name"aui-field-input aui-field-input-select

aui-field-input-menu".

3.1. The aui-cc:button tag

The aui-cc:button renders a div with CSS class name "aui-button" and achild input element with CSS class name "aui-button-input".


24/120

Chapter 3. Composite Component Tags






false

immediate Boolean Boolean flagindicating whetheror not actionsand actionlisteners are to beexecuted duringthe APPLY_REQUEST_VALUESphase of the JSFlifecycle. Thedefault value isfalse.

false

label String The text value forthe rendered labelof the button.

false

rendered Boolean Boolean flagindicating whetheror not thiscomponent isto be renderedduring the RENDER_RESPONSEphase of the JSF

lifecycle. Thedefault value istrue.

false


false


25/120

The aui-cc:input tag


3.2. The aui-cc:input tag

The aui-cc:input renders either an input (type=text), textarea, input

(type="secret"), input (type="checkbox"), or input (type="radio") withappropriate Alloy UI CSS class names, according to the value of the typeattribute.


26/120




pass-thru type ofattribute.

readonly Boolean This is an HTMLpass-thru typeof attribute. Thedefault value isfalse.

false

required Boolean Boolean flag

indicating whetheror not it isrequired for theuser to supplya value for thiscomponent. Thedefault value isfalse.

false

rendered Boolean Boolean flag

indicating whetheror not thiscomponent isto be renderedduring the RENDER_RESPONSEphase of the JSFlifecycle. Thedefault value istrue.

false

rows String The numberof rows for therendered textarea.

false

size String The size/width ofthe rendered inputtext box.

false

style String This is an HTMLpass-thru type ofattribute.

false


false

type String The type of inputfield. Valid valuesare: text, textarea,password,checkbox,boolean.

false


27/120

The aui-cc:message tag


3.3. The aui-cc:message tag

The aui-cc:message encapsulates a standard JSF h:message tag with JSR

286 (Portlet 2.0) CSS class names.




false

for String The id of thecomponent

for which thismessage isassociated.

false


false


false


false

3.4. The aui-cc:messages tag

The aui-cc:messages encapsulates a standard JSF h:messages tag with JSR286 (Portlet 2.0) CSS class names.


28/120






globalOnly Boolean Boolean flagindicating whetheror not thiscomponent is torender only theglobal messages,meaning,messages thatare not associatedwith an individualcomponent. Thedefault value isfalse.

false

layout String The layout of thelist of messages.Valid values are:list, table.

false


false


false


false


29/120

The aui-cc:select tag


3.5. The aui-cc:select tag

The aui-cc:select encapsulates a standard JSF h:selectOneMenu tag with

CSS class name "aui-field-input aui-field-input-select aui-field-input-menu".NOTE that sometimes the JSF implementation performs more reliably if asimple h:selectOneMenu is used instead of this tag.




false

inlineMessage String Boolean flagindicating whetheror not thereshould be aninline h:messagetag included. Thedefault value isfalse.

false

label String The text valuefor the rendered

label.

false


false

value java.util.List The list of itemsthat are to appearin the drop downlist.

false


30/120



31/120


32/120


33/120


Chapter 4. Overview

Liferay Faces Bridge is a JAR that JSF developers can add as a dependencyto their portlet WAR projects in order to deploy JSF web applications asportlets within JSR 286 (Portlet 2.0) compliant portlet containers like LiferayPortal 5.2, 6.0, and 6.1.

The project home page can be found athttp://www.liferay.com/community/liferay-projects/liferay-faces/bridge
http://www.liferay.com/community/liferay-projects/liferay-faces/bridge


34/120



35/120


Chapter 5. Portlet Standard

5.1. OverviewPortlets are web applications that are designed to run inside a portletcontainer that implements either the Portlet 1.0 ( JSR 168 ) or Portlet 2.0 ( JSR286 ) standard. Portlet containers provide a layer of abstraction over the JavaEE Servlet API, and consequently require a servlet container like ApacheTomcat to function. The reference implementation for Portlet 1.0 and 2.0 isthe Apache Pluto project: http://portals.apache.org/pluto .

Portals are standalone systems that use a portlet container as the runtimeengine for executing portlets. When a portal is asked to deliver a portalpage to the end-users web browser, each portlet is asked to render itselfas a fragment of HTML. It is the job of the portal to aggregate these HTMLfragments into a complete HTML document.

5.2. Portlet Lifecycle

The Portlet 1.0 standard defines two lifecycle phases for the execution ofa portlet that a compliant portlet container must support: The first is the

javax.portlet.PortletRequest.RENDER_PHASE, in which the portlet container

asks each portlet to render itself as a fragment of HTML. The second is the javax.portlet.PortletRequest.ACTION_PHASE, in which the portlet containerinvokes actions related to HTML form submission. When the portal receivesan HTTP GET request for a portal page, the portlet container executesthe portlet lifecycle and each of the portlets on the page undergoes theRENDER_PHASE. When the portal receives an HTTP POST request, theportlet container executes the portlet lifecycle and the portlet associated withthe HTML form submission will first undergo the ACTION_PHASE before theRENDER_PHASE is invoked for all of the portlets on the page.

The Portlet 2.0 standard adds two more lifecycle phasesthat define the execution of a portlet. The first is the

javax.portlet.PortletRequest.EVENT_PHASE, in which the portlet containerbroadcasts events that are the result of an HTML form submission. Duringthis phase, the portlet container asks each portlet to process events that theyare interested in. The typical use case for th e EVENT_PHASE is to achie veInter-Portlet Communication (IPC), whereby two or more portlets on a portalpage share data in some way. The other new phase added by the Portlet2.0 standard is th e ja vax.portlet.PortletRequest.RESOURCE_PHASE, inwhich the portlet container asks a specific portlet to perform resou rce-relat edprocessing. One typical use case for the RESOURCE_PHASE is for an
http://portals.apache.org/plutohttp://www.jcp.org/en/jsr/detail?id=286http://www.jcp.org/en/jsr/detail?id=168http://portals.apache.org/plutohttp://www.jcp.org/en/jsr/detail?id=286http://www.jcp.org/en/jsr/detail?id=286http://www.jcp.org/en/jsr/detail?id=168


36/120



individual portlet to process Ajax requests. Another typical use case forthe RESOURCE_PHASE is for an individual portlet to generate non-HTMLcontent (for download purposes) such as a PDF or spreadsheet document.

5.3. Portlet Modes

The Portlet 1.0 and 2.0 standards define three portlet modes that acompliant portlet container must support: javax.portlet.PortletMode.VIEW,

javax.portlet.PortletMode.EDIT, and javax.portlet.PortletMode.HELP. Portalvendors and portlet developers may supply custom modes as well. VIEWmode refers to the rendered portlet markup that is encountered by the userunder normal circumstances. Perhaps a clearer name would be "normal"mode or "typical" mode, because the word "view" is also used by developers

to review to the "view" concern of the MVC design pattern. EDIT moderefers to the rendered portlet markup that is encountered by the user whenselecting custom values for portlet preferences. Perhaps a clearer namewould be "preferences" mode. Finally, HELP mode refers to the renderedportlet markup that is encountered by the user when seeking help regardingthe usage and/or functionality of the portlet.

Figure 5.1. Portlet VIEW Mode

Figure 5.2. Portlet EDIT Mode


37/120

Portlet Window States


Figure 5.3. Portlet HELP Mode

5.4. Portlet Window States

Portals typically manifest the rendered markup of a portlet in arectangular section of the browser known as a portlet window. ThePortlet 1.0 and 2.0 standards define three window states that a compliant

portlet container must support: javax.portlet.WindowState.NORMAL, javax.portlet.WindowState.MAXIMIZED, and javax.portlet.WindowState.MINIMIZED. The NORMAL window state refersto the way in which the portlet container displays the rendered markup of aportlet when it can appear on the same portal page as other portlets. TheMAXIMIZED window state refers to the way in which the portlet containerdisplays the rendered markup of a portlet when it is the only portlet on apage, or when the portlet is to be rendered more prominently than otherportlets on a page. Finally, the MINIMIZED window state refers to the wayin which the portlet container displays a portlet when the markup is not to berendered.

5.5. Portlet Preferences

Developers often have the requirement to provide the end-user withthe ability to personalize the portlet behavior in some way. To meet thisrequirement, the Portlet 1.0 and 2.0 standards provide the ability to definepreferences for each portlet. Preference names and default values can bedefined in the WEB-INF/portlet.xml configuration file. Portal end-users start

out interacting with the portlet user interface in portlet VIEW mode but canswitch to portlet EDIT mode in order to select custom preference values.


38/120



Example 5.1. Specifying preference names and associateddefault values in the WEB-INF/portlet.xml configuration file

...

datePattern

MM/dd/yyyy

unitedStatesPhoneFormat

###-###-####

...

5.6. Inter-Portlet Communication

Inter-Portlet Communication (IPC) is a technique whereby two or moreportlets on a portal page share data in some way. In a typical IPC use case,user interactions with one portlet affect the rendered markup of anotherportlet. The Portlet 2.0 standard provides two techniques to achieve IPC:Public Render Parameters and Server-Side Events.

The Public Render Parameters technique provides a way for portlets toshare data by setting public/shared parameter names in a URL controlledby the portal. While the benefit of this approach is that it is relatively easy toimplement, the drawback is that only small amounts of data can be shared.Typically the kind of data that is shared is simply the value of a databaseprimary key.

The Server-Side Events technique provides a way for portlets to share datausing an event-listener design. When using this form of IPC, the portletcontainer acts as broker and distributes events and payload (data) to portlets.One requirement of this approach is that the payload must implement the

java.io.Serializable interface since it might be sent to a portlet in anotherWAR running in a different classloader.

It could be argued that the Portlet 2.0 approaches for IPC have a commondrawback in that they can lead to a potentially disruptive end-userexperience. This is because they cause either an HTTP GET or HTTP POSTwhich results in a full page refresh. Technologies such as ICEfaces Ajax


39/120

Inter-Portlet Communication


Push can be used to solve this problem. Refer to the Ajax Push IPC sectionof this document for more details.

Figure 5.4. Illustration of Standard Portlet 2.0 IPC


40/120



41/120


Chapter 6. Portlet Bridge Standard

6.1. OverviewThe Portlet 1.0 and JSF 1.0 specifications were formulated during roughlythe same timeframe. Consequently, the JSF Expert Group (EG) was ableto design a framework with portlet compatibility in mind. This is evidencedby methods like ExternalContext.getRequest() which returns a value of typeObject , rather than a value of type javax.servlet.http.HttpServletRequest .When running inside a portlet container, the same method would return avalue of type javax.portlet.PortletRequest . Although the JSF API provides adegree of portlet compatibility, it is necessary to introduce a bridge between

the JSF lifecycle and the P ortlet life cycle in order to run JSF applications asportlets.

6.2. Portlet Bridge 1.0

Starting in 2004, several different JSF portlet bridge implementations w eredeveloped in order to provide JSF deve lopers wi th the ability to deploy theirJSF webapps as portlets. In 2006 the JCP formed the Portlet Bridge 1.0(JSR 301 ) EG in order to define a standard bridge API as well as detailed

requirements for bridge implementations. JSR 301 was released in 2010 andtargeted Portlet 1.0 and JSF 1.2.

6.3. Portlet Bridg e 2.0

When the Portlet 2.0 ( JSR 286 ) standard was released in 2008 it becamenecessary for the JCP to form the Portlet Bridge 2.0 ( JSR 329 ) EG. JSR 329was also released in 2010 and targeted Portlet 2.0 and JSF 1.2.

6.4. Portlet Bridge 3.0After the JSR 314 EG released JSF 2.0 in 2009 and JSF 2.1 in 2010, itbecame evident that a Portlet Bridge 3.0 standard would be beneficial. At thetime of this writing, the JCP ha s not formed such an EG. In the meantime, theLiferay has developed Liferay Faces Bridge , which targets Portlet 2.0 andJSF 2.0/2.1.

Liferay Faces Bridge is an implementation of the JSR 329 Portlet BridgeStandard. It also contains innovative features that make it possible to

leverage the power of JSF 2 inside a portlet application.
http://www.jcp.org/en/jsr/detail?id=314http://www.jcp.org/en/jsr/detail?id=329http://www.jcp.org/en/jsr/detail?id=286http://www.jcp.org/en/jsr/detail?id=301http://portals.apache.org/pluto/portlet-2.0-apidocs/javax/portlet/PortletRequest.htmlhttp://www.jcp.org/en/jsr/detail?id=314http://www.jcp.org/en/jsr/detail?id=329http://www.jcp.org/en/jsr/detail?id=286http://www.jcp.org/en/jsr/detail?id=301http://portals.apache.org/pluto/portlet-2.0-apidocs/javax/portlet/PortletRequest.htmlhttp://download.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.htmlhttp://download.oracle.com/javaee/6/api/javax/faces/context/ExternalContext.html


42/120

Chapter 6. Portlet Bridge Standard


6.5. Portlet Lifecycle and JSF Lifecycle

JSF portlet bridges are responsible for providing a bridge between

the portlet lifecycle and the JSF lifecycle. For example, when a portalpage that contains a JSF portlet is requested via HTTP GET, thenthe RENDER_PHASE of the portlet lifecycle should in turn executethe RESTORE_VIEW and RENDER_RESPONSE phases of the JSFlifecycle. Similarly, when the user submits a form contained within aJSF portlet via HTTP POST, then the ACTION_PHASE of the portletlifecycle should execute the complete JSF lifecycle of RESTORE_VIEW,APPLY_REQUEST_VALUES, PROCESS_VALIDATIONS,UPDATE_MODEL_VALUES, INVOKE_APPLICATION, andRENDER_RESPONSE. Since the portal is in full control of managing URLs,

JSF portlet bridges are also responsible for asking the portal to generateURLs that are compatible with actions that invoke JSF navigation rules. If adifferent JSF view is to be rendered as a result of a JSF navigation-rule, thenthe JSF portlet bridge simply displays the new JSF view in the same portletwindow.


43/120


Chapter 7. Liferay Faces BridgeConfiguration

7.1. Overview

The JSR 329 standard defines several configuration options prefixed withthe javax.portlet.faces namespace. Liferay Faces Bridge defines additionalimplementation specific options prefixed with the com.liferay.faces.bridgenamespace.

7.2. Bridge Request Scope

One of the key requirements in creating a JSF portlet bridge is managingJSF request-scoped data within the Portlet lifecycle. This is normallyreferred to as the "Bridge Request Scope" by JSR 329. The lifespan of theBridgeRequestScope works like this:

1. ActionRequest/EventRequest: BridgeRequestScope begins

2. RenderRequest: BridgeRequestScope is preserved

3. Subsequent RenderRequest: BridgeRequestScope is reused

4. Subsequent ActionRequest/EventRequest: BridgeRequestScope ends,and a new BridgeRequestScope begins

5. If the session expires or is invalidated, then similar to the PortletSessionscope, all BridgeRequestScope instances associated with the session aremade avialable for garbage collection by the JVM

The main use-case for having the BridgeRequestScope preserved in #2(above) is for "re-render" of portlets. One example would be when two or

more JSF portlets are placed on a portal page (Portlets X and Y), and thoseportlets are not using f:ajax for form submission. In such a case, if the userwere to submit a form (via full ActionRequest postback) in Portlet X, andthen submit a form in Portlet Y, then Portlet X should be re-rendered with itspreviously submitted form data.

With the advent of JSF 2 and Ajax, there are four drawbacks for supportingthis use-case as the default behavior:

Request-scoped data basically semi-session-scoped in nature, becausethe BridgeRequestScope is preserved (even though the user mightNEVER click the Submit button again).


44/120

Chapter 7. Liferay Faces Bridge Conf...


BridgeRequestScope can't be stored in the PortletSession because thedata is Request-scoped in nature, and the data stored in the scope isn'tguaranteed to be Serializable for replication. Therefore it doesn't reallywork well in a clustered deployment.

The developer might have to specify the javax.portlet.faces.MAX_MANAGED_REQUEST_SCOPES init-param inthe WEB-INF/web.xml descriptor in order to tune the memory settings onthe server.

The developer is forced to add a for the BridgeSessionListenerto the WEB-INF/web.xml descriptor.

Therefore, since Liferay Faces Bridge is designed for JSF 2 and Ajax inmind, the bridge makes the following assumptions:

That developers are not primarily concerned about the "re-render" ofportlets use-case mentioned above.

That developers don't want any of the drawbacks mentioned above.

That developers are making heavy use of the f:ajax tag (or implicitly doingso with ICEfaces) and submitting forms via Ajax with their modern-dayportlets.

That developers want to be as zero-config as possible, and don't want tobe forced to add anything to the WEB-INF/web.xml descriptor.

Consequently, the default behavior of Liferay Faces Bridge is to causethe BridgeRequestScope to end at the end of the RenderRequest. If thestandard behavior is desired, then the following options can be placed in theWEB-INF/web.xml descriptor.


45/120


46/120



In-Depth Discussion Avialable Online

For a in-depth discussion of this issue, please refer tohttp://issues.liferay.com/browse/FACES-146

In order to explain this requirement, it is necessary to make a distinctionbetween local portals and remote portals. Local portals invoke portletsthat are deployed within the same (local) servlet container. Remoteportals invoke portlets that are deployed elsewhere via WSRP(Web Services for Remote Portlets). The @BridgePreDestroy and@BridgeRequestScopeAttributeAdded annotations were introduced intothe JSR 329 standard primarily to support WSRP in remote portals. Thatbeing the case, the standard indicates that developers should always use

@BridgePreDestroy instead of @PreDestroy. Liferay Faces Bridge howevertakes a different approach: rather than assuming the remote portal use-case,Liferay Faces Bridge assumes the local portal use-case. When developingwith a local portal like Liferay, Liferay Faces Bridge ensures that the standard@PreDestroy annotation works as expected. This means there is no reasonto use the @BridgeRequestScope annotation with a local portal whenusing Liferay Faces Bridge. Developers must manually configure LiferayFaces Bridge via the WEB-INF/web.xml descriptor in order to leverage the@BridgePreDestroy and @BridgeRequestScopeAttributeAdded annotationsfor WSRP.
http://issues.liferay.com/browse/FACES-146


47/120

Portlet Container Abilities


Example 7.2. Specifying support for @BridgePreDestroyand @BridgeRequestScopeAttributeAdded in theWEB-INF/web.xml descriptor

com.liferay.faces.bridge.preferPreDestroy

false

com.liferay.faces.bridge.servlet.BridgeRequestAttributeListener

Alternatively, the com.liferay.faces.bridge.preferPreDestroy value can bespecified on a portlet-by-portlet basis in the WEB-INF/portlet.xml descriptor.

7.4. Portlet Container Abilities

Liferay Faces Bridge can be run in a variety of portlet containers (Liferay,Pluto, etc.) and is aware of some of the abilities (or limitations) of these

containers. Regardless, Liferay Faces Bridge enables the developer toconfigure the abilities of the portlet container in the WEB-INF/web.xmldescriptor.


48/120



Example 7.3. Setting portlet container abilities via theWEB-INF/web.xml descriptor

com.liferay.faces.bridge.containerAbleToSetHttpStatusCode

true

7.5. Portlet Namespace Optimization

The JSR 329 standard requires the bridge implementation to prepend theportlet namespace to the value of the "id" attribute of every componentthat is rendered by a JSF view. This guarantees the uniqueness ofthe "id" attribute when there are multiple JSF portlets on a portal

page that contain similar component hierarchies and naming. Also,the JSR 329 standard indicates that the bridge implementation of theExternalContext.encodeNamesapce(String) method is to prepend the valueof javax.portlet.PortletResponse.getNamespace() to the specified String. Theproblem is that since the value returned by getNamespace() can be a lengthystring, the size of the rendered HTML portal page can become unnecessarilylarge. This can be especially non-performant when using the f:ajax tag in aFacelet view in order to perform partial-updates the browser's DOM.

Liferay Faces Bridge has a built-in optimization that minimizes the value

returned by the the ExternalContext.encodeNamesapce(String) method,while still guaranteeing uniqueness. Developers must manually configureLiferay Faces Bridge via the WEB-INF/web.xml descriptor in order to disablethe namespace optimization and leverage the default behavior specified byJSR 329.


49/120

Resolving XML Entities


Example 7.4. Disabling the namespace optimization via theWEB-INF/web.xml descriptor

com.liferay.faces.bridge.optimizePortletNamespace

false

7.6. Resolving XML EntitiesLiferay Faces Bridge provides the ability to set a flag indicating whether ornot XML entities are required to be resolved when parsing faces-config.xmlfiles in the classpath. The default value of this option is false.

Example 7.5. Specifying the resolving of XML entities viathe WEB-INF/web.xml descriptor

com.liferay.faces.bridge.resolveXMLEntities

true

7.7. Resource Buffer SizeLiferay Faces Bridge provides the ability to set the size of the buffer usedto load resources into memory as the file contents are being copied to the

response. The default value of this option is 1024 (1KB).

Example 7.6. Specifying the resource buffer size via theWEB-INF/web.xml descriptor

com.liferay.faces.bridge.resourceBufferSize

4096


50/120



Alternatively, the com.liferay.faces.bridge.resourceBufferSize value can bespecified on a portlet-by-portlet basis in the WEB-INF/portlet.xml descriptor.


51/120


Chapter 8. JSF Portlet Development

8.1. OverviewThe main goal of JSF portlet bridges is to make the JSF portlet developmentexperience as close as possible to JSF webapp development. Consequently,many JSF webapps can be easily migrated to a portlet container using sucha bridge.

8.2. Liferay Faces Bridge

In order to use JSF2 in a portlet, developers must specifyjavax.portlet.faces.GenericFacesPortlet in the element ofthe WEB-INF/portlet.xml descriptor.


52/120



Example 8.1. Specifying Liferay Faces Bridge in theWEB-INF/portlet.xml configuration file, as well as defaultFacelet views that are to be rendered for VIEW mode, EDIT

mode, and HELP mode

my_portlet

My Portlet

javax.portlet.faces.GenericFacesPortlet

javax.portlet.faces.defaultViewId.view

/xhtml/applicantForm.xhtml

javax.portlet.faces.defaultViewId.edit

/xhtml/edit.xhtml

javax.portlet.faces.defaultViewId.help

/xhtml/help.xhtml

text/html

view

edit

help

...

8.3. JSF and PortletPreferences

JSF portlet developers often have the requirement to provide the end-userwith the ability to personalize the portlet in some way. To meet thisrequirement, the Portlet 2.0 specification provides the ability to define portletpreferences for each portlet. Preference names and default values can bedefined in the WEB-INF/portlet.xml descriptor. Portal end-users start outinteracting with the portlet user interface in portlet VIEW mode but switch toportlet EDIT mode in order to select custom preference values.


53/120

JSF and PortletPreferences


Example 8.2. Portlet Preferences in WEB-INF/portlet.xml

datePattern

MM/dd/yyyy

Additionally, Portlet 2.0 provides the ability to specify support for EDIT modein the WEB-INF/portlet.xml descriptor.

Example 8.3. Enabling Support for Portlet EDIT Mode inWEB-INF/portlet.xml

text/html

view

edit

However, just because support portlet EDIT mode has been specified,it doesn't mean that the portlet container knows which JSF view shouldbe rendered when the user enters portlet portlet EDIT mode. JSF portletdevelopers must specify the Facelet view that is to be displayed for eachsupported portlet mode.

Example 8.4. Specifying a Facelet View for EDIT mode withLiferay Faces Bridge

javax.portlet.faces.defaultViewId.edit

/edit.xhtml

Facelet views that are designed to be used in portlet EDIT mode aretypically forms that contain JSF component tags that enable the portletend-user to select custom preference values that override the defaultvalues specified in the WEB-INF/portlet.xml descriptor. JSR 329 bridgeimplementations are required to provide an EL resolver that introduces themutablePortletPreferencesValues variable into the EL, which is a mutablejava.util.Map that provides read/write access to each portlet preference. Byutilizing the JSR 329 mutablePortletPreferencesValues variable within anEL ValueExpression , portlet developers can declaratively bind the Facelet


54/120



view to the portlet preference model data. In order to save the preferences, abacking bean must call the PortletPreferences.store() method.

Example 8.5. EDIT Mode Facelet XHTML
http://portals.apache.org/pluto/portlet-2.0-apidocs/javax/portlet/PortletPreferences.html


55/120

JSF and PortletPreferences


Example 8.6. EDIT Mode Backing Bean - Part I

/**

* This is a JSF backing managed-bean that has an action-listener * for saving portlet preferences.

*/

@ManagedBean(name = "portletPreferencesBackingBean")

@RequestScoped

public class PortletPreferencesBackingBean {

public void submit() {

// The JSR 329 specification defines an EL variable named

// mutablePortletPreferencesValues that is being used in

// the portletPreferences.xhtml Facelet composition. This

// object is of type Map and is // designed to be a model managed-bean (in a sense) that

// contain preference values. However the only way to

// access this from a Java class is to evaluate an EL

// expression (effectively self-injecting) the map into

// this backing bean.

FacesContext facesContext = FacesContext.getCurrentInstance();

ExternalContext externalContext =

facesContext.getExternalContext();

String elExpression = "mutablePortletPreferencesValues";

ELResolver elResolver =

facesContext.getApplication().getELResolver();

@SuppressWarnings("unchecked") Map mutablePreferenceMap =

(Map) elResolver.getValue(

facesContext.getELContext(), null, elExpression);

// Get a list of portlet preference names.

PortletRequest portletRequest =

(PortletRequest) externalContext.getRequest();

PortletPreferences portletPreferences =

portletRequest.getPreferences();

Enumeration preferenceNames =

portletPreferences.getNames();


56/120



Example 8.7. EDIT Mode Backing Bean - Part II

try {

// For each portlet preference name:

while (preferenceNames.hasMoreElements()) {

// Get the value specified by the user.

String preferenceName = preferenceNames.nextElement();

String preferenceValue =

mutablePreferenceMap.get(preferenceName).getValue();

// Prepare to save the value.

if (!portletPreferences.isReadOnly(preferenceName)) {

portletPreferences.setValue(

preferenceName, preferenceValue); }

}

// Save the preference values.

portletPreferences.store();

// Switch the portlet mode back to VIEW.

ActionResponse actionResponse =

(ActionResponse) externalContext.getResponse();

actionResponse.setPortletMode(PortletMode.VIEW);

// Report a successful message back to the user as feedback. FacesMessageUtil.addGlobalSuccessInfoMessage(facesContext);

}

catch (Exception e) {

FacesMessageUtil.addGlobalUnexpectedErrorMessage(facesContext);

}

}

}

8.4. JSF ExternalContext and the Portlet API

Just as JSF web application developers rely on ExternalContext in orderto get access to the Servlet API, JSF portlet developers also rely onExternalContext in order to get access to the Portlet API.

8.4.1. Getting the PortletRequest and PortletResponseObjects

The two most common tasks that JSF portlet developers need toperform is to obtain an instance of the javax.portlet.PortletRequest or

javax.portlet.PortletResponse objects.


57/120

JSF and Inter-Portlet Communication


Example 8.8. Getting the PortletRequest andPortletResponse objects from within a JSF backingmanaged-bean action method

public class BackingBean {

public void submit() {

FacesContext facesContext =

FacesContext.getCurrentInstance();



PortletRequest portletRequest =

(PortletRequest) externalContext.getRequest();

PortletResponse portletResponse =

(PortletResponse) externalContext.getResponse();

}

}

Liferay Faces Portal Project

For Liferay portlet developers, Liferay Faces

Portal project features the LiferayFacesContextsingleton which contains convenience methodslike liferayFacesContext.getPortletRequest() andliferayFacesContext.getPortletResponse().

8.5. JSF and Inter-Portlet Communication

Liferay Faces Bridge supports Portlet 2.0 IPC using the JSR 329 approachfor supporting Portlet 2.0 Events and also Portlet 2.0 Public Render

Parameters. It could be argued that the Portlet 2.0 approaches for IPC havea common drawback in that they can lead to a potentially disruptive end-userexperience. This is because they cause either an HTTP GET or HTTP POSTwhich results in a full page refresh. Technologies such as ICEfaces AjaxPush can be used to solve this problem. Refer to the Ajax Push IPC sectionof this document for more details.

Demo Portlets at liferay.com

Visithttp://www.liferay.com/community/liferay-projects/liferay-faces/
http://www.liferay.com/community/liferay-projects/liferay-faces/demos


58/120



demos for demo portlets that demonstrate how to use each ofthese various approaches to IPC.

8.5.1. Portlet 2.0 Public Render Parameters

As discussed in Chapter 1 , the Public Render Parameters technique providesa way for portlets to share data by setting public/shared parameter names ina URL controlled by the portal. While the benefit of this approach is that it isrelatively easy to implement, the drawback is that only small amounts of datacan be shared. Typically the kind of data that is shared is simply the valueof a database primary key. As required by the Portlet 2.0 standard, PublicRender Parameters must be declared in the WEB-INF/portlet.xml descriptor.

Example 8.9. Specifying Supported Public RenderParameters in the WEB-INF/portlet.xml descriptor

customersPortlet

...

selectedCustomerId

bookingsPortlet

...

selectedCustomerId

selectedCustomerId

x:selectedCustomerId

The JSR 329 standard defines a mechanism by which developers canuse Portlet 2.0 Public Render Parameters for IPC in a way that is morenatural to JSF development. Section 5.3.2 requires the bridge to injectthe public render parameters into the Model concern of the MVC designpattern (as in JSF model managed-beans) after RESTORE_VIEW phasecompletes. This is accomplished by evaluating the EL expressions foundin the ... section of the WEB-INF/faces-config.xmldescriptor.
http://www.liferay.com/community/liferay-projects/liferay-faces/demos


59/120

Portlet 2.0 Public Render Parameters


Example 8.10. Specifying Public Render Parameters in theWEB-INF/faces-config.xml descriptor

selectedCustomerId

#{customersPortlet:customersModelBean.selectedCustomerId}

#{bookingsPortlet:bookingsModelBean.selectedCustomerId}

Section 5.3.2 of the JSR 329 standard also requires that if abridgePublicRenderParameterHandler has been registered in theWEB-INF/portlet.xml descriptor, then the handler must be invoked so that itcan perform any processing that might be necessary.

Example 8.11. Specifying abridgePublicRenderParameterHandler in theWEB-INF/portlet.xml descriptor

javax.portlet.faces.bridgePublicRenderParameterHandler

com.liferay.faces.example.handler.CustomerSelectedHandler


60/120



Example 8.12. bridgePublicRenderParameterHandler JavaCode

package com.liferay.faces.example.handler;

import javax.faces.context.FacesContext;

import com.liferay.faces.bridge.BridgePublicRenderParameterHandler;

public class CustomerSelectedHandler implements

BridgePublicRenderParameterHandler {

public void processUpdates(FacesContext facesContext) {

// Here is where you would perform any necessary processing of

public render parameters

}

}

8.5.2. Portlet 2.0 Events

As discussed in Chapter 1 , the Server-Side Events technique provides away for portlets to share data using an event-listener design. When usingthis form of IPC, the portlet container acts as broker and distributes eventsand payload (data) to portlets. One requirement of this approach is that

the payload must implement the java.io.Serializable interface since it mightbe sent to a portlet in another WAR running in a different classloader.As required by the Portlet 2.0 standard, Events must be declared in theWEB-INF/portlet.xml descriptor.


61/120

Portlet 2.0 Events


Example 8.13. Specifying Supported Events in theWEB-INF/portlet.xml descriptor

customersPortlet

...

x:ipc.customerEdited

x:ipc.customerSelected

bookingsPortlet

...




com.liferay.faces.example.dto.Customer


com.liferay.faces.example.dto.Customer

Section 5.2.5 of the JSR 329 standard requires that if a BridgeEventHandler

has been registered in the WEB-INF/portlet.xml descriptor, then the handlermust be invoked so that it can perform any processing that might benecessary.


62/120


63/120

Portlet 2.0 Shared Session Scope


and javax.portlet.PortletSession.PORTLET_SCOPE. The former canbe used for sharing data between portlets packaged in the same WAR,but the latter cannot. The reason why JSF session scope cant be usedto share data between portlets is because all JSF portlet bridges usePortletSession.PORTLET_SCOPE.

In order to share data with PortletSession.APPLICATION_SCOPE, the JSFportlet developer can place a JSF model managed-bean in request scopeand use the getter/setter as a layer of abstraction.

Example 8.16. Shared Scope Model Managed-Bean - Part I

/**

* This class is a request-scoped JSF managed-bean that has

* a getter and setter that serves as a layer of abstraction

* over PortletSession.APPLICATION_SCOPE

*/

@RequestScoped(name="sharedScopeModelBean")

public class SharedScopeModelBean {

public static final String

SHARED_STRING_KEY = sharedStringKey;

public String getSharedString() {

return PortletSessionUtil.getSharedSessionAttribute(

SHARED_STRING_KEY);

}

public void setSharedString(String value) {

PortletSessionUtil.setSharedSessionAttribute(

SHARED_STRING_KEY, value);

}

}

public class PortletSessionUtil {

public static Object getSharedSessionAttribute(

String key) {





PortletSession portletSession =

(PortletSession) externalContext().getSession(false);

return portletSession.getAttribute(

key, PortletSession.APPLICATION_SCOPE);

}


64/120



Example 8.17. Shared Scope Model Managed Bean - Part II

public static void setSharedSessionAttribute(

String key, Object value) {





PortletSession portletSession =

(PortletSession)externalContext().getSession(false);

portletSession.setAttribute(

key, value, PortletSession.APPLICATION_SCOPE); }

}


65/120


Chapter 9. JSF Component Tags

9.1. OverviewAlthough the JSR 329 standard does not define any JSF components thatimplementations are required to provide, Liferay Faces Bridge comes with ahandful of components that are helpful during JSF portlet development.

9.2. Bridge UIComponent Tags

Liferay Faces Bridge provides the following bridge-specific UIComponenttags as part of its component suite.


Tag Description

bridge:inputFile Renders an HTML tag which providesfile upload capability.

9.2.1. The bridge:inputFile tag

The bridge:inputFile tag renders an HTML tag whichenables file upload capability.

Dependency on JARs from apache.org

Usage of this tag requires the Apache commons-fileuploadand commons-io dependencies. See the Demo JSF2 Portlet atliferay.com for more details.
http://www.liferay.com/community/liferay-projects/liferay-faces/demos#jsf2-portlet


66/120






binding com.liferay.faces.bridge.component.HtmlInputFileAn EL expressionthat representsa JavaBeanproeprty for thecorrespondingHtmlInputFilecomponent inthe runtimecomponent tree.

true

rendered Boolean Boolean flagindicating whetheror not thiscomponent isto be renderedduring the RENDER_RESPONSEphase of the JSFlifecycle. The

default value istrue.

false

Example 9.1. Example usage of bridge:inputFile tag


67/120

Portlet 2.0 UIComponent Tags


Example 9.2. Backing Bean Java Code

@ManagedBean(name = "backingBean")

@ViewScopedpublic class BackingBean implements Serializable {

private transient HtmlInputFile attachment1;

public void uploadAttachments(ActionEvent actionEvent) {

UploadedFile uploadedFile1 = attachment1.getUploadedFile();

System.err.println("Uploaded file:" + uploadedFile1.getName());

}

}

9.3. Portlet 2.0 UIComponent TagsLiferay Faces Bridge provides the following portlet UIComponent tags as partof its component suite.

JSF 2 Facelets

Although JSP tags are provided by the portlet containerimplementation, Liferay Faces Bridge provides these tags in orderto support their usage within Facelets.


68/120




Tag Description

portlet:actionURL If the var attribute is present,introduces an EL variable thatcontains a javax.portlet.ActionURLadequate for postbacks. Otherwise,the URL is written to the response.

portlet:namespace If the var attribute is present,introduces an EL variable thatcontains a the portlet namespace.Otherwise, the namespace is writtento the response.

portlet:param Provides the ability to add arequest parameter name=valuepair when nested insideportlet:actionURL, portletRenderURL,or portlet:resourceURL tags.

portlet:renderURL If the var attribute is present,introduces an EL variable thatcontains a javax.portlet.PortletURLadequate for rendering. Otherwise,the URL is written to the response.

portlet:resourceURL If the var attribute ispresent, introduces an ELvariable that contains a

javax.portlet.ResourceURL adequatefor rendering. Otherwise, the URL iswritten to the response.

9.3.1. The portlet:actionURL tag

If the var attribute is present, the portlet:actionURL tag introduces an ELvariable that contains a javax.portlet.ActionURL adequate for postbacks.Otherwise, the URL is written to the response.


69/120

The portlet:namespace tag





false



false

var String Specifies thename of avariable that willbe introduced intothe EL.

false

Example 9.3. Example usage of portlet:actionURL tag


70/120







false


false



71/120

The portlet:renderURL tag





name String The name of theparameter.

true


false

value String The value of theparameter.

true



72/120


73/120

The portlet:resourceURL tag





false



false


false

Example 9.7. Example usage of portlet:resourceURL tag


74/120



75/120


Chapter 10. Liferay Portal

10.1. OverviewLiferay Portal is an open source portal server that implements the Portlet 2.0standard. The project home page can be found at http://www.liferay.com .

While Liferay Faces Bridge is theoretically compatible with any portal thatimplements the Portlet 2.0 standard, it has been carefully tested for use withLiferay Portal 5.2 and Liferay Portal 6.0 and has several optimizations thatprovide increased performance within Liferay.

10.2. JavaScript ConcernsWhen any JSF 2 portlet dynamically is added to a portal page at runtime bythe end-user, the JSF 2 standard jsf.js JavaScript code will not be executedunless there is a full page refresh.

As a workaround, Liferay Portal provides configuration parameters thatallow the developer to specify that a full page refresh is required. Doingthis ensures that JSF 2 is properly initialized. The required parameters,render-weight and ajaxable, are specified in the WEB-INF/liferay-portlet.xml

configuration file

Example 10.1. Specifying that a full page refresh shouldtake place after the JSF 2 portlet is first added to the portalpage

my_portlet

false

1

false
http://www.liferay.com/


76/120



77/120


Chapter 11. ICEfaces 3 PortletDevelopment

11.1. Overview

ICEfaces 3 is an open source extension to JSF that enables developerswith Java EE application skills to build Ajax-powered Rich InternetApplications (RIA) without writing any JavaScript code. The product containsa robust suite of Ajax-enabled JSF UI components, and also supports abroad array of Java application servers, IDEs, third party components,and JavaScript effect libraries. The project home page can be found at

http://www.icesoft.org/projects/ICEfaces .

ICEfaces 3 introduces automatic-Ajax into JSF 2 applications, which makesit a particularly good choice for developing RIA portlets. Consider a portalpage that contains two portlets: Portlet A and Portlet B. When submitting aform in Portlet A, an HTTP POST takes place and the entire portal page isrefreshed. This can result in a disruptive end-user experience if the user hadentered data in Portlet B prior to submitting Portlet A. ICEfaces 3 allows youto combat this disruptive experience with RIA features in your portlets.

11.2. ICEfaces Direct-To-DOM RenderKitRather than writing markup directly to the response, ICEfaces 3 componentsrender themselves into a server-side Document Object Model (DOM) viathe Direct-to-DOM (D2D) RenderKit. When a JSF view is requested for thefirst time, the markup inside the server-side DOM is delivered to the browseras part of the response. As the user interacts with the UI of the portlet,ICEfaces transparently submits user actions via Ajax and executes theJSF lifecycle. When the RENDER_RESPONSE phase of the JSF lifecycle

completes, ICEfaces will compare the previous server-side DOM with thelatest server-side DOM and send the incremental page updates back to thebrowser via the IC Efaces Ajax Bridge.

This approach is sometimes referred to as dom-diffing and provides thefollowing benefits for portlets:

The end user is immediately presented with form validation failures forvisited fields when pressing the tab key

When a navigation-rule fires and a new JSF view is to be rendered,ICEfaces will render the new JSF view by performing a complete update of
http://www.icesoft.org/projects/ICEfaceshttp://www.icesoft.org/projects/ICEfaces


78/120

Chapter 11. ICEfaces 3 Portlet Devel...


the markup contained in the affected portlet, rather than causing the entirebrowser page to reload

ICEfaces portlets will not disturb other portlets on the same portal page

11.3. ICEfaces Ajax Push and Inter-PortletCommunication

While the Portlet 2.0 standard defines techniques for performing inter-portletcommunication (IPC), they cause either an HTTP GET or HTTP POST whichresults in a full page reload and a disruptive end-user experience. ICEfacesprovides a natural way for portlets to perform IPC via ICEfaces Ajax Push.

ICEfaces pioneered Ajax Push, which is sometimes referred to as ReverseAjax or Comet. The technology provides the ability for server-initiated eventsto cause incremental page updates to be sent to the browser. With ICEfacesAjax Push, developers can create collaborative and dynamic enterpriseapplications like never before.

Because the mechanism facilitates asynchronous updates from the serverto the client, interaction with one ICEfaces portlet can trigger communicationwith other ICEfaces portlets by changing values in JSF backing and modelmanaged-beans. This mechanism is not restricted to IPC among portletson the same portal page in a single browser, but can include updating otherbrowsers that are interacting with the same portal page. The result is not justinter-portlet communication, but inter-portlet, inter-browser communication.Additionally, ICEfaces Ajax Push solves the potentially disruptive end-userexperience associated with the Portlet 2.0 standard IPC techniques.

Figure 11.1. Illustration of IPC with ICEfaces Ajax Push


79/120

ICEfaces Ajax Push and Inter-PortletCommunication


The following is a list of guidelines for achieving IPC with ICEfaces Ajax Push

Package the portlets that need to communicate in the same WAR.

In order to share data between portlets, use application-scopedbeans or request-scoped beans that store data inPortletSession.APPLICATION_SCOPE.

Use the ICEfaces Ajax Push SessionRenderer to trigger client updateswhen the shared data changes.


80/120



Example 11.1. Chat Portlet Managed-Bean

/*

* This is a file named ChatRoomManagedBean.java* that is registered as a JSF managed-bean in

* application scope. It maintains a chat log

* that participates in ICEfaces Ajax Push using

* the SessionRenderer.

*/

@ManagedBean(name = "chatRoomManagedBean")

@RequestScoped

public class ChatRoomManagedBean {

private String messageText;

private List messages = new ArrayList();

private static final String

AJAX_PUSH_GROUP_NAME = "chatRoom";

public ChatRoomsModel() {

SessionRenderer.addCurrentSession(

AJAX_PUSH_GROUP_NAME);

}

@PreDestroy

public void preDestroy() throws Exception {

SessionRenderer.removeCurrentSession( AJAX_PUSH_GROUP_NAME);

}

public void addMessage(ActionEvent actionEvent) {

messages.add(messageText);

SessionRenderer.render(AJAX_PUSH_GROUP_NAME);

}

public List getMessages() {

return messages;

}

public String getMessageText() {

return messageText;

}

public void setMessageText(String messageText) {

this.messageText = messageText;

}

}


81/120


82/120



http://www.liferay.com/community/liferay-projects/liferay-faces/ demos

11.4. ICEfaces Themes and Portal Themes

The ICEfaces Component Suite fully supports consistent component stylingvia a set of predefined CSS style classes and associated images. Changingthe component styles for a web application developed with the ICEfacesComponent Suite is as simple as changing the style sheet used. ICEfacesships with a set of predefined style sheets are available to be used as-is, orcustomized to meet the specific requirements of the application. There arefive predefined ICEfaces style sheets included, two of which are designed tobe used inside a portlet container:

rime.css

rime-portlet.css

xp.css

xp-portlet.css

royale.css

Example 11.3. Specifying the portlet-compatible version ofthe ICEfaces "XP" theme

...

The Portlet 1.0 and 2.0 standards document a set of common CSS classnames that should be applied to specific page elements in order to integratewith the portlet containers theme mechanism. When running in a portlet
http://www.liferay.com/community/liferay-projects/liferay-faces/demoshttp://www.liferay.com/community/liferay-projects/liferay-faces/demos


83/120

ICEfaces Themes and Portal Themes


container, ICEfaces 1.8 compatibility components will automatically renderthe following subset of Portlet 1.0 CSS class names where appropriate

portlet-form-button

portlet-form-field

portlet-form-input-field

portlet-form-label

portlet-menu

portlet-menu-cascade-item

portlet-menu-item

portlet-menu-item-hover

portlet-section-alternate

portlet-section-body

portlet-section-footer

portlet-section-header

portlet-msg-alert

portlet-msg-error

portlet-msg-info

To disable this feature, developers can specify thecom.icesoft.faces.portlet.renderStyles context parameter in theWEB-INF/web.xml configuration file and set its value to false.

Example 11.4. Disabling automatic rendering of Portlet 1.0/ 2.0 standard CSS class names in the WEB-INF/web.xmlconfiguration file

com.icesoft.faces.portlet.renderStyles

false


84/120



11.5. ICEfaces Themes and Liferay Themes

Liferay Portal supports styling for Portlet 1.0 and 2.0 standard CSS class

names as well as a set of vendor-specific CSS class names within thecontext of a Liferay theme. However, since Liferay themes do not containstyling for the ICEfaces Component Suite, it is necessary to select anICEfaces style sheet that is visually compatible with the Liferay theme.

On some occasions, it becomes necessary to override some of the stylingin a Liferay theme in order to make it more visually compatible with anICEfaces portlet. For example, Liferay themes typically render spans ofclass portlet-msg-error with a margin that has too much space to be placedalongside a rendered ice:inputText component tag.

Example 11.5. Overriding styling in a Liferay themefrom within a Facelet view so that rendered output fromice:messages and ice:message have a more narrow margin

...

/*

* This is a separate file named liferay-theme-override.css

*/

.example-icefaces-portlet .portlet-msg-error {

margin: 1px 0px 0px 0px;

padding: 1px 5px 1px 24px;

}


85/120


86/120


87/120


Chapter 12. Overview

Liferay Faces Portal is a JAR that JSF developers can add as a dependencyto their portlet WAR projects in order to utilize Liferay-specific utilities and UIcomponents.

The project home page can be found athttp://www.liferay.com/community/liferay-projects/liferay-faces/portal
http://www.liferay.com/community/liferay-projects/liferay-faces/portal


88/120



89/120


Chapter 13. LiferayFacesContextJSF web application developers typically callFacesContext.getCurrentInstance() in order to obtain the ThreadLocalsingleton instance associated with the current request. While JSFportlet developers can certainly do the same, it's easier to callLiferayFacesContext.getInstance() which returns an application-scopedsingleton instance.

Example 13.1. Obtaining the LiferayFacesContext SingletonInstance

public class SessionScopedManagedBean {

private final LiferayFacesContext liferayFacesContext =

LiferayFacesContext.getInstance();

public List getDocuments() {

List documents;

try {

documents = DLFileEntryLocalServiceUtil.getFileEntries(folderId);

}

catch (Exception e) {

logger.error(e.getMessage(), e);

// Don't have to call LiferayFacesContext.getInstance() first

since

// a reference to it was obtained when the bean was created.

liferayFacesContext.addGlobalUnexpectedErrorMessage();

}

return documents;

}

}

LiferayFacesContext is an abstract class that extends the JSF FacesContextabstract class. Because of thism it supplies all the same methodsignatures and can therefore do anything that FacesContext can do. TheLiferayFacesContext implements the delegation design pattern for methodsdefined by FacesContext by first calling FacesContext.getCurrentInstance()and then delegating to corresponding methods. The benefit ofusing this technique is that JSF portlet developers only have to callLiferayFacesContext.getInstance() once, and can save the singleton objectreference for future use.
http://docs.oracle.com/cd/E17802_01/j2ee/javaee/javaserverfaces/2.0/docs/api/javax/faces/context/FacesContext.htmlhttp://en.wikipedia.org/wiki/Delegation_patternhttp://docs.oracle.com/cd/E17802_01/j2ee/javaee/javaserverfaces/2.0/docs/api/javax/faces/context/FacesContext.htmlhttp://docs.oracle.com/cd/E17802_01/j2ee/javaee/javaserverfaces/2.0/docs/api/javax/faces/context/FacesContext.html


90/120



91/120


Chapter 14. Liferay Faces PortalExpression Language Additions

Liferay Faces Portal introduces several variables into the ExpressionLanguage (EL).


92/120

Chapter 14. Liferay Faces Portal Exp...


Table 14.1. Liferay Faces Portal EL Variables

Type: com.liferay.portal.security.permission.Permis

liferay.portalURL The absolute URL for the portal.

Type: String

liferay.portlet the containing Liferay Portletassociated with the PortletRequest .

Type: com.liferay.portal.model.Portlet

liferay.portraitURL Designed to be called from the EL bypassing a Liferay User or userId asan array index, returns the absoluteURL to the user's portrait.

Type: String

liferay.theme The Liferay Theme associated with theLiferay Layout .

Type: com.liferay.portal.model.Theme

liferay.themeDisplay The Liferay ThemeDisplay associatedwith the PortletRequest .

Type: com.liferay.portal.theme.ThemeDisplay

liferay.themeImageURL Designed to be called from the ELby passing a relative path to a themeimage as an array index, returns theabsolute URL to the theme image.

Type: String

liferay.themeImagesURL The absolute URL for the image pathassociated with the current LiferayTheme.

Type: String

liferay.user The Liferay User associated with thePortletRequest .

Type: com.liferay.portal.model.Userliferay.user