PRIMEFACES MOBILE USERS GUIDE

Author
aatay ivici

0.9.2

This guide is dedicated to my wife Nurcan, without her support PrimeFaces wouldnt exist.

aatay ivici

About the Author! Introduction!

1.1 What is PrimeFaces Mobile?! 1.2 Prime Teknoloji!

5 6
6 6

2. Setup!
2.1 Download! 2.2 Dependencies! 2.3 Conguration! 2.4 Taglib! 2.5 RenderKit!

7
7 7 7 8 8

3. Pages! 4. Navigations!
4.1 Local Navigations! 4.2 External Navigations! 4.3 Transitions! 4.4 Client API!

9 11
11 13 13 13

5. Ajax! 6. Mobile Components!

6.1 ButtonGroup! 6.2 Content! 6.3 Field! 6.4 Footer! 6.5 Header! 6.6 InputRange !
3

14 15
15 17 18 19 20 22

6.7 NavBar! 6.8 Page! 6.9 Switch! 6.10 View!

24 26 27 29

7. RenderKit !
7.1 h:outputLink! 7.2 h:panelGrid! 7.3 h:form! 7.4 p:button! 7.5 p:commandButton! 7.6 p:dataList! 7.7 p:inputText! 7.8 p:inputTextarea ! 7.9 p:panel! 7.10 p:accordionPanel! 7.11 p:selectBooleanCheckbox! 7.12 p:selectManyCheckbox! 7.13 p:selectOneRadio !

30
30 30 30 30 31 31 33 33 33 34 34 34 35

8. Themes!
8.1 Theme Framework! 8.2 Creating a Custom Theme!

36
36 37

9. Extensions! 10. Samples! 11. Supported Platforms!

4

38 39 40

About the Author

aatay ivici is a member of JavaServer Faces Expert Group, the founder and project lead of PrimeFaces and PMC member of open source JSF implementation Apache MyFaces. Hes a recognized speaker in international conferences including SpringOne, Jazoon, JAX, W-JAX, JSFSummit, JSFDays, Con-Fess and many local events such as JUGs. aatay is also an author and technical reviewer of a couple books regarding web application development with Java and JSF. As an experienced trainer, he has trained over 300 developers on Java EE technologies mainly JSF, Spring, EJB 3.x and JPA. aatay is currently working as a principal consultant for Prime Teknoloji, the company he cofounded in Turkey.

1. Introduction
1.1 What is PrimeFaces Mobile?
PrimeFaces Mobile is a UI kit to implement JSF pages that are optimized for mobile devices with a native look and feel. Mobile RenderKit for standard JSF and core PrimeFaces components. Mobile JSF components. Same backend model for desktop web and mobile web. Wide range of platform support. Ajax features to bring native application experience. Nothing required to install on device. Powered by jQuery Mobile

1.2 Prime Teknoloji

PrimeFaces Mobile is maintained by Prime Teknoloji, a Turkish software development company specialized in Agile and Java EE consulting. PrimeFaces Team members are full time engineers at Prime Teknoloji. aatay ivici - Architect and Lead Developer Levent Gnay - Core Developer / QA&Test Yiit Darn - Core Developer / QA&Test Mustafa Dagn - Core Developer / QA&Test Cenk ivici - Mentor

2. Setup
2.1 Download
PrimeFaces Mobile has a single jar called primefaces-mobile-{version}.jar. There are two ways to download this jar, you can either download from PrimeFaces homepage or if you are a maven user you can define it as a dependency. Download Manually Three different artifacts are available for each PrimeFaces Mobile version, binary, sources and bundle. Bundle contains binary, sources and javadocs.
http://www.primefaces.org/downloads.html

Download with Maven Group id of the dependency is org.primefaces and artifact id is primefaces-mobile.
<dependency> <groupId>org.primefaces</groupId> <artifactId>primefaces-mobile</artifactId> <version>0.9.2</version> </dependency>

In addition to the configuration above you also need to add PrimeFaces maven repository to the repository list so that maven can download it.
<repository> <id>prime-repo</id> <name>Prime Repo</name> <url>http://repository.primefaces.org</url> </repository>

2.2 Dependencies
PrimeFaces Mobile only requires a JAVA 5+ runtime, a JSF 2.0 implementation and PrimeFaces Core as mandatory dependencies. It is suggested to use the latest core available in combination with mobile.

2.3 Configuration
PrimeFaces Mobile does not require any mandatory configuration.
7

2.4 Taglib
PrimeFaces Mobile component library namespace should be added to your mobile pages.
xmlns:pm="http://primefaces.org/mobile">

2.5 RenderKit
PrimeFaces Mobile provides a Mobile Renderkit for some standard JSF and core PrimeFaces Components, in order to run PrimeFaces Mobile, this render kit should be enabled. There are a couple of ways listed below you can choose. Id of the renderkit is PRIMEFACES_MOBILE. Request Parameter Access a mobile page with javax.faces.RenderKitId parameter. This approach is for quick testing and not suggested as maintaining a request parameter is not easy.
http://www.yourapp.com?javax.faces.RenderKitId=PRIMEFACES_MOBILE

(Suggested) Configure Application Wide Define in faces-config.xml. This method is suggested if your mobile pages are in a different application than the non-mobile pages like http://mobile.yourapp.com.
<application> <default-render-kit-id>PRIMEFACES_MOBILE</default-render-kit-id> </application>

Decide Yourself Write a viewhandler by overriding calculateRenderKitId API and decide when to display the page in mobile mode. This approach is suggested if your mobile and non-mobile pages are in same application and you need to switch renderkits on-the-fly.

3. Pages
A mobile page is a simple xhtml based JSF view that can have of one or more views. A view is a screen in your layout. Following is a simple example having page, view, header and content components.
<f:view xmlns="http://www.w3.org/1999/xhtml" xmlns:f="http://java.sun.com/jsf/core" xmlns:p="http://primefaces.org/ui" xmlns:pm="http://primefaces.org/mobile" contentType="text/html"> <pm:page title="Hello World"> <pm:view id="main"> <pm:header title="Header" /> <pm:content> Content </pm:content> </pm:view> </pm:page> </f:view>

You can add more views by using a similar approach using pm:view component. Following is a multi view page.
9

<f:view xmlns="http://www.w3.org/1999/xhtml" xmlns:f="http://java.sun.com/jsf/core" xmlns:p="http://primefaces.org/ui" xmlns:pm="http://primefaces.org/mobile" contentType="text/html"> <pm:page title="Hello World"> <pm:view id="main"> <pm:header title="Header" /> <pm:content> Content </pm:content> </pm:view> <pm:view id="second"> <pm:header title="Second View Header" /> <pm:content> Second View Page </pm:content> </pm:view> <pm:view id="third"> <pm:header title="Third View Header" /> <pm:content> Third View Page </pm:content> </pm:view> </pm:page> </f:view>

By default, first view on page is displayed initially.

10

4. Navigations
Navigation in PrimeFaces Model can be between local views with or without ajax and to an external page outside of application.

4.1 Local Navigations

Local navigation means navigation from a view to another view on same page.

GET Style This type of navigation behaves like a GET navigation although there is no actual HTTP request.
<f:view xmlns="http://www.w3.org/1999/xhtml" xmlns:f="http://java.sun.com/jsf/core" xmlns:p="http://primefaces.org/ui" xmlns:pm="http://primefaces.org/mobile" contentType="text/html"> <pm:page title="Mobile"> <pm:view id="viewA"> <pm:header title="A" /> <pm:content> <h:outputLink value="#viewB">Go to B</h:outputLink> </pm:content> </pm:view> <pm:view id="viewB"> <pm:header title="B" />

<pm:content> B View </pm:content> </pm:view> </pm:page>

</f:view>

11

POST Style This navigation approach integrated with JSF Navigation Model is used when you do an ajax request and need to navigate to another view.
<f:view xmlns="http://www.w3.org/1999/xhtml" xmlns:f="http://java.sun.com/jsf/core" xmlns:p="http://primefaces.org/ui" xmlns:pm="http://primefaces.org/mobile" contentType="text/html"> <pm:page title="Mobile"> <pm:view id="viewA"> <pm:header title="A" /> <pm:content> <h:form> <p:commandButton value=Go action=#{bean.method} /> </h:form> </pm:content> </pm:view> <pm:view id="viewB"> <pm:header title="B" />

<pm:content> B View </pm:content> </pm:view> </pm:page>

</f:view>

public String method() { return pm:viewB; }

When the outcome is prefixed by pm:, PrimeFaces Mobile navigates to the View B after ajax request is completed. You can also use the outcome directly as;
<p:commandButton value=Go action=pm:viewB />

Reverse Effect By default, slide forward animation is used to navigate between local views, in case you need to display slide backwards, append reverse=true string to your outcome.
<p:commandButton value=Go back to B action=pm:viewB?reverse=true /> <h:outputLink value="#viewB?reverse=true">Go back to B</h:outputLink>

12

4.2 External Navigations

Navigation from a mobile application to an external resource is not different then doing it in a regular web page.
<h:outputLink value="http://www.primefaces.org"> Go Prime </h:outputLink>

4.3 Transitions
Various types of transition effects are supported to display during navigation. Please note that transitions are not supported in all devices and fade is used as a fallback for the older devices. Add transition parameter to the outcome to enable effects.
<h:outputLink value="#viewB?transition=pop"> Go </h:outputLink>

For actions same can be applied as;

public String method() { return pm:viewB&transition=pop; }

Here is the list of all supported transitions; fade, pop, flip, turn, flow, slide, slideup, slidedown, none.

4.4 Client API

Use PrimeFaces.navigate(view, cfg) to navigate manually.
PrimeFaces.navigate('#viewB', { reverse: true|false ,transition: 'fade' });

//defaults to false //optional transition name

13

5. Ajax
A mobile page can be enhanced with ajax features using regular PrimeFaces Ajax Framework. Important note is avoid updating whole views but the contents of the views. Following is a simple example;
<pm:page title="Mobile"> <pm:view id="main"> <pm:header title="Ajax" /> <pm:content> <h:form> <p:inputText value="#{bean.text}" /> <p:commandButton value="Update" update="display" /> <h:outputText id="display" value="#{bean.text}"/> </h:form> </pm:content> </pm:view> </pm:page>

PrimeFaces Ajax extension features a special integration with jQuery Mobiles progressively enhanced UI controls and built-in ajax status dialog whereas core JSF ajax does not. If you update a component with core JSF ajax, you will lose the mobile optimized UI. To avoid this always use PrimeFaces Ajax instead as PF is aware of how jQuery Mobile works. Updating a component on another view is easy with proper referencing as well, here is an example;
<pm:page title="Mobile"> <pm:view id="viewA"> <pm:header title="A" /> <pm:content> <h:form> <p:inputText value="#{bean.text}" /> <p:commandButton value="Update" update=":formB:display" /> </h:form> </pm:content> </pm:view> <pm:view id="viewB"> <pm:header title="B" /> <pm:content> <h:form id="formB"> <h:outputText id="display" value="#{bean.text}"/> <h:form> </pm:content> </pm:view> </pm:page>

Note that commandButton is referencing to display component using naming container separator as prefix since display component is in another naming container(form). Views themselves are not naming containers.
14

6. Mobile Components
PrimeFaces Mobile provides a set of mobile components that are specific to mobile platforms.

6.1 ButtonGroup
ButtonGroup component groups a set of buttons.

Info
Tag Component Class Component Type Component Family Renderer Type Renderer Class buttonGroup org.primefaces.mobile.component.buttongroup.ButtonGroup org.primefaces.mobile.ButtonGroup org.primefaces.mobile.component org.primefaces.mobile.component.ButtonGroupRenderer org.primefaces.mobile.component.buttongroup.ButtonGroupRenderer

Attributes
Name id rendered Default null TRUE String Boolean Type Description Unique identifier of the component Boolean value to specify the rendering of the component, when set to false component will not be rendered. An el expression that maps to a server side UIComponent instance in a backing bean Type of the orientation, can be vertical or horizontal. Inline style of the component. Style class of the component.

binding orientation style styleClass

null vertical null null

Object String String String

15

Getting started with ButtonGroup Buttons to be grouped are placed inside the button group.
<pm:buttonGroup> <p:commandButton value="Yes" /> <p:commandButton value="No" /> </pm:buttonGroup>

Orientation Default orientation is vertical and other option is horizontal.

<pm:buttonGroup orientation="horizontal"> <p:commandButton value="Yes" /> <p:commandButton value="No" /> </pm:buttonGroup>

16

6.2 Content
Content is used the place the contents of a mobile view. Info
Tag Component Class Component Type Component Family Renderer Type Renderer Class content org.primefaces.mobile.component.content.Content org.primefaces.mobile.Content org.primefaces.mobile.component org.primefaces.mobile.component.ContentRenderer org.primefaces.mobile.component.content.ContentRenderer

Attributes
Name id rendered Default null TRUE String Boolean Type Description Unique identifier of the component Boolean value to specify the rendering of the component, when set to false component will not be rendered. An el expression that maps to a server side UIComponent instance in a backing bean Inline style of the component. Style class of the component.

binding style styleClass

null null null

Object String String

Getting started with Content See section 3 (Pages) for more information on how content component is used.

17

6.3 Field
Field component is used to align a label and a related input. Info
Tag Component Class Component Type Component Family Renderer Type Renderer Class field org.primefaces.mobile.component.field.Field org.primefaces.mobile.Field org.primefaces.mobile.component org.primefaces.mobile.component.FieldRenderer org.primefaces.mobile.component.field.FieldRenderer

Attributes
Name id rendered Default null TRUE String Boolean Type Description Unique identifier of the component Boolean value to specify the rendering of the component, when set to false component will not be rendered. An el expression that maps to a server side UIComponent instance in a backing bean

binding

null

Object

Getting started with Field Field component wraps the label and the input.
<pm:field> <h:outputLabel for="input" value="Input: "/> <h:inputText id="inputText" value="#{bean.value}"/> </pm:field>

Note that not all platforms due the screen size differences support field component. Integrated Field (Suggested) Field alignment is a built-in feature of PrimeFaces Mobile Renderkit, same can be written as;
<p:inputText id="inputText" value="#{bean.value}" label="Input: "/>

18

6.4 Footer
Footer is used as a bottom content container of a view. Info
Tag Component Class Component Type Component Family Renderer Type Renderer Class footer org.primefaces.mobile.component.footer.Footer org.primefaces.mobile.Footer org.primefaces.mobile.component org.primefaces.mobile.component.FooterRenderer org.primefaces.mobile.component.footer.FooterRenderer

Attributes
Name id rendered Default null TRUE String Boolean Type Description Unique identifier of the component Boolean value to specify the rendering of the component, when set to false component will not be rendered. An el expression that maps to a server side UIComponent instance in a backing bean Whether or not the position of footer is fixed. Theme swatch. Inline style of the component. Style class of the component.

binding fixed swatch style styleClass

null FALSE null null null

Object Boolean String String String

Getting started with Footer To begin with, see section 3 (Pages) for more information on how content component is used. A footer is used inside a mobile view.
<pm:view id="main"> //... <pm:footer> Footer Content </pm:footer> </pm:view>

19

6.5 Header
Header is used as a top content container of a view. Info
Tag Component Class Component Type Component Family Renderer Type Renderer Class header org.primefaces.mobile.component.header.Header org.primefaces.mobile.Header org.primefaces.mobile.component org.primefaces.mobile.component.HeaderRenderer org.primefaces.mobile.component.header.HeaderRenderer

Attributes
Name id rendered Default null TRUE String Boolean Type Description Unique identifier of the component Boolean value to specify the rendering of the component, when set to false component will not be rendered. An el expression that maps to a server side UIComponent instance in a backing bean Title text of the header. Whether or not the position of footer is fixed. Theme swatch. Inline style of the component. Style class of the component.

binding title fixed swatch style styleClass

null null FALSE null null null

Object String Boolean String String String

Getting started with Header As described in section 3, a header is defined within a view.
<pm:view id="main"> <pm:header> Header Content </pm:header> //... </pm:view>

20

Fixed Position When fixed position is enabled, header scrolls along with the view.
<pm:header title="Header" fixed="true"/>

Left and Right Content Placing buttons at left and right side of a header is common case in a mobile view. Header provides left and right facets to implement this.
<pm:header title="Prime"> <f:facet name="left"> <p:button value="Back" icon="back" href="#main"/> </f:facet> <f:facet name="right"> <p:button value="Settings" icon="gear" href="#settings"/> </f:facet> </pm:header>

21

6.6 InputRange
InputRange is a slider to provide number input. Info
Tag Component Class Component Type Component Family Renderer Type Renderer Class inputRange org.primefaces.mobile.component.inputrange.InputRange org.primefaces.mobile.InputRange org.primefaces.mobile.component org.primefaces.mobile.component.InputRangeRenderer org.primefaces.mobile.component.inputrange.InputRangerRenderer

Attributes
Name id rendered binding value converter Default null TRUE null null null Type String Boolean Object Object Converter /String Description Unique identifier of the component Boolean value to specify the rendering of the component, when set to false component will not be rendered. An el expression that maps to a server side UIComponent instance in a backing bean Value of the component than can be either an EL expression of a literal text An el expression or a literal text that defines a converter for the component. When its an EL expression, its resolved to a converter instance. In case its a static text, it must refer to a converter id When set true, process validations logic is executed at apply request values phase for this component. Marks component as required A method binding expression that refers to a method validationg the input A method binding expression that refers to a method for handling a valuchangeevent Message to be displayed when required field validation fails. Message to be displayed when conversion fails. 0 100
22

immediate required validator valueChangeListener requiredMessage converterMessage minValue maxValue

FALSE FALSE null null null null null null

Boolean Boolean Method Expr Method Expr String String Number Number

Name style styleClass step disabled label

Default null null 1 FALSE null

Type String String Number Boolean string

Description Inline style of the component. Style class of the component. Step factor. Disables the component when true. User presentable name.

Getting started with InputRange InputRange is an input component that requires a number value to bind.
public class Bean { private int value; } //getter-setter

<pm:inputRange value="#{bean.value}" />

23

6.7 NavBar
NavBar is a grouping component for a set of buttons in a bar. Info
Tag Component Class Component Type Component Family Renderer Type Renderer Class navBar org.primefaces.mobile.component.navbar.NavBar org.primefaces.mobile.NavBar org.primefaces.mobile.component org.primefaces.mobile.component.NavBarRenderer org.primefaces.mobile.component.navbar.NavBarRenderer

Attributes
Name id rendered binding Default null TRUE null Type String Boolean Object Description Unique identifier of the component Boolean value to specify the rendering of the component, when set to false component will not be rendered. An el expression that maps to a server side UIComponent instance in a backing bean

Getting started with NavBar NavBar can be placed inside a header or directly inside a content.

24

<pm:view id="navbar"> <pm:header title="NavBar"> <pm:navBar> <p:button value="Home" icon="home" href="#main?reverse=true" styleClass="ui-btn-active"/> <p:button value="Info" icon="info" href="#main?reverse=true" /> <p:button value="Search" icon="search" href="#main?reverse=true" /> </pm:navBar> </pm:header> <pm:content> <pm:navBar> <p:button value="Home" icon="home" href="#main?reverse=true" styleClass="ui-btn-active"/> <p:button value="Info" icon="info" href="#main?reverse=true" /> <p:button value="Search" icon="search" href="#main?reverse=true" /> <p:button value="Favs" icon="star" href="#main?reverse=true" /> <p:button value="Setup" icon="gear" href="#main?reverse=true" /> </pm:navBar> </pm:content> </pm:view>

Adding ui-btn-active style class displays a button in a nav bar as active. Note that up to 5 buttons can be placed inside a navbar.

25

6.8 Page
Page is the core of a mobile page that contains one or more views and provides page wide options. Info
Tag Component Class Component Type Component Family Renderer Type Renderer Class page org.primefaces.mobile.component.page.Page org.primefaces.mobile.Page org.primefaces.mobile.component org.primefaces.mobile.component.PageRenderer org.primefaces.mobile.component.page.PageRenderer

Attributes
Name id rendered Default null TRUE Type String Boolean Description Unique identifier of the component Boolean value to specify the rendering of the component, when set to false component will not be rendered. An el expression that maps to a server side UIComponent instance in a backing bean Title of the page. Name of animation to use in view navigation. Name of animation to use when displaying a dialog. Text to display in built-in ajax status. Meta settings for viewport. Manifest setting of the document. When enabled form components displayed smaller.

binding title defaultPageTransition defaultDialogTransition loadingMessage viewport manifest mini

null FALSE slide pop loading null null FALSE

Object Boolean String String String String String Boolean

Getting started with Page See section 3 (Pages) for more information on how page component is basically used. Event Facets Page provides various facets as extension points, see section 9 for more information.
26

6.9 Switch
Switch is used to choose a binary selection. Info
Tag Component Class Component Type Component Family Renderer Type Renderer Class page org.primefaces.mobile.component.uiswitch.UISwitch org.primefaces.mobile.UISwitch org.primefaces.mobile.component org.primefaces.mobile.component.UISwitchRenderer org.primefaces.mobile.component.uiswitch.UISwitchRenderer

Attributes
Name id rendered Default null TRUE String Boolean Type Description Unique identifier of the component Boolean value to specify the rendering of the component, when set to false component will not be rendered. An el expression that maps to a server side UIComponent instance in a backing bean Value of the component than can be either an EL expression of a literal text An el expression or a literal text that defines a converter for the component. When its an EL expression, its resolved to a converter instance. In case its a static text, it must refer to a converter id When set true, process validations logic is executed at apply request values phase for this component. Marks component as required A method binding expression that refers to a method validationg the input A method binding expression that refers to a method for handling a valuchangeevent Message to be displayed when required field validation fails. Message to be displayed when conversion fails.
27

binding value converter

null null null

Object Object Converter/String

immediate

FALSE

Boolean

required validator valueChangeListener requiredMessage converterMessage

FALSE null null null null

Boolean Method Expr Method Expr String String

Name label onLabel offLabel

Default null null null String String String

Type

Description Label of the components. Text for true. Text for false.

Getting started with Switch Switch is an input component that requires a boolean value to bind.
public class Bean { private boolean value; } //getter-setter

<pm:switch value="#{bean.value}" onLabel="Yes" offLabel="No"/>

28

6.10 View
View represents a screen in a mobile page. Info
Tag Component Class Component Type Component Family Renderer Type Renderer Class view org.primefaces.mobile.component.view.View org.primefaces.mobile.View org.primefaces.mobile.component org.primefaces.mobile.component.ViewRenderer org.primefaces.mobile.component.view.ViewRenderer

Attributes
Name id rendered Default null TRUE Type String Boolean Description Unique identifier of the component Boolean value to specify the rendering of the component, when set to false component will not be rendered. An el expression that maps to a server side UIComponent instance in a backing bean Title of the view. Theme swatch.

binding title swatch

null FALSE null

Object Boolean String

Getting started with View See section 3 (Pages) for more information on how view component is used.

29

7. RenderKit
In addition to the mobile specific components, PrimeFaces Mobile also provides Mobile optimized renderers for some core JSF and PrimeFaces components. Following is the list of components with mobile renderers. Note that mobile renderers may not support all the features of the component available in a desktop web environment.

7.1 h:outputLink
Core output link component is extended to integrate with PrimeFaces Mobile navigation model, see section 4 for more information about Navigations. For example to go from one view to another;
<h:outputLink value="#viewIdHere">Navigate</h:outputLink>

7.2 h:panelGrid
PanelGrid component is used to do create a grid layout with a table-less approach.
<h:panelGrid columns="4"> <h:outputText value="Cell <h:outputText value="Cell <h:outputText value="Cell <h:outputText value="Cell <h:outputText <h:outputText <h:outputText <h:outputText </h:panelGrid> value="Cell value="Cell value="Cell value="Cell

1" 2" 3" 4" 5" 6" 7" 8"

/> /> /> /> /> /> /> />

7.3 h:form
In a mobile environment, standard form component always sends javax.faces.RenderKitId = PRIMEFACES_MOBILE as a request parameter to set mobile renderkit to keep the mobile renderkit if you are using the request parameter approach defined in section 2.5

7.4 p:button
Button display is optimized for a mobile platform and integrated with mobile navigation model.
<p:button value="Home" icon="home" href="#main" />

30

7.5 p:commandButton
CommandButton display is optimized for a mobile platform and integrated with mobile navigation model. Core ajax features are also available.
<p:commandButton value="With Icon" icon="check" actionListener="#{bean.method}" update="othercomponent" global="false" />

7.6 p:dataList
DataList is an important component for Mobile featuring various display modes for data display. DataList can be used to display children only or iterate them for each data item. ReadOnly
<p:dataList> <h:outputText value="Item 1" /> <h:outputText value="Item 2" /> <h:outputText value="Item 3" /> </p:dataList>

Links
<p:dataList> <h:outputLink value="#main">Item 1</h:outputLink> <h:outputLink value="#main">Item 2</h:outputLink> <h:outputLink value="#main">Item 3</h:outputLink> </p:dataList>

31

Inset
<p:dataList type="inset"> <h:outputLink value="#main">Item 1</h:outputLink> <h:outputLink value="#main">Item 2</h:outputLink> <h:outputLink value="#main">Item 3</h:outputLink> </p:dataList>

Custom Content
<p:dataList value="#{ringBean.players}" var="player"> <p:graphicImage value="/images/barca/#{player.photo}" /> <h3><h:outputLink value="#main">#{player.name}</h:outputLink></h3> <p>#{player.position}</p> <h:outputText styleClass="ui-li-count" value="#{player.number}" /> </p:dataList>

Search Filter As filter is a mobile specific attribute, define it with f:attribute.

<p:dataList value="#{ringBean.players}" var="player"> <f:attribute name="filter" value="true" /> //content </p:dataList>

32

Notes on Mobile DataList Ajax pagination is not supported. Use PrimeFaces Ajax components or APIs to update the datalist, using core JSF ajax cannot update the datalist properly as explained in section 5 Ajax. Wrap the content inside a column component in case you do a selection. This is a requirement in core UIData to process selection properly. Use p:separator with a custom content to add a divider between list items.

7.7 p:inputText
InputText display is optimized for a mobile platform, in addition using type attribute you can customize the look and feel in supported browsers. For example following virtual display for the input text only displays numbers in iOS5.
<p:inputText id="age" type="number" value="#{bean.value}" />

7.8 p:inputTextarea
Rendering is optimized for a mobile platforms.

7.9 p:panel
PrimeFaces Panel component is toggleable by default in a mobile environment.
<p:panel header="Expanded"> Toggle panel content </p:panel> <p:panel header="Collapsed" collapsed="true"> Initially collapsed content </p:panel>

33

7.10 p:accordionPanel
<p:accordionPanel> <p:tab title="Title 1"> Content 1 </p:tab> <p:tab title="Title 2"> Content 2 </p:tab> <p:tab title="Title 3"> Content 3 </p:tab> </p:accordionPanel>

7.11 p:selectBooleanCheckbox
<p:selectBooleanCheckbox value="#{true}" itemLabel="I agree" />

7.12 p:selectManyCheckbox

34

7.13 p:selectOneRadio

35

8. Themes
8.1 Theme Framework
jQuery Mobile provides themes with multi swatches each having a different color scheme. PrimeFaces Mobile currently provides simple integration with this model and advanced integration is in the roadmap. View, Header and Footer components are equipped with swatch attribute to select the swatch to use in a mobile view. Default theme has five swatches; a, b, c, d and e.

Note that default swatch for view content is c and for header-footer it is a. Following is a simple page with b for header and e for content.
<pm:page title="Hello World"> <pm:view id="main" swatch="e" <pm:header title="Header" swatch="b"/> <pm:content> Content </pm:content> </pm:view> </pm:page>

36

8.2 Creating a Custom Theme

jQuery Mobile provides a mobile themeroller tool to create custom themes easily.

http://jquerymobile.com/themeroller/

1) Once you have created, give a name (e.g. optimus) and downloaded your theme from themeroller, place the contents of the zip file in your webapp like; - %webroot% - themes - images - optimus.min.css 2) Configure PrimeFaces Mobile not to include default theme.
<context-param> <param-name>primefaces.mobile.THEME</param-name> <param-value>none</param-value> </context-param>

3) Use the pre-init facet to place your theme.

<pm:page> <f:facet name="preinit"> <link type="text/css" rel="stylesheet" href="#{request.contextPath}/mobile/themes/optimus.css" /> </f:facet> </pm:page>

Do not use h:outputStylesheet as it cant load icons referenced from css. 4) Enjoy!
37

9. Extensions
PrimeFaces Mobile provides various facets to hook-in underlying jQuery mobile settings as extension points. preinit Rendered before any resources that are included by default. See section 8.2 for a use case. postinit Rendered after all resources are included. meta Meta settings for the document.
<pm:page> <f:facet name="meta"> <meta name="apple-mobile-web-app-capabel" content="yes" /> </f:facet> </pm:page>

config Used to define global settings for jQuery Mobile.

<pm:page> <f:facet name="config"> $.mobile.minScrollBack = 200; </f:facet> </pm:page>

38

10. Samples
PrimeFaces Mobile has various samples on PrimeFaces Showcase demonstrating different features.

39

11. Supported Platforms

PrimeFaces Mobile is powered by jQuery Mobile which supports various mobile platforms based on a grade level. See jQuery Mobile documentation for the detailed information;
http://jquerymobile.com/gbs/

40

THE END

41