PRIMEFACES MOBILE USER'S GUIDE
Contents
1. PRIMEFACES MOBILE USER S GUIDE Author Cagatay Civici This guide is dedicated to my wife Nurcan without her support PrimeFaces wouldn t exist a atay ivici About the Author Introduction 1 1 What is PrimeFaces Mobile 1 2 Prime Teknoloji 2 Setup 2 1 Download 2 2 Dependencies 2 3 Configuration 2 4 Taglib 2 5 RenderKit Pages Navigations 4 1 Local Navigations 4 2 External Navigations 5 Ajax 6 Mobile Components 6 1 ButtonGroup 6 2 Content 6 3 Field 6 4 Footer 6 5 Header 6 6 InputRange 6 7 NavBar 6 8 Page a o o o NM N N oo OO Gi ES 13 14 15 15 17 18 19 20 22 24 26 6 9 Switch 6 10 View 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 8 Themes 8 1 Theme Framework 8 2 Creating a Custom Theme 9 Samples 10 Supported Platforms 27 29 30 30 30 30 30 31 31 33 33 33 34 34 39 35 36 37 38 About the Author a atay 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 He s a recognized speaker in international conferences including SpringOne Jazoon JAX W JAX JSFSummit JSFDays Con Fess and many local events such as JUGs Cagatay is als2. view gt 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 lt f view xmlns http wnw 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 gt lt pm page title Mobile gt lt pm view id viewA gt lt pm header title A gt lt pm content gt lt h form gt lt p commandButton value Go action bean method gt lt h form gt lt pm content gt lt pm view gt lt pm view id viewB gt lt pm header title B gt lt pm content gt B View lt pm content gt lt pm view gt lt pm page gt lt f view gt 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 lt p commandButton value Go action pm viewB gt 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 lt p commandButton value Go back to B action pm viewB reverse true gt lt h outputLink value viewB reverse true gt Go back to B lt h outputLink gt 4 2 External Navigations Naviga
3. 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 page Component Class org primefaces mobile component page Page Component Type org primefaces mobile Page Component Family org primefaces mobile component Renderer Type org primefaces mobile component PageRenderer Renderer Class org primefaces mobile component page PageRenderer Attributes rendered TRUE Boolean Boolean value to specify the rendering of the component when set to false component will not be rendered binding null Object An el expression that maps to a server side instance in a backing bean title o Title ofthe page of the page sigan pp a y Getting started with Page See section 3 Pages for more information on how page component is basically used Event Facets Page provides two facets name preinit and postinit that can be used to place content before jQuery mobile is initialized For example preinit event is used to load custom themes see section 8 2 for more information 26 6 9 Switch Switch is used to choose a binary selection Info Tag Component Class org primefaces mobile component uiswitch UISwitch Component Type org primefaces mobile UISwitch Component Family org primefaces mobile component Renderer Type org primefaces mobile component UISwitchRenderer Renderer Class org pri
4. gt lt h form id formB gt lt h outputText id display value bean text gt lt h form gt lt pm content gt lt pm view gt lt pm page gt 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 Yes No Info Tag buttonGroup Component Class org primefaces mobile component buttongroup ButtonGroup Component Type org primefaces mobile ButtonGroup Component Family org primefaces mobile component Renderer Type org primefaces mobile component ButtonGroupRenderer Renderer Class org primefaces mobile component buttongroup ButtonGroupRenderer Attributes rendered TRUE Boolean Boolean value to specify the rendering of the component when set to false component will not be rendered binding null Object An el expression that maps to a server side UIComponent instance in a backing bean orientation vertical String Type of the orientation can be vertical or horizontal style Inline style of the component styleClass Style class of the component 15 Getting started with ButtonGroup Buttons to be grouped are placed inside the button group Orientation Defa
5. 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 Expanded Toggle panel content Collapsed 33 7 10 p accordionPanel Title1 Content 1 Title 2 Title3 7 11 p selectBooleanCheckbox lagree 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 2 59 PM Header 35 8 2 Creating a Custom Theme jQuery Mobile provides a mobile themeroller tool to create custom themes easily 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 3 Use the pre init facet to place your theme Do not use h outputStylesheet as it can t load icons referenced from css 4 Enjoy 9 Sample
6. Component Class org primefaces mobile component view View Component Type org primefaces mobile View Component Family org primefaces mobile component Renderer Type org primefaces mobile component ViewRenderer Renderer Class org primefaces mobile component view ViewRenderer Attributes rendered TRUE Boolean Boolean value to specify the rendering of the component when set to false component will not be rendered binding null Object An el expression that maps to a server side re instance in a backing bean le o FALSE Title ofthe view of the view 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 7 2 h panelGrid PanelGrid component is used to do create a grid layout with a table less approach 7 3 h form In a mobile environment standard form component always sends javax faces RenderKitld PRIMEFACES MOBILE as a req
7. Renderer Class org primefaces mobile component navbar NavBarRenderer Attributes id mai String Unique identifier of the component identifier of the component rendered TRUE Boolean Boolean value to specify the rendering of the component when set to false component will not be rendered binding null Object An el expression that maps to a server side UlComponent instance in a backing bean Getting started with NavBar NavBar can be placed inside a header or directly inside a content 12 33 PM NavBar 24 lt pm view id navbar gt lt pm header title NavBar gt lt pm navBar gt lt p button value Home icon home href main reverse true styleClass ui btn active gt lt p button value Info icon info href main reverse true gt lt p button value Search icon Search href main reverse true gt lt pm navBar gt lt pm header gt lt pm content gt lt pm navBar gt lt p button value Home 1icon home href main reverse true styleClass ui btn active gt lt p button value Info icon info href main reverse true gt lt p button value Search icon search href main reverse true gt lt p button value Favs icon star href main reverse true gt lt p button value Setup icon gear href main reverse true gt lt pm navBar gt lt pm content gt lt pm view gt Adding ui btn active style class displays a button in a nav bar as active
8. bean Getting started with Field Field component wraps the label and the input Note that not all platforms due the screen size differences support field component Integrated Field Field alignment is a built in feature of PrimeFaces Mobile Renderkit same can be written as 18 6 4 Footer Footer is used as a bottom content container of a view Info Tag footer Component Class org primefaces mobile component footer Footer Component Type org primefaces mobile Footer Component Family org primefaces mobile component Renderer Type org primefaces mobile component FooterRenderer Renderer Class org primefaces mobile component footer FooterRenderer Attributes rendered TRUE Boolean Boolean value to specify the rendering of the component when set to false component will not be rendered binding null Object An el expression that maps to a server side 7 a instance in a backing bean xd FALSE Whether or not the Whether or not the position of footer is fixed of footer is fixed 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 19 6 5 Header Header is used as a top content container of a view Info Tag header Component Class org primefaces mobile component header Header Component Type org primefaces mobile Header Component Family org primefaces mobile component Renderer Type or
9. ean value null Object Value of the component than can be either an EL expression of a literal text converter null Converter An el expression or a literal text that defines a converter String for the component When it s an EL expression it s resolved to a converter instance In case it s a static text it must refer to a converter id immediate FALSE Boolean When set true process validations logic is executed at ae request values phase for this component FALSE Marks component as Marks component as required validator null Method A method binding expression that refers to a method Expr validationg the input valueChangeListener null Method A method binding expression that refers to a method for Expr handling a valuchangeevent requiredMessage Message to be displayed when required field validation eee Message to be Message to be displayed when conversion fails when conversion fails ities pa ame Yo styleClass Style class of the component disabled FALSE Disables the component when true Getting started with InputRange InputRange is an input component that requires a number value to bind 21 A 23 6 7 NavBar NavBar is a grouping component for a set of buttons in a bar Info Component Class org primefaces mobile component navbar NavBar Component Type org primefaces mobile NavBar Component Family org primefaces mobile component Renderer Type org primefaces mobile component NavBarRenderer
10. fine 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 Decide Yourself Write a viewhandler by overriding calculateRenderKitld 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 lt 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 gt lt pm page title Hello World gt lt pm view id main gt lt pm header title Header gt lt pm content gt Content lt pm content gt lt pm view gt lt pm page gt lt f vien gt Carrier gt 11 40 AM Header Content You can add more views by using a similar approach using pm view component Following is a multi view page lt f view xmlns http wnw 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 gt lt pm page title Hello World gt lt pm view id ma
11. g primefaces mobile component HeaderRenderer Renderer Class org primefaces mobile component header HeaderRenderer Attributes rendered TRUE Boolean Boolean value to specify the rendering of the component when set to false component will not be rendered binding null Object An el expression that maps to a server side Per instance in a backing bean le Title text ofthe header o text of the header FALSE Whether or not the position of footer is fixed Getting started with Footer As described in section 3 a header is defined within a view 20 Fixed Position When fixed position is enabled header scrolls along with the view 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 6 6 InputRange InputRange is a slider to provide number input Info Component Class org primefaces mobile component inputrange InputRange Component Type org primefaces mobile InputRange Component Family org primefaces mobile component Renderer Type org primefaces mobile component InputRangeRenderer Renderer Class org primefaces mobile component inputrange InputRangerRenderer Attributes rendered TRUE Boolean Boolean value to specify the rendering of the component when set to false component will not be rendered binding null Object An el expression that maps to a server side UIComponent instance in a backing b
12. in gt lt pm header title Header gt lt pm content gt Content lt pm content gt lt pm view gt lt pm view id second gt lt pm header title Second View Header gt lt pm content gt Second View Page lt pm content gt lt pm view gt lt pm view id third gt lt pm header title Third View Header gt lt pm content gt Third View Page lt pm content gt lt pm view gt lt pm page gt lt f view gt 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 b This type of navigation behaves like a GET navigation although there is no actual HTTP request GET Style lt f view xmlns http wnww w3 org 1999 xhtml xmlns f http java sun com jsf core xmlns p http primefaces orqg ui xmlns pm http primefaces org mobile contentType text html gt lt pm page title Mobile gt lt pm view id viewA gt lt pm header title A gt lt pm content gt lt h outputLink value viewB gt Go to B lt h outputLink gt lt pm content gt lt pm view gt lt pm view id viewB gt lt pm header title B gt lt pm content gt B View lt pm content gt lt pm view gt lt pm page gt lt f
13. mefaces mobile component uiswitch UISwitchRenderer Attributes id String Unique identifier of the component rendered TRUE Boolean Boolean value to specify the rendering of the component when set to false component will not be rendered binding null Object An el expression that maps to a server side UIComponent instance in a backing bean value null Object Value of the component than can be either an EL expression of a literal text converter null Converter An el expression or a literal text that defines a converter String for the component When it s an EL expression it s resolved to a converter instance In case it s a static text it must refer to a converter id immediate FALSE Boolean When set true process validations logic is executed at ae request values phase for this component FALSE Marks component as Marks component as required validator null Method A method binding expression that refers to a method Expr validationg the input valueChangeListener null Method A method binding expression that refers to a method for Expr handling a valuchangeevent requiredMessage Message to be displayed when required field validation ee Message to be Message to be displayed when conversion fails when conversion fails offLabel Text for false Getting started with Switch Switch is an input component that requires a boolean value to bind 6 10 View View represents a screen in a mobile page Info Tag view
14. o 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 Cagatay is currently working as a principal consultant for Prime Teknoloji the company he co founded in Turkey 1 Introduction 1 1 What is PrimeFaces Mobile PrimeFaces Mobile is a Ul kit to implement JSF pages that are optimized for mobile devices with a native look and feel e Mobile RenderKit for standard JSF and core PrimeFaces components e Mobile JSF components e Same backend model for desktop web and mobile web e Wide range of platform support e Ajax features to bring native application experience e 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 a atay ivici Architect and Lead Developer Levent G nay Core Developer QA amp Test e Yi it Dar n Core Developer QA amp Test e Mustafa Da g n Core Developer QA amp Test e Basri Kahveci QA amp Test Deniz Silah lar QA amp Test e Cenk ivici Mentor 2 Setup 2 1 Download PrimeFaces Mobile has a single jar called mobile version jar There are two ways to do
15. s PrimeFaces Mobile has various samples on PrimeFaces Showcase demonstrating different features Showcase Weather TwitFaces News Maps Contacts Translate Notes Chat a Men Contact To aes aton i asma 37 10 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 38 THE END 39
16. tion from a mobile application to an external resource is not different then doing it in a regular web page 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 lt pm page title Mobile gt lt pm view id main gt lt pm header title Ajax gt lt pm content gt lt h form gt lt p inputText value bean text gt lt p commandButton value Update update display gt lt h outputText id display value bean text gt lt h form gt lt pm content gt lt pm view gt lt pm page gt PrimeFaces Ajax extension features a special integration with jQuery Mobile s 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 Updating a component on another view is easy with proper referencing as well here is an example lt pm page title Mobile gt lt pm view id viewA gt lt pm header title A gt lt pm content gt lt h form gt lt p inputText value bean text gt lt p commandButton value Update update formB display gt lt h form gt lt pm content gt lt pm view gt lt pm view id viewB gt lt pm header title B gt lt pm content
17. uest 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 Home 7 5 p commandButton CommandButton display is optimized for a mobile platform and integrated with mobile navigation model Core ajax features are also available With Icon 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 Item 1 Item 2 Item 3 item 1 item 2 Item 3 Inset g El N Custom Content 10 Notes on Mobile DataList e 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 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 iOSS Previ Next Done LeeLee S000000000 GOOG E 7
18. ult orientation is vertical and other option is horizontal O Yes No 6 2 Content Content is used the place the contents of a mobile view Info Tag content Component Class org primefaces mobile component content Content Component Type org primefaces mobile Content Component Family org primefaces mobile component Renderer Type org primefaces mobile component ContentRenderer Renderer Class org primefaces mobile component content ContentRenderer Attributes rendered TRUE Boolean Boolean value to specify the rendering of the component when set to false component will not be rendered binding null Object An el expression that maps to a server side UIComponent instance in a backing bean 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 field Component Class org primefaces mobile component field Field Component Type org primefaces mobile Field Component Family org primefaces mobile component Renderer Type org primefaces mobile component FieldRenderer Renderer Class org primefaces mobile component field FieldRenderer Attributes rendered TRUE Boolean Boolean value to specify the rendering of the component when set to false component will not be rendered binding null Object An el expression that maps to a server side UIComponent instance in a backing
19. wnload 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 Download with Maven Group id of the dependency is org primefaces and artifact id is primefaces In addition to the configuration above you also need to add PrimeFaces maven repository to the repository list so that maven can download it 2 2 Dependencies PrimeFaces Mobile only requires a JAVA 5 runtime a JSF 2 0 implementation and PrimeFaces Core as mandatory dependencies Following is the compatibility matrix between core and mobile se 2 3 Configuration PrimeFaces Mobile does not require any mandatory configuration 2 4 Taglib PrimeFaces Mobile component library namespace should be added to your mobile pages 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 RenderKitld parameter This approach is for quick testing and not suggested as maintaining a request parameter is not easy Suggested Configure Application Wide De
Download Pdf Manuals
Related Search