prime faces users guide 3m4

USERS GUIDEAuthora!atay ivici

Covers 3.0.M4 Last Update: 14.11.11

PrimeFaces User!s Guide

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

a!atay ivici

2


About theAuthor! 1. Introduction ! What 1.1 2. Setup!isPrimeFaces?! 1.2 PrimeTeknoloji ! 2.1 Download! 2.2 Dependencies! 2.3 Conguration! 2.4 Hello World!

10 1111 11

1212 13 13 13

3. Component Suite! 3.1 AccordionPanel!3.2 AjaxBehavior! 3.3 AjaxStatus! 3.4 AutoComplete! 3.5 BreadCrumb! 3.6 Button! 3.7 Calendar! 3.8 Captcha! 3.9 Carousel! 3.10 CellEditor ! 3.11 Charts!3.11.1 PieChart! 3. 1.2 Line Chart! 1 3. 1.3 Bar Chart! 1 3.11.4 Donut Chart!3

1414 18 20 23 31 34 37 47 50 56 575 7 6 0 6 3 6 6


3. 1.5 Bubble Chart! 1 3. 1.6 Ohlc Chart! 1 3.11.7 MeterGaugeChart! 3.11.8 SkinningCharts! 3.11.9 AjaxBehaviorEvents ! 3.11.10 ChartingTips!

6 9 7 2 7 4 7 6 7 7 7 8

3.12 Collector ! 3.13 ColorPicker ! 3.14 Column! 3.15 Columns! 3.16 ColumnGroup! 3.17 CommandButton! 3.18 CommandLink! 3.19 ConrmDialog! 3.20 ContextMenu! 3.21 Dashboard! 3.22 DataExporter ! 3.23 DataGrid ! 3.24 DataList! 3.25 DataTable! 3.26 Dialog! 3.27 Drag&Drop!3.27.1 Draggable! 3.27.2 Droppable!

79 80 84 86 87 88 93 96 99 102 107 110 116 120 138 14314 3 14 7

3.28 Dock! 3.29 Editor !

152 1544


3.30 Effect ! 3.31 FeedReader! 3.32 Fieldset! 3.33 FileDownload! 3.34 FileUpload! 3.35 Focus! 3.36 Galleria! 3.37 GMap! 3.38 GMapInfoWindow ! 3.39 GraphicImage! 3.40 Growl! 3.41 HotKey! 3.42 IdleMonitor ! 3.43 ImageCompare! 3.44 ImageCropper! 3.45 ImageSwitch! 3.46 Inplace! 3.47 InputMask! 3.48 InputText! 3.49 InputTextarea! 3.50 Keyboard! 3.51 Layout! 3.52 LayoutUnit! 3.53 LightBox! 3.54 Log!5

158 161 162 166 168 174 176 179 190 191 196 199 202 204 206 210 213 217 221 224 228 233 237 239 243


3.55 Media! 3.56 Menu! 3.57 Menubar! 3.58 MenuButton! 3.59 MenuItem! 3.60 Message! 3.61 Messages! 3.62 NoticationBar ! 3.63 OrderList! 3.64 OutputPanel! 3.65 Panel! 3.66 Password! 3.67 PickList! 3.68 Poll! 3.69 Printer ! 3.70 ProgressBar! 3.71 Push! 3.72 Rating! 3.73 RemoteCommand! 3.74 Resizable! 3.75 Ring! 3.76 Row! 3.77 RowEditor ! 3.78 RowExpansion! 3.79 RowToggler!6

245 247 253 256 258 261 263 265 267 271 273 276 281 287 290 291 294 295 298 300 304 307 308 309 310


3.80 Schedule! 3.81 ScrollPanel ! 3.82 SelectBooleanCheckbox! 3.83 SelectManyCheckbox! 3.84 SelectOneListbox! 3.85 SelectOneMenu! 3.86 SelectOneRadio! 3.87 SelectManyMenu! 3.88 Separator! 3.89 Sheet! 3.90 Slider ! 3.91 Spacer! 3.92 Spinner! 3.93 Submenu! 3.94 Stack! 3.95 SubTable! 3.96 SummaryRow! 3.97 Tab! 3.98 TabView! 3.99 TagCloud! 3.100 Terminal! 3.101 ThemeSwitcher! 3.102 Timeline! 3.103 Toolbar! 3.104 ToolbarGroup!7

311 319 321 323 325 327 331 333 335 337 340 345 346 351 352 354 355 356 357 361 363 365 367 370 372


3.105 Tooltip! 3.106 Tree! 3.107 TreeNode! 3.108 TreeTable! 3.109 Watermark ! 3.110 Wizard!

373 376 384 385 388 390

4. PartialRenderingandProcessing!4.1 PartialRendering !4.1.1 Infrastructure! 4.1.2 Using IDs! 4.1.3 NotifyingUsers! 4.1.4 Bits&Pieces !

39639639 6 39 6 39 9 39 9

4.2 PartialProcessing !4.2.2 Keywords! 4.2.3 Using Ids!

40040 0 40 1 40 1

4.2.1 PartialValidation!

5. PrimeFacesMobile! 6. PrimeFacesPush!6.1 Setup! 6.2 PushAPI! 6.3 PushComponent! 6.4 Samples!6.4.1 Counter! 6.4.2 Chat!

402 403403 404 404 40440 4 40 5

7. Javascript API!8

407


7.1 PrimeFacesNamespace! 7.2 AjaxAPI!

407 408

8. Themes!8.1 Applying a Theme! 8.2 CreatingaNewTheme! 8.3 How Themes Work! 8.4 Theming Tips!

410411 412 413 414

9. Utilities!9.1 RequestContext! 9.2 ELFunctions!

415415 418

10. Portlets!10.1 Dependencies! 10.2 Conguration!

420420 421

11. IntegrationwithJavaEE ! 12. IDE Support!12.1 NetBeans! 12.2 Eclipse!

424 425425 426

13. Project Resources! 14. FAQ!

427 428

9

About theAuthora!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. Hes a recognized speaker in international conferences including SpringOne, Jazoon, JAX, W-JAX, JSFSummit, JSFDays, Con-Fess and many local events such as JUGs. a!atay 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. a!atay is currently working as a principal consultant for Prime Teknoloji, the company he cofounded in Turkey.


1. Introduction1.1 What isPrimeFaces?PrimeFaces is an open source JSF component suite with various extensions. Rich set of components (HtmlEditor, Dialog, AutoComplete, Charts and many more). Built-in Ajax based on standard JSF 2.0 Ajax APIs. Lightweight, one jar, zero-configuration and no required dependencies. Ajax Push support via websockets. Mobile UI kit to create mobile web applications for handheld devices. Skinning Framework with 30 built-in themes and support for visual theme designer tool. Extensive documentation. Large, vibrant and active user community. Developed with "passion" from application developers to application developers.

1.2 PrimeTeknolojiPrimeFaces is maintained by Prime Teknoloji, a Turkish software development company specialized inAgile and Java EE consulting. PrimeFaces Team members are full time engineers at PrimeTeknoloji. a!atay ivici - Architect and Lead Developer Levent Gnay - Core Developer / QA&Test Yi!it Darn - Core Developer / QA&Test Mustafa Da"gn - Core Developer / QA&Test Basri Kahveci - QA&Test Deniz Silahlar - QA&Test Cenk ivici - Mentor

11


2. Setup2.1 DownloadPrimeFaces has a single jar called primefaces-{version}.jar.There are two ways to download this jar,youcaneitherdownloadfromPrimeFaceshomepageorifyouareamavenuseryoucandefine it as a dependency. DownloadManually Three different artifacts are available for each PrimeFaces version, binary, sources and bundle. Bundle contains binary, sources and javadocs.http://www.primefaces.org/downloads.html

DownloadwithMaven Group id of the dependency isorg.primefaces and artifact id isprimefaces. org.primefaces primefaces 3.0.M4

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

12


2.2 DependenciesPrimeFaces only requires a JAVA 5+ runtime and a JSF 2.0 implementation as mandatory dependencies. Therere some optional libraries for certain features.Dependency JSF runtime itext apache poi rome commons-fileupload commons-io Version * 2.0+ 2.1.7 3.7 1.0 1.2.1 1.4 Type Required Optional Optional Optional Optional Optional Description Apache MyFaces or Oracle Mojarra DataExporter (PDF). DataExporter (Excel). FeedReader. FileUpload FileUpload

* Listed versions are tested and known to be working with PrimeFaces, other versions of these dependencies may also work but not tested.

2.3 Configuratio n 2.4 Hello World

PrimeFaces does not require any mandatory configuration.

Once you have added the downloaded jar to your classpath, you need to add the PrimeFaces namespace to your page to begin using the components. Here is a simple page;

When you run this page, you should see a rich text editor.

13


3. Component Suite3.1 AccordionPanelAccordionPanel is a container component that displays content in stacked format.

InfoTag Component Class ComponentType Component Family Renderer Type Renderer Class accordionPanel org.primefaces.component.accordionpanel.Accordionpanel org.primefaces.component.AccordionPanel org.primefaces.component org.primefaces.component.AccordionPanelRenderer org.primefaces.component.accordionpanel.AccordionPanelRenderer

AttributesName 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. An EL expression that maps to a server side UIComponent instance in a backing bean.14


Name activeIndex style styleClass onTabChange onTabShow dynamic cache value var multiple widgetVar

Default 0 null null null null FALS E TRUE null null FALS E null

Type String String String String String Boolean Boolean java.util.List String Boolean String

Description Index of the active tab or a comma separated string of indexes when multiple mode is on. Inline style of the container element. Style class of the container element. Client side callback to invoke when an inactive tab is clicked. Client side callback to invoke when a tab gets activated. Defines the toggle mode. Defines if activating a dynamic tab should load the contents from server again. List to iterate to display dynamic number of tabs. Name of iterator to use in a dynamic number of tabs. Controls multiple selection. Name of the client side widget.

GettingStartedwithAccordionPanel Accordion panel consists of one or more tabs and each tab can group any content. ...More content for first tab //any number of tabs

DynamicContent Loading AccordionPanel supports lazy loading of tab content, when dynamic option is set true, only active tab contents will be rendered to the client side and clicking an inactive tab header will do an ajax request to load the tab contents. This feature is useful to reduce bandwidth and speed up page loading time. By default activating a previouslyloadeddynamictabdoesnotinitiatearequesttoloadthecontentsagainastabiscached. To control this behavior usecache option.15

PrimeFaces User!s Guide //..tabs

Client SideCallbacks onTabChange is called before a tab is shown and onTabShow is called after. Both receive container element of the tab to show as the parameter. //..tabs function handleChange(panel) { //panel: new tab content container }

AjaxBehaviorEvents tabChangeis the one and only ajax behavior event of accordion panel that is executed when a tab is toggled.

public void onChange(TabChangeEvent event) { //Tab activeTab = event.getTab(); //... }

Your listener(if defined) will be invoked with an org.primefaces.event.TabChangeEvent instance that contains a reference to the new active tab and the accordion panel itself. DynamicNumberof Tabs When the tabs to display are not static, use the built-in iteration feature similar to ui:repeat. .. .More content

16


Disabled Tabs A tab can be disabled by setting disabled attribute to true. ...More content for first tab //any number of tabs

MultipleSelection By default, only one tab at a time can be active, enablemultiple mode to activate multiple tabs. //tabs

Client SideAPI Widget:PrimeFaces.widget.AccordionPanelMethod select(index) unselect(index) Params index: Index of tab to display index: Index of tab to hide Return Type void void Description Activates tab with given index. Deactivates tab with given index.

Skinning AccordionPanel resides in a main container element which style and styleClass options apply. Following is the list of structural style classes;Class .ui-accordion .ui-accordion-header .ui-accordion-content Main container element Tab header Tab content Applies

As skinning style classes are global, see the main Skinning section for more information.17


3.2 AjaxBehaviorAjaxBehavior is an extension to standard f:ajax. InfoTag Behavior Id Behavior Class ajax org.primefaces.component.AjaxBehavior org.primefaces.component.behavior.ajax.AjaxBehavior

AttributesName listener immediate Default null FALS E FALS E null null null null null null TRUE FALS E null Type MethodExpr boolean Description Method to process in partial request. Boolean value that determines the phaseId, when true actions are processed at apply_request_values, when false at invoke_application phase. When set to true, ajax requests are not queued. Component(s) to process in partial request. Component(s) to update with ajax. Callback to execute before ajax request is begins. Callback to execute when ajax request is completed. Callback to execute when ajax request succeeds. Callback to execute when ajax request fails. Global ajax requests are listened by ajaxStatus component, setting global to false will not trigger ajaxStatus. Disables ajax behavior. Client side event to trigger ajax request.

async process update onstart oncomplete onsuccess onerror global disabled event

Boolean String String String String String String Boolean Boolean String

GettingStartedwithAjaxBehavior AjaxBehavior is attached to the component to ajaxify.

18


In the example above, each time the input changes, an ajax request is sent to the server. When the response is received output text with id "out" is updated with value of the input. Listener In case you need to execute a method on a backing bean, define a listener;

public class CounterBean { private int count; public int getCount() { return } public void setCount(int count) { this.count = } public void increment() { } count++; }

count;

count;

Events Default client side events are defined by components that support client behaviors, for input componentsitisonchangeandforcommandcomponentsitisonclick.Inordertooverridethedom event to trigger the ajax request use event option. In following example, ajax request is triggered when key is up on input field.

PartialProcessing Partial processing is used with process option which defaults to @this, meaning the ajaxified component. See section 5 for detailed information on partial processing.

19


3.3 AjaxStatusAjaxStatus is a global notifier for ajax requests made by PrimeFaces components.

InfoTag Component Class ComponentType Component Family Renderer Type Renderer Class ajaxStatus org.primefaces.component.ajaxstatus.AjaxStatus org.primefaces.component.AjaxStatus org.primefaces.component org.primefaces.component.AjaxStatusRenderer org.primefaces.component.ajaxstatus.AjaxStatusRenderer

AttributesName id rendered binding onstart oncomplete onprestart onsuccess onerror style styleClass widgetVar Default null TRUE null null null null null null null null null String Boolean Object String String String String String String String String Type Description Unique identifier of the component. Boolean value to specify the rendering of the component. An el expression that maps to a server side UIComponent instance in a backing bean Client side callback to execute after ajax requests start. Client side callback to execute after ajax requests complete. Client side callback to execute before ajax requests start. Client side callback to execute after ajax requests completed succesfully. Client side callback to execute when an ajax request fails. Inline style of the component. Style class of the component. Name of the client side widget.

20


GettingStartedwithAjaxStatus AjaxStatus uses facets to represent the request status. Most common used facets arestart and complete. Start facet will be visible once ajax request begins and stay visible until its completed. Once the ajax response is received start facet becomes hidden and complete facet shows up.

Events Here is the full list of available event names; default: Initially visible when page is loaded. prestart: Before ajax request is sent. start:After ajax request begins. success:When ajax response is received without error. error:When ajax response is received with error. complete:When everything finishes.

21


CustomEvents Facets are the declarative way to use, if youd like to implement advanced cases with scripting you can take advantage of on* callbacks which are the event handler counterparts of the facets.

A comman usage of programmatic approach is to implement a custom status dialog; Please Wait

Client SideAPI Widget:PrimeFaces.widget.AjaxStatusMethod bindFacet(eventName, facetId) Params eventName: Name of status event, facetId: Element id of facet container eventName: Name of status event, fn: function to bind Return Type void Description Binds a facet to an event

bindCallback(eventName, fn)

void

Binds a function to an event

Skinning AjaxStatus is equipped with style and styleClass. Styling directly applies to a container element which contains the facets.

Tips Avoid updating ajaxStatus itself to prevent duplicate facet/callback bindings. Provide a fixed width/height to the ajaxStatus to prevent page layout from changing. Components like commandButton has an attribute (global) to control triggering of AjaxStatus. There is an ajax loading gif bundled with PrimeFaces which you can use;

22


3.4 AutoComplet e

AutoComplete provides live suggestions while an input is being typed.

InfoTag Component Class ComponentType Component Family Renderer Type Renderer Class autoComplete org.primefaces.component.autocomplete.AutoComplete org.primefaces.component.AutoComplete org.primefaces.component org.primefaces.component.AutoCompleteRenderer org.primefaces.component.autocomplete.AutoCompleteRenderer

AttributesName 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. 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.23


Name immediate

Default FALS E FALS E null null null null null null null null null null unlimited 1 300 FALS E null null TRUE null null 400 FALS E null

Type Boolean

Description When set true, process validations logic is executed at apply request values phase for this component. Marks component as required. A method expression that refers to a method validationg the input. A method 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. Message to be displayed when validation fails. Name of the client side widget. Method providing suggestions. Name of the iterator used in pojo based suggestion. Label of the item. Value of the item. Maximum number of results to be displayed. Number of characters to be typed before starting to query. Delay to wait in milliseconds before sending each query to the server. When enabled, autoComplete only accepts input from the selection list. Client side callback to execute before ajax request to load suggestions begins. Client side callback to execute after ajax request to load suggestions completes. Defines whether to trigger ajaxStatus or not. Defines the height of the items viewport. Effect to use when showing/hiding suggestions. Duration of effect in milliseconds. Enables dropdown mode when set true. Inline style of the items container element.

required validator valueChangeListener requiredMessage converterMessage validatorMessage widgetVar completeMethod var itemLabel itemValue maxResults minQueryLength queryDelay forceSelection onstart oncomplete global scrollHeight effect effectDuration dropdown panelStyle

Boolean MethodExpr MethodExpr String String String String MethodExpr String String String Integer Integer Integer Boolean String String Boolean Integer String Integer Boolean String

24


Name panelStyleClass accesskey alt autocomplete dir disabled label lang maxlength onblur onchange

Default null null null null null FALS E null null null null null

Type String String String String String Boolean String String Integer String String

Description Style class of the items container element. Access key that when pressed transfers focus to the input element. Alternate textual description of the input field. Controls browser autocomplete behavior. Direction indication for text that does not inherit directionality. Valid values are LTR and RTL. Disables input field A localized user presentable name. Code describing the language used in the generated markup for this component. Maximum number of characters that may be entered in this field. Client side callback to execute when input element loses focus. Client side callback to execute when input element loses focus and its value has been modified since gaining focus. Client side callback to execute when input element is clicked. Client side callback to execute when input element is double clicked. Client side callback to execute when input element receives focus. Client side callback to execute when a key is pressed down over input element. Client side callback to execute when a key is pressed and released over input element. Client side callback to execute when a key is released over input element. Client side callback to execute when a pointer button is pressed down over input element Client side callback to execute when a pointer button is moved within input element. Client side callback to execute when a pointer button is moved away from input element. Client side callback to execute when a pointer button is moved onto input element.25

onclick ondblclick onfocus onkeydown onkeypress onkeyup onmousedown onmousemove onmouseout onmouseover

null null null null null null null null null null

String String String String String String String String String String


Name onmouseup onselect readonly size style styleClass tabindex title

Default null null FALS E null null null null null

Type String String Boolean Integer String String Integer String

Description Client side callback to execute when a pointer button is released over input element. Client side callback to execute when text within input element is selected by user. Flag indicating that this component will prevent changes by the user. Number of characters used to determine the width of the input element. Inline style of the input element. Style class of the input element. Position of the input element in the tabbing order. Advisory tooltip informaton.

GettingStartedwithAutoComplete Suggestions are loaded by calling a server side completeMethod that takes a single string parameter which is the text entered. Since autoComplete is an input component, it requires a value as usual.

public class Bean { private String text; public List complete(String query) { List results = new ArrayList(); for (int i = 0; i < 10; i++) results.add(query + i); return } results; //getter setter }

PojoSupport Most of the time, instead of simple strings you would need work with your domain objects, autoComplete supports this common use case with the use of a converter and data iterator.26


Following example loads a list of players, itemLabel is the label displayed as a suggestion and itemValueisthesubmittedvalue.Notethatwhenworkingwithpojos,youneedtoplug-inyourown converter.

public class PlayerBean { private Player selectedPlayer; public Player getSelectedPlayer() { return selectedPlayer; } public void setSelectedPlayer(Player selectedPlayer) { this.selectedPlayer = selectedPlayer; } public List complete(String query) { List players = readPlayersFromDatasource(query); return } players; }

public class Player { private String name; //getter setter }

LimitingtheResults Number of results shown can be limited, by default there is no limit. completeMethod=#{bean.complete}

27


MinimumQueryLength By default queries are sent to the server and completeMethod is called as soon as users starts typing at the input text. This behavior is tuned using theminQueryLength attribute.

With this setting, suggestions will start when user types the 3rd character at the input field. Query Delay AutoComplete is optimized using queryDelay option, by default autoComplete waits for 300 milliseconds to query a suggestion request, if youd like to tune the load balance, give a longer value. Following autoComplete waits for 1 second after user types an input.

CustomContent AutoComplete can display custom content by nesting columns. #{p.name} #{p.number}

DropdownMode When dropdown mode is enabled, a dropdown button is displayed next to the input field, clicking thisbuttonwilldoasearchwithanemptyquery,aregularcompleteMethodimplementationshould load all available items as a response.

28


AjaxBehaviorEvents Insteadofwaitingforusertosubmittheformmanuallytoprocesstheselecteditem,youcanenable instant ajax selection by using the itemSelect ajax behavior. Example below demonstrates how to display a message about the selected item instantly.

public class Bean { public void handleSelect(SelectEvent event) { Object item = event.getObject(); FacesMessage msg = new FacesMessage(Selected, Item: + item); } ... }

Your listener(if defined) will be invoked with an org.primefaces.event.Select instance that contains a reference to the selected item. Note that autoComplete also supports events inherited from regular input text such as blur, focus, mouseover in addition to itemSelect. Client SideCallbacks onstart and oncomplete are used to execute custom javascript before and after an ajax request to load suggestions.

onstart callback gets arequest parameter and oncomplete gets aresponse parameter, these parameters contain useful information. For examplerequestis the query string and responseis the xhr request sent under the hood. Client SideAPI Widget:PrimeFaces.widget.AutoCompleteMethod search(value) close() Params value: keyword for search 29

Return Type void void

Description Initiates a search with given value Hides suggested items menu


Method disable() enable() deactivate() activate()

Params -

Return Type void void void void

Description Disables the input field Enables the input field Deactivates search behavior Activates search behavior

Skinning Following is the list of structural style classes;Class .ui-autocomplete .ui-autocomplete-input .ui-autocomplete-panel .ui-autocomplete-items .ui-autocomplete-item Container element. Input field. Container of suggestions list. List of items Each item in the list. Applies

As skinning style classes are global, see the main Skinning section for more information. Tips Do not forget to use a converter when working with pojos. Enable forceSelection if youd like to accept values only from suggested list. Increase query delay to avoid unnecessary load to server as a result of user typing fast.

30


3.5 BreadCrumbBreadcrumb is a navigation component that provides contextual information about page hierarchy in the workflow.

InfoTag Component Class ComponentType Component Family Renderer Type Renderer Class breadCrumb org.primefaces.component.breadcrumb.BreadCrumb org.primefaces.component.BreadCrumb org.primefaces.component org.primefaces.component.BreadCrumbRenderer org.primefaces.component.breadcrumb.BreadCrumbRenderer

AttributesName 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. An el expression that maps to a server side UIComponent instance in a backing bean Name of the client side widget. MenuModel instance to create menus programmatically Number of expanded menutitems at the end. Number of expanded menuitems at begining. Expanded effect duration in milliseconds. Collapse effect duration in milliseconds. Initial collapse effect duration in milliseconds. Preview width of a collapsed menuitem.

widgetVar model expandedEndItems expandedBeginningItems expandEffectDuration collapseEffectDuration initialCollapseEffectDuration previewWidth

null null 1 1 800 500 600 5

String MenuModel Integer Integer Integer Integer Integer Integer31


Name preview style styleClass

Default FALS E null null

Type Boolean String String

Description Specifies preview mode, when set to false menuitems will not collapse. Style of main container element. Style class of main container

GettingStartedwithBreadCrumb Steps are defined as child menuitem components in breadcrumb.

Preview By default all menuitems are expanded, if you have limited space and many menuitems, breadcrumb can collapse/expand menuitems on mouseover. previewWidth attribute defines the reveal amount in pixels.

DynamicMenus Menus can be created programmatically as well, see the dynamic menus part in menu component section for more information and an example.32


AnimationConfiguration Duration of effects can be customized using several attributes. Heres an example;

Durations are defined in milliseconds. Skinning Breadcrumb resides in a container element thatstyle and styleClass options apply. Following is the list of structural style classes;Style Class .ui-breadcrumb .ui-breadcrumb .ui-menu-item-link .ui-breadcrumb .ui-menu-item-text .ui-breadcrumb-chevron Applies Main breadcrumb container element. Each menuitem. Each menuitem label. Seperator of menuitems.

As skinning style classes are global, see the main Skinning section for more information. Tips If there is a dynamic flow, use model option instead of creating declarative p:menuitem components and bind your MenuModel representing the state of the flow. Breadcrumb can do ajax/non-ajax action requests as well since p:menuitem has this option. In this case, breadcrumb must be nested in a form. url option is the key for a menuitem, if it is defined, it will work as a simple link. If youd like to use menuitem to execute command with or without ajax, do not define the url option.

33


3.6 Butto n

Button is an extension to the standard h:button component with skinning capabilities.

InfoTag Component Class ComponentType Component Family Renderer Type Renderer Class button org.primefaces.component.button.Button org.primefaces.component.Button org.primefaces.component org.primefaces.component.ButtonRenderer org.primefaces.component.button.ButtonRenderer

AttributesName id rendered binding widgetVar value outcome includeViewParams fragment disabled accesskey alt dir Default null TRUE null null null null FALS E null FALS E null null null Type String Boolean Object String Object String Boolean String Boolean String String String34

Description Unique identifier of the component. Boolean value to specify the rendering of the component. An el expression that maps to a server side UIComponent instance in a backing bean. Name of the client side widget. Value of the component than can be either an EL expression of a literal text. Used to resolve a navigation case. Whether to include page parameters in target URI Identifier of the target page which should be scrolled to. Disables button. Access key that when pressed transfers focus to button. Alternate textual description. Direction indication for text that does not inherit directionality. Valid values are LTR and RTL.


Name image lang onblur onchange

Default null null null null

Type String String String String

Description Style class for the button icon. Code describing the language used in the generated markup for this component. Client side callback to execute when button loses focus. Client side callback to execute when button loses focus and its value has been modified since gaining focus. Client side callback to execute when button is clicked. Client side callback to execute when button is double clicked. Client side callback to execute when button receives focus. Client side callback to execute when a key is pressed down over button. Client side callback to execute when a key is pressed and released over button. Client side callback to execute when a key is released over button. Client side callback to execute when a pointer button is pressed down over button. Client side callback to execute when a pointer button is moved within button Client side callback to execute when a pointer button is moved away from button. Client side callback to execute when a pointer button is moved onto button. Client side callback to execute when a pointer button is released over button. Inline style of the button. Style class of the button. Makes button read only. Position in the tabbing order. Advisory tooltip informaton.

onclick ondblclick onfocus onkeydown onkeypress onkeyup onmousedown onmousemove onmouseout onmouseover onmouseup style styleClass readOnly tabindex title

null null null null null null null null null null null null null FALS E null null

String String String String String String String String String String String String String Boolean Integer String

35


GettingStartedwithButton p:button usage is same as standard h:button, an outcome is necessary to navigate using GET requests. Assume you are at source.xhtml and need to navigate target.xhtml.

Parameters Parameters in URI are defined with nested tags.

Icons Icons for button are defined via css and image attribute, if you use title instead of value, only icon will be displayed and title text will be displayed as tooltip on mouseover. You can also use icons from PrimeFaces themes with image attribute.

.star { background-image: url("images/star.png"); }

Skinning Button renders abutton tag which style and styleClass applies. Following is the list of structural style classes;Style Class .ui-button .ui-button-text-only .ui-button-text Button element Button element when icon is not used Label of button Applies

As skinning style classes are global, see the main Skinning section for more information.

36


3.7 CalendarCalendar is an input component used to select a date featuring display modes, paging, localization, ajax selection and more.

InfoTag Component Class ComponentType Component Family Renderer Type Renderer Class calendar org.primefaces.component.calendar.Calendar org.primefaces.component.Calendar org.primefaces.component org.primefaces.component.CalendarRenderer org.primefaces.component.calendar.CalendarRenderer

AttributesName id rendered binding Default null TRUE null String Boolean Object Type Description Unique identifier of the component Boolean value to specify the rendering of the component. An el expression that maps to a server side UIComponent instance in a backing bean Value of the component 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

value converter

null null

java.util.Date Converter/String

37


Name immediate

Default FALS E FALS E null null null null null null null null int FALS E popup MM/dd/ yyyy null null FALS E FALS E null

Type Boolean

Description When set true, process validations logic is executed at apply request values phase for this component. Marks component as required A method expression that refers to a method validationg the input A method 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. Message to be displayed when validation fails. Name of the client side widget. Sets calendar's minimum visible date Sets calendar's maximum visible date Enables multiple page rendering. Disables the calendar when set to true. Defines how the calendar will be displayed. DateFormat pattern for localization Locale to be used for labels and conversion. Icon of the popup button When enabled, popup icon is rendered without the button. Enables month/year navigator String or a java.util.TimeZone instance to specify the timezone used for date conversion, defaults to TimeZone.getDefault() Makes input text of a popup calendar readonly. Visibility of button panel containing today and done buttons.

required validator valueChangeListener requiredMessage converterMessage validatorMessage widgetVar mindate maxdate pages disabled mode pattern locale popupIcon popupIconOnly navigator timeZone

Boolean MethodExpr MethodExpr String String String String Date or String Date or String 1 Boolean String String java.util.Locale or String String Boolean Boolean java.util.TimeZone

readOnlyInputText showButtonPanel

FALS E FALS E

Boolean Boolean

38


Name effect effectDuration showOn showWeek disabledWeekends showOtherMonths selectOtherMonths yearRange timeOnly stepHour stepMinute stepSecond minHour maxHour minMinute maxMinute minSecond maxSecond accesskey alt autocomplete dir

Default null normal both FALS E FALS E FALS E FALS E null FALS E 1 1 1 0 23 0 59 0 59 null null null null String String String

Type

Description Effect to use when displaying and showing the popup calendar. Duration of the effect. Client side event that displays the popup calendar. Displays the week number next to each week. Disables weekend columns. Displays days belonging to other months. Enables selection of days belonging to other months. Year range for the navigator, default "c-10:c+10" Shows only timepicker without date. Hour steps. Minute steps. Second steps. Minimum boundary for hour selection. Maximum boundary for hour selection. Minimum boundary for minute selection. Maximum boundary for hour selection. Minimum boundary for second selection. Maximum boundary for second selection. Access key that when pressed transfers focus to the input element. Alternate textual description of the input field. Controls browser autocomplete behavior. Direction indication for text that does not inherit directionality. Valid values are LTR and RTL. A localized user presentable name. Code describing the language used in the generated markup for this component.

Boolean Boolean Boolean Boolean String Boolean Integer Integer Integer Integer Integer Integer Integer Integer Integer String String String String

label lang

null null

String String

39


Name maxlength onblur onchange

Default null null null Integer String String

Type

Description Maximum number of characters that may be entered in this field. Client side callback to execute when input element loses focus. Client side callback to execute when input element loses focus and its value has been modified since gaining focus. Client side callback to execute when input element is clicked. Client side callback to execute when input element is double clicked. Client side callback to execute when input element receives focus. Client side callback to execute when a key is pressed down over input element. Client side callback to execute when a key is pressed and released over input element. Client side callback to execute when a key is released over input element. Client side callback to execute when a pointer button is pressed down over input element Client side callback to execute when a pointer button is moved within input element. Client side callback to execute when a pointer button is moved away from input element. Client side callback to execute when a pointer button is moved onto input element. Client side callback to execute when a pointer button is released over input element. Client side callback to execute when text within input element is selected by user. Flag indicating that this component will prevent changes by the user. Number of characters used to determine the width of the input element.

onclick ondblclick onfocus onkeydown onkeypress

null null null null null

String String String String String

onkeyup onmousedown

null null

String String

onmousemove

null

String

onmouseout

null

String

onmouseover

null

String

onmouseup

null

String

onselect readonly size

null FALS E null

String Boolean Integer

40


Name tabindex title

Default null null Integer String

Type

Description Position of the input element in the tabbing order. Advisory tooltip informaton.

GettingStartedwithCalendar Value of the calendar should be a java.util.Date.

public class DateBean { private Date date; //Getter and Setter }

DisplayModes Calendar has two main display modes, popup (default) and inline. Inline

Popup

41


showOn option defines the client side event to display the calendar. Valid values are; focus:When input field receives focus button:When popup button is clicked both: Both focus and button cases Popup Button

Popup Icon Only

Paging Calendar can also be rendered in multiple pages where each page corresponds to one month. This feature is tuned with thepages attribute.42


I18N By default locale information is retrieved from the views locale and can be overridden by the locale attribute. Locale attribute can take a locale key as a String or a java.util.Locale instance. Default language of labels are English and you need to add the necessary translations to your page manually as PrimeFaces does not include language translations. PrimeFaces Wiki Page for PrimeFacesLocales is a community driven page where you may find the translations you need. Please contribute to this wiki with your own translations.http://wiki.primefaces.org/display/Components/PrimeFaces+Locales

Translation is a simple javascript object, we suggest adding the code to a javascript file and include in your application. Following is aTurkish calendar.

L11N Locale option is used for localizing the labels, not for localizing the date pattern. Default pattern is "MM/dd/yyyy" and pattern attribute is used to provide a custom date pattern.

43


Effects Various effects can be used when showing and hiding the popup calendar, options are; show slideDown fadeIn blind bounce clip drop fold slide

AjaxBehaviorEvents Calendar provides a dateSelect ajax behavior event to execute an instant ajax selection whenever a date is selected. If you define a method as a listener, it will be invoked by passing an org.primefaces.event.DateSelectEvent instance.

public void handleDateSelect(DateSelectEvent event) { Date date = event.getDate(); //Add facesmessage }

In popup mode, calendar also supports regular ajax behavior events like blur, keyup and more.

44


DateRanges Using mindate and maxdate options, selectable dates can be restricted. Values for these attributes can either be a string or a java.util.Date.

Navigator Navigator is an easy way to jump between months/years quickly.

TimePicker TimePicker functionality is enabled by adding time format to your pattern.

45


Client SideAPI Widget:PrimeFaces.widget.CalendarMethod getDate() setDate(date) disable() enable() Params date: Date to display Return Type Date void void void Description Return selected date Sets display date Disables calendar Enables calendar

Skinning Calendar resides in a container element which style and styleClass options apply. Following is the list of structural style classes;Style Class .ui-datepicker .ui-datepicker-header .ui-datepicker-prev .ui-datepicker-next .ui-datepicker-title .ui-datepicker-month .ui-datepicker-table .ui-datepicker-week-end .ui-datepicker-other-month .ui-datepicker td .ui-datepicker-buttonpane .ui-datepicker-current .ui-datepicker-close Main container Header container Previous month navigator Next month navigator Title Month display Date table Label of weekends Dates belonging to other months Each cell date Button panel Today button Close button Applies

As skinning style classes are global, see the main Skinning section for more information

46


3.8 CaptchaCaptcha is a form validation component based on RecaptchaAPI.

InfoTag Component Class ComponentType Component Family Renderer Type Renderer Class captcha org.primefaces.component.captcha.Captcha org.primefaces.component.Captcha org.primefaces.component org.primefaces.component.CaptchaRenderer org.primefaces.component.captcha.CaptchaRenderer

AttributesName 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. 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.47

binding value converter

null null null

Object Object Converter/ String

immediate

FALS E FALS E

Boolean

required

Boolean


Name validator valueChangeListener requiredMessage converterMessage validatorMessage publicKey theme language tabindex label secure

Default null null null null null null red en null null FALS E

Type MethodExpr ValueChange Listener String String String String String String Integer String Boolean

Description 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. Message to be displayed when validation fields. Public recaptcha key for a specific domain (deprecated) Theme of the captcha. Key of the supported languages. Position of the input element in the tabbing order. User presentable field name. Enables https support

GettingStartedwithCaptcha Catpcha is implemented as an input component with a built-in validator that is integrated with reCaptcha. First thing to do is to sign up to reCaptcha to get public&private keys. Once you have the keys for your domain, add them to web.xml as follows; primefaces.PRIVATE_CAPTCHA_KEY YOUR_PRIVATE_KEY primefaces.PUBLIC_CAPTCHA_KEY YOUR_PUBLIC_KEY

That is it, now you can use captcha as follows;

48


Themes Captcha features following built-in themes for look and feel customization. red (default) white blackglass clean

Themes are applied via the theme attribute.

Language s Text instructions displayed on captcha is customized with thelanguage attribute. Below is a captcha with Turkish text.

OverridingValidationMessages By default captcha displays its own validation messages, this can be easily overridden by the JSF message bundle mechanism. Corresponding keys are;Summary Detail primefaces.captcha.INVALID primefaces.captcha.INVALID_detail

Tips Use label option to provide readable error messages in case validation fails. Enablesecure option to support https otherwise browsers will give warnings. See http://www.google.com/recaptcha/learnmore to learn more about how reCaptcha works.

49


3.9 CarouselCarousel is a multi purpose component to display a set of data or general content with slide effects.

InfoTag Component Class ComponentType Component Family Renderer Type Renderer Class carousel org.primefaces.component.carousel.Carousel org.primefaces.component.Carousel org.primefaces.component org.primefaces.component.CarouselRenderer org.primefaces.component.carousel.CarouselRenderer

AttributesName 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 A value expression that refers to a collection Name of the request scoped iterator Number of visible items per page Index of the first element to be displayed Name of the client side widget. Sets continuous scrolling Sets vertical scrolling

binding value var rows first widgetVar circular vertical

null null null 3 0 null FALS E FALS E

Object Object String Integer Integer String Boolean Boolean

50


Name autoPlayInterval pageLinks effect easing effectDuration dropdownTemplate. style styleClass itemStyle itemStyleClass headerText footerText

Default 0 3 slide easeInO utCirc 500 {page} null null null null null null

Type Integer Integer String String Integer String String String String String String String

Description Sets the time in milliseconds to have Carousel start scrolling automatically after being initialized Defines the number of page links of paginator. Name of the animation, could be fade or slide. Name of the easing animation. Duration of the animation in milliseconds. Template string for dropdown of paginator. Inline style of the component.. Style class of the component.. Inline style of each item. Style class of each item. Label for header. Label for footer.

GettingStartedwithCarousel Calendar has two main use-cases; data and general content display. To begin with data iteration lets use a list of cars to display with carousel.public class Car { private private private private ... } String model; int year; String manufacturer; String color;

public class CarBean { private List cars; public CarListController() { cars = new ArrayList(); cars.add(new Car(myModel, 2005, ManufacturerX, blue)); // add more cars } //getter setter }

51

PrimeFaces User!s Guide !

Carousel iterates through the cars collection and renders its children for each car, note that you also need to define a width for each item. LimitingVisibleItems Bu default carousel lists its items in pages with size 3. This is customizable with the rows attribute. ...

Effects Paging happens with a slider effect by default and following easing options are supported. backBoth backIn backOut bounceBoth bounceIn bounceOut easeBoth easeBothStrong easeIn easeInStrong easeNone easeOut easeOutStrong elasticBoth elasticIn elasticOut52

PrimeFaces User!s GuideNote: Easingnames arecasesensitiveandincorrectusagemay resultinjavascripterrors

SlideShow Carousel can display the contents in a slideshow, for this purposeautoPlayInterval and circular attributes are used. Following carousel displays a collection of images as a slideshow.

Content Display Another use case of carousel is tab based content display.

story begins as

prime faces users guide 3m4

Documents