indexed primefaces users_guide_3_5

of 497/497
USER’S GUIDE 3.5 Author Optimus Prime

Post on 06-May-2015

2.040 views

Category:

Technology

7 download

Embed Size (px)

TRANSCRIPT

  • 1.USERS GUIDE 3.5Author Optimus Prime

2. PrimeFaces Users GuideAbout the Author!101. Introduction!111.1 What is PrimeFaces?!112. Setup!122.1 Download!122.2 Dependencies!132.3 Conguration!132.4 Hello World!133. Component Suite!143.1 AccordionPanel!143.2 AjaxBehavior!193.3 AjaxStatus!213.4 AutoComplete !243.5 BlockUI!343.6 BreadCrumb!373.7 Button!393.8 Calendar!423.9 Captcha !533.10 Carousel!563.11 CellEditor!623.12 Charts !633.12.1 Pie Chart!633.12.2 Line Chart!663.12.3 Bar Chart!703.12.4 Donut Chart!73 2 3. PrimeFaces Users Guide3.12.5 Bubble Chart!763.12.6 Ohlc Chart!793.12.7 MeterGauge Chart!823.12.8 Skinning Charts!843.12.9 Ajax Behavior Events!853.12.10 Charting Tips!863.13 Clock!873.14 Collector!893.15 Color Picker!903.16 Column!933.17 Columns!953.18 ColumnGroup!973.19 CommandButton!983.20 CommandLink!1033.21 ConrmDialog!1063.22 ContextMenu!1093.23 Dashboard!1123.24 DataExporter!1173.25 DataGrid!1203.26 DataList!1263.27 DataTable!1303.28 DefaultCommand!1493.29 Dialog!1513.30 Drag&Drop!1563.30.1 Draggable!1563.30.2 Droppable!160 3 4. PrimeFaces Users Guide3.31 Dock!1653.32 Editor!1673.33 Effect!1713.34 FeedReader!1743.35 Fieldset!1753.36 FileDownload!1793.37 FileUpload!1823.38 Focus !1883.39 Galleria !1903.40 GMap!1933.41 GMapInfoWindow!2043.42 GraphicImage !2053.43 Growl!2103.44 HotKey!2143.45 IdleMonitor!2173.46 ImageCompare!2193.47 ImageCropper!2213.48 ImageSwitch!2253.49 Inplace !2283.50 InputMask!2323.51 InputText!2363.52 InputTextarea!2393.53 Keyboard!2443.54 Layout!2493.55 LayoutUnit!254 4 5. PrimeFaces Users Guide3.56 LightBox!2563.57 Log!2593.58 Media!2613.59 MegaMenu!2633.60 Menu!2663.61 Menubar!2713.62 MenuButton!2743.63 MenuItem!2763.64 Message!2793.65 Messages!2813.66 Mindmap!2843.67 NoticationBar!2873.68 OrderList!2893.69 OutputLabel!2933.70 OutputPanel!2963.71 OverlayPanel!2983.72 Panel!3013.73 PanelGrid!3043.74 PanelMenu!3073.75 Password!3093.76 PhotoCam!3143.77 PickList!3163.78 Poll!3233.79 Printer!3263.80 ProgressBar!327 5 6. PrimeFaces Users Guide3.81 RadioButton!3313.82 Rating!3323.83 RemoteCommand!3363.84 ResetInput!3383.85 Resizable!3403.86 Ring!3443.87 Row!3473.88 RowEditor!3483.89 RowExpansion!3493.90 RowToggler!3503.91 Schedule !3513.92 ScrollPanel!3593.93 SelectBooleanButton!3613.94 SelectBooleanCheckbox!3633.95 SelectCheckboxMenu!3653.96 SelectManyButton!3683.97 SelectManyCheckbox!3703.98 SelectManyMenu!3723.99 SelectOneButton!3753.100 SelectOneListbox!3773.101 SelectOneMenu!3803.102 SelectOneRadio !3853.103 Separator!3883.104 SlideMenu!3903.105 Slider!393 6 7. PrimeFaces Users Guide3.106 Socket!3983.107 Spacer!3993.108 Spinner!4003.109 SplitButton!4053.110 Submenu!4093.111 Stack!4103.112 SubTable!4123.113 SummaryRow!4133.114 Tab!4143.115 TabMenu!4153.116 TabView!4173.117 TagCloud!4223.118 Terminal!4253.119 ThemeSwitcher!4273.120 TieredMenu!4293.121 Toolbar!4323.122 ToolbarGroup!4343.123 Tooltip!4353.124 Tree!4383.125 TreeNode!4463.126 TreeTable!4473.127 Watermark!4503.128 Wizard!4524. Partial Rendering and Processing! 4.1 Partial Rendering!458 4587 8. PrimeFaces Users Guide4.1.1 Infrastructure!4584.1.2 Using IDs!4584.1.3 Notifying Users!4614.1.4 Bits&Pieces!4614.2 Partial Processing!4624.2.1 Partial Validation!4624.2.2 Keywords!4634.2.3 Using Ids!4634.3 PFS (PrimeFaces Selectors)!4644.4 PartialSubmit!4665. PrimeFaces Push!4675.1 Setup!4675.2 Push API!4675.3 Socket Component!4695.4 Putting It All Together!4695.4.1 Counter!4695.4.2 FacesMessage!4725.5 Tips and Tricks!4736. Javascript API!4746.1 PrimeFaces Namespace!4746.2 Ajax API!4757. Themes!4777.1 Applying a Theme !4787.2 Creating a New Theme !4797.3 How Themes Work!480 8 9. PrimeFaces Users Guide7.4 Theming Tips!4818. Utilities!4828.1 RequestContext!4828.2 EL Functions!4859. Portlets!4879.1 Dependencies!4879.2 Conguration!48810. Right-To-Left !49111. Integration with Java EE!49212. IDE Support !49312.1 NetBeans!49312.2 Eclipse!49413. Project Resources!49514. FAQ!4969 10. About the Author aatay ivici (a.k.a Optimus Prime in PrimeFaces Community) is a member of JavaServer Faces Expert Group, the founder of PrimeFaces and PMC member of open source JSF implementation Apache MyFaces. He is a recognized speaker in international conferences including JavaOne, 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 the owner of PrimeTek, the company he founded in Turkey. 11. PrimeFaces Users Guide1. Introduction 1.1 What is PrimeFaces? 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 35+ 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.11 12. PrimeFaces Users Guide2. Setup 2.1 Download PrimeFaces has a single jar called primefaces-{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 version, binary, sources and bundle. Bundle contains binary, sources and javadocs. http://www.primefaces.org/downloads.htmlDownload with Maven Group id of the dependency is org.primefaces and artifact id is primefaces. org.primefacesprimefaces3.5In addition to the configuration above you also need to add PrimeFaces maven repository to the repository list so that maven can download it. prime-repoPrime Repohttp://repository.primefaces.org12 13. PrimeFaces Users Guide2.2 Dependencies PrimeFaces only requires a JAVA 5+ runtime and a JSF 2.x implementation as mandatory dependencies. Therere some optional libraries for certain features. DependencyVersion *TypeDescriptionJSF runtime2.0 or 2.1RequiredApache MyFaces or Oracle Mojarraitext2.1.7OptionalDataExporter (PDF).apache poi3.7OptionalDataExporter (Excel).rome1.0OptionalFeedReader.commons-fileupload1.2.1OptionalFileUploadcommons-io1.4OptionalFileUpload* Listed versions are tested and known to be working with PrimeFaces, other versions of these dependencies may also work but not tested.2.3 Configuration PrimeFaces does not require any mandatory configuration.2.4 Hello World 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 like test.xhtml; When you run this page through Faces Servlet mapping, you should see a rich text editor.13 14. PrimeFaces Users Guide3. Component Suite 3.1 AccordionPanel AccordionPanel is a container component that displays content in stacked format.Info TagaccordionPanelComponent Classorg.primefaces.component.accordionpanel.AccordionpanelComponent Typeorg.primefaces.component.AccordionPanelComponent Familyorg.primefaces.componentRenderer Typeorg.primefaces.component.AccordionPanelRendererRenderer Classorg.primefaces.component.accordionpanel.AccordionPanelRendererAttributes NameDefaultTypeDescriptionidnullStringUnique identifier of the componentrenderedTRUEbooleanBoolean value to specify the rendering of the component.bindingnullObjectAn EL expression that maps to a server side UIComponent instance in a backing bean.14 15. PrimeFaces Users GuideNameDefaultTypeDescriptionactiveIndex0StringIndex of the active tab or a comma separated string of indexes when multiple mode is on.stylenullStringInline style of the container element.styleClassnullStringStyle class of the container element.onTabChangenullStringClient side callback to invoke when an inactive tab is clicked.onTabShownullStringClient side callback to invoke when a tab gets activated.dynamicFALSEBooleanDefines the toggle mode.cacheTRUEBooleanDefines if activating a dynamic tab should load the contents from server again.valuenulljava.util.L istList to iterate to display dynamic number of tabs.varnullStringName of iterator to use in a dynamic number of tabs.multipleFALSEBooleanControls multiple selection.dirltrStringDefines text direction, valid values are ltr and rtl.widgetVarnullStringName of the client side widget.Getting Started with Accordion Panel Accordion panel consists of one or more tabs and each tab can group any content. Titles can also be defined with title facet. ...More content for first tab //any number of tabs Dynamic Content 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.15 16. PrimeFaces Users GuideThis feature is useful to reduce bandwidth and speed up page loading time. By default activating a previously loaded dynamic tab does not initiate a request to load the contents again as tab is cached. To control this behavior use cache option. //..tabs Client Side Callbacks 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 Ajax Behavior Events tabChange is 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.16 17. PrimeFaces Users GuideDynamic Number of Tabs When the tabs to display are not static, use the built-in iteration feature similar to ui:repeat. ...More content Disabled Tabs A tab can be disabled by setting disabled attribute to true. ...More content for first tab //any number of tabs Multiple Selection By default, only one tab at a time can be active, enable multiple mode to activate multiple tabs. //tabs Client Side API Widget: PrimeFaces.widget.AccordionPanel MethodParamsReturn TypeDescriptionselect(index)index: Index of tab to displayvoidActivates tab with given index.unselect(index)index: Index of tab to hidevoidDeactivates tab with given index.17 18. PrimeFaces Users GuideSkinning AccordionPanel resides in a main container element which style and styleClass options apply. Following is the list of structural style classes; ClassApplies.ui-accordionMain container element.ui-accordion-headerTab header.ui-accordion-contentTab contentAs skinning style classes are global, see the main theming section for more information.18 19. PrimeFaces Users Guide3.2 AjaxBehavior AjaxBehavior is an extension to standard f:ajax. Info TagajaxBehavior Idorg.primefaces.component.AjaxBehaviorBehavior Classorg.primefaces.component.behavior.ajax.AjaxBehaviorAttributes NameDefaultTypeDescriptionlistenernullMethodExprMethod to process in partial request.immediateFALSEbooleanBoolean value that determines the phaseId, when true actions are processed at apply_request_values, when false at invoke_application phase.asyncFALSEBooleanWhen set to true, ajax requests are not queued.processnullStringComponent(s) to process in partial request.updatenullStringComponent(s) to update with ajax.onstartnullStringCallback to execute before ajax request is begins.oncompletenullStringCallback to execute when ajax request is completed.onsuccessnullStringCallback to execute when ajax request succeeds.onerrornullStringCallback to execute when ajax request fails.globalTRUEBooleanGlobal ajax requests are listened by ajaxStatus component, setting global to false will not trigger ajaxStatus.disabledFALSEBooleanDisables ajax behavior.eventnullStringClient side event to trigger ajax request.Getting Started with AjaxBehavior AjaxBehavior is attached to the component to ajaxify. 19 20. PrimeFaces Users GuideIn 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 count; } }public void setCount(int count) { this.count = count; } public void increment() { count++; }Events Default client side events are defined by components that support client behaviors, for input components it is onchange and for command components it is onclick. In order to override the dom event to trigger the ajax request use event option. In following example, ajax request is triggered when key is up on input field. Partial Processing Partial processing is used with process option which defaults to @this, meaning the ajaxified component. See section 5 for detailed information on partial processing.20 21. PrimeFaces Users Guide3.3 AjaxStatus AjaxStatus is a global notifier for ajax requests.Info TagajaxStatusComponent Classorg.primefaces.component.ajaxstatus.AjaxStatusComponent Typeorg.primefaces.component.AjaxStatusComponent Familyorg.primefaces.componentRenderer Typeorg.primefaces.component.AjaxStatusRendererRenderer Classorg.primefaces.component.ajaxstatus.AjaxStatusRendererAttributes NameDefaultTypeDescriptionidnullStringUnique identifier of the component.renderedTRUEBooleanBoolean value to specify the rendering of the component.bindingnullObjectAn el expression that maps to a server side UIComponent instance in a backing beanonstartnullStringClient side callback to execute after ajax requests start.oncompletenullStringClient side callback to execute after ajax requests complete.onprestartnullStringClient side callback to execute before ajax requests start.onsuccessnullStringClient side callback to execute after ajax requests completed succesfully.onerrornullStringClient side callback to execute when an ajax request fails.stylenullStringInline style of the component.styleClassnullStringStyle class of the component.widgetVarnullStringName of the client side widget.21 22. PrimeFaces Users GuideGetting Started with AjaxStatus AjaxStatus uses facets to represent the request status. Most common used facets are start 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. 22 23. PrimeFaces Users GuideCustom Events 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 Side API Widget: PrimeFaces.widget.AjaxStatus MethodParamsReturn TypeDescriptionbindFacet(eventName, facetId)eventName: Name of status event, facetId: Element id of facet containervoidBinds a facet to an eventbindCallback(eventName, fn)eventName: Name of status event, fn: function to bindvoidBinds a function to an eventSkinning 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. AjaxStatus also supports core JSF ajax requests as well.23 24. PrimeFaces Users Guide3.4 AutoComplete AutoComplete provides live suggestions while an input is being typed.Info TagautoCompleteComponent Classorg.primefaces.component.autocomplete.AutoCompleteComponent Typeorg.primefaces.component.AutoCompleteComponent Familyorg.primefaces.componentRenderer Typeorg.primefaces.component.AutoCompleteRendererRenderer Classorg.primefaces.component.autocomplete.AutoCompleteRendererAttributes NameDefaultTypeDescriptionidnullStringUnique identifier of the component.renderedTRUEBooleanBoolean value to specify the rendering of the component.bindingnullObjectAn el expression that maps to a server side UIComponent instance in a backing bean.valuenullObjectValue of the component than can be either an EL expression of a literal text.converternullConverter /StringAn 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.24 25. PrimeFaces Users GuideNameDefaultTypeDescriptionimmediateFALSEBooleanWhen set true, process validations logic is executed at apply request values phase for this component.requiredFALSEBooleanMarks component as required.validatornullMethodEx prA method expression that refers to a method validationg the input.valueChangeListenernullMethodEx prA method expression that refers to a method for handling a valuchangeevent.requiredMessagenullStringMessage to be displayed when required field validation fails.converterMessagenullStringMessage to be displayed when conversion fails.validatorMessagenullStringMessage to be displayed when validation fails.widgetVarnullStringName of the client side widget.completeMethodnullMethodEx prMethod providing suggestions.varnullStringName of the iterator used in pojo based suggestion.itemLabelnullStringLabel of the item.itemValuenullStringValue of the item.maxResultsunlimitedIntegerMaximum number of results to be displayed.minQueryLength1IntegerNumber of characters to be typed before starting to query.queryDelay300IntegerDelay to wait in milliseconds before sending each query to the server.forceSelectionFALSEBooleanWhen enabled, autoComplete only accepts input from the selection list.onstartnullStringClient side callback to execute before ajax request to load suggestions begins.oncompletenullStringClient side callback to execute after ajax request to load suggestions completes.globalTRUEBooleanDefines whether to trigger ajaxStatus or not.scrollHeightnullIntegerDefines the height of the items viewport.effectnullStringEffect to use when showing/hiding suggestions.effectDuration400IntegerDuration of effect in milliseconds.dropdownFALSEBooleanEnables dropdown mode when set true.panelStylenullStringInline style of the items container element. 25 26. PrimeFaces Users GuideNameDefaultTypeDescriptionpanelStyleClassnullStringStyle class of the items container element.multiplenullBooleanWhen true, enables multiple selection.processnullStringComponent(s) to process on query request.accesskeynullStringAccess key that when pressed transfers focus to the input element.altnullStringAlternate textual description of the input field.autocompletenullStringControls browser autocomplete behavior.dirnullStringDirection indication for text that does not inherit directionality. Valid values are LTR and RTL.disabledFALSEBooleanDisables input fieldlabelnullStringA localized user presentable name.langnullStringCode describing the language used in the generated markup for this component.maxlengthnullIntegerMaximum number of characters that may be entered in this field.onblurnullStringClient side callback to execute when input element loses focus.onchangenullStringClient side callback to execute when input element loses focus and its value has been modified since gaining focus.onclicknullStringClient side callback to execute when input element is clicked.ondblclicknullStringClient side callback to execute when input element is double clicked.onfocusnullStringClient side callback to execute when input element receives focus.onkeydownnullStringClient side callback to execute when a key is pressed down over input element.onkeypressnullStringClient side callback to execute when a key is pressed and released over input element.onkeyupnullStringClient side callback to execute when a key is released over input element.onmousedownnullStringClient side callback to execute when a pointer button is pressed down over input elementonmousemovenullStringClient side callback to execute when a pointer button is moved within input element.onmouseoutnullStringClient side callback to execute when a pointer button is moved away from input element. 26 27. PrimeFaces Users GuideNameDefaultTypeDescriptiononmouseovernullStringClient side callback to execute when a pointer button is moved onto input element.onmouseupnullStringClient side callback to execute when a pointer button is released over input element.onselectnullStringClient side callback to execute when text within input element is selected by user.readonlyFALSEBooleanFlag indicating that this component will prevent changes by the user.sizenullIntegerNumber of characters used to determine the width of the input element.stylenullStringInline style of the input element.styleClassnullStringStyle class of the input element.tabindexnullIntegerPosition of the input element in the tabbing order.titlenullStringAdvisory tooltip informaton.itemTipMyPositionleft topStringPosition of itemtip corner relative to item.itemTipAtPositionright bottomStringPosition of item corner relative to itemtip.Getting Started with AutoComplete 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; }//getter setterpublic List complete(String query) { List results = new ArrayList(); for (int i = 0; i < 10; i++) results.add(query + i); return results; }27 28. PrimeFaces Users GuidePojo Support 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. Following example loads a list of players, itemLabel is the label displayed as a suggestion and itemValue is the submitted value. Note that when working with pojos, you need to plug-in your own converter. public class PlayerBean { private Player selectedPlayer; }public } public }Player getSelectedPlayer() { return selectedPlayer; 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 setterLimiting the Results Number of results shown can be limited, by default there is no limit. 28 29. PrimeFaces Users GuideMinimum Query Length 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 the minQueryLength 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. Custom Content AutoComplete can display custom content by nesting columns. #{p.name} - #{p.number} Dropdown Mode When dropdown mode is enabled, a dropdown button is displayed next to the input field, clicking this button will do a search with an empty query, a regular completeMethod implementation should load all available items as a response. 29 30. PrimeFaces Users GuideMultiple Selection AutoComplete supports multiple selection as well, to use this feature set multiple option to true and define a list as your backend model. Following example demonstrates multiple selection with custom content support. #{p.name} - #{p.number} public class AutoCompleteBean { private List selectedPlayers; }//...Ajax Behavior Events Instead of waiting for user to submit the form manually to process the selected item, you can enable instant ajax selection by using the itemSelect ajax behavior. Example below demonstrates how to display a message about the selected item instantly. 30 31. PrimeFaces Users Guide 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. Similarly, itemUnselect event is provided for multiple autocomplete when an item is removed by clicking the remove icon. In this case org.primefaces.event.Unselect instance is passed to a listener if defined. ItemTip Itemtip is an advanced built-in tooltip when mouse is over on suggested items. Content of the tooltip is defined via the itemtip facet. 31 32. PrimeFaces Users GuideClient Side Callbacks onstart and oncomplete are used to execute custom javascript before and after an ajax request to load suggestions. onstart callback gets a request parameter and oncomplete gets a response parameter, these parameters contain useful information. For example request is the query string and response is the xhr request sent under the hood. Client Side API Widget: PrimeFaces.widget.AutoComplete MethodParamsReturn Typevalue: keyword for searchvoidInitiates a search with given valueclose()-voidHides suggested items menudisable()-voidDisables the input fieldenable()-voidEnables the input fielddeactivate()-voidDeactivates search behavioractivate()-voidActivates search behaviorsearch(value)DescriptionSkinning Following is the list of structural style classes; ClassApplies.ui-autocompleteContainer element..ui-autocomplete-inputInput field..ui-autocomplete-panelContainer of suggestions list..ui-autocomplete-itemsList of items.ui-autocomplete-itemEach item in the list..ui-autocomplete-queryHighlighted part in suggestions.As skinning style classes are global, see the main theming section for more information.32 33. PrimeFaces Users GuideTips 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.33 34. PrimeFaces Users Guide3.5 BlockUI BlockUI is used to block JSF components during ajax processing.Info TagblockUIComponent Classorg.primefaces.component.blockui.BlockUIComponent Typeorg.primefaces.component.BlockUIComponent Familyorg.primefaces.componentRenderer Typeorg.primefaces.component.BlockUIRendererRenderer Classorg.primefaces.component.blockui.BlockUIRendererAttributes NameDefaultTypeDescriptionidnullStringUnique identifier of the component.renderedTRUEBooleanBoolean value to specify the rendering of the component.bindingnullObjectAn el expression that maps to a server side UIComponent instance in a backing beanwidgetVarnullStringName of the client side widget.34 35. PrimeFaces Users GuideNameDefaultTypeDescriptiontriggernullStringIdentifier of the component(s) to bind.blocknullStringIdentifier of the component to block.blockedFALSEBooleanBlocks the UI by default when enabled.Getting Started with BlockUI BlockUI requires trigger and block attributes to be defined. With the special ajax integration, ajax requests whose source are the trigger components will block the ui onstart and unblock oncomplete. Example below blocks the ui of the panel when saveBtn is clicked and unblock when ajax response is received. //content Multiple triggers are defined as a comma separated list. Custom Content In order to display custom content like a loading text and animation, place the content inside the blockUI. //more columns LOADING
35 36. PrimeFaces Users GuideClient Side API Widget: PrimeFaces.widget.BlockUI MethodParamsReturn TypeDescriptionshow()-voidBlocks the UI.hide()-voidUnblocks the UISkinning Following is the list of structural style classes; ClassApplies.ui-blockuiContainer element..ui-blockui-contentContainer for custom content.As skinning style classes are global, see the main theming section for more information. Tips BlockUI does not support absolute or fixed positioned components. e.g. dialog.36 37. PrimeFaces Users Guide3.6 BreadCrumb Breadcrumb is a navigation component that provides contextual information about page hierarchy in the workflow.Info TagbreadCrumbComponent Classorg.primefaces.component.breadcrumb.BreadCrumbComponent Typeorg.primefaces.component.BreadCrumbComponent Familyorg.primefaces.componentRenderer Typeorg.primefaces.component.BreadCrumbRendererRenderer Classorg.primefaces.component.breadcrumb.BreadCrumbRendererAttributes NameDefaultTypeDescriptionidnullStringUnique identifier of the component.renderedTRUEBooleanBoolean value to specify the rendering of the component.bindingnullObjectAn el expression that maps to a server side UIComponent instance in a backing beanwidgetVarnullStringName of the client side widget.modelnullMenuModelMenuModel instance to create menus programmaticallystylenullStringStyle of main container element.styleClassnullStringStyle class of main containerGetting Started with BreadCrumb Steps are defined as child menuitem components in breadcrumb. //more menuitems 37 38. PrimeFaces Users GuideDynamic Menus Menus can be created programmatically as well, see the dynamic menus part in menu component section for more information and an example. Skinning Breadcrumb resides in a container element that style and styleClass options apply. Following is the list of structural style classes; Style ClassApplies.ui-breadcrumbMain breadcrumb container element..ui-breadcrumb .ui-menu-item-linkEach menuitem..ui-breadcrumb .ui-menu-item-textEach menuitem label..ui-breadcrumb-chevronSeperator of menuitems.As skinning style classes are global, see the main theming 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.38 39. PrimeFaces Users Guide3.7 Button Button is an extension to the standard h:button component with skinning capabilities.Info TagbuttonComponent Classorg.primefaces.component.button.ButtonComponent Typeorg.primefaces.component.ButtonComponent Familyorg.primefaces.componentRenderer Typeorg.primefaces.component.ButtonRendererRenderer Classorg.primefaces.component.button.ButtonRendererAttributes NameDefaultTypeDescriptionidnullStringUnique identifier of the component.renderedTRUEBooleanBoolean value to specify the rendering of the component.bindingnullObjectAn el expression that maps to a server side UIComponent instance in a backing bean.widgetVarnullStringName of the client side widget.valuenullObjectValue of the component than can be either an EL expression of a literal text.outcomenullStringUsed to resolve a navigation case.includeViewParamsFALSEBooleanWhether to include page parameters in target URIfragmentnullStringIdentifier of the target page which should be scrolled to.disabledFALSEBooleanDisables button.accesskeynullStringAccess key that when pressed transfers focus to button.altnullStringAlternate textual description.dirnullStringDirection indication for text that does not inherit directionality. Valid values are LTR and RTL.imagenullStringStyle class for the button icon. (deprecated: use icon)39 40. PrimeFaces Users GuideNameDefaultTypeDescriptionlangnullStringCode describing the language used in the generated markup for this component.onblurnullStringClient side callback to execute when button loses focus.onchangenullStringClient side callback to execute when button loses focus and its value has been modified since gaining focus.onclicknullStringClient side callback to execute when button is clicked.ondblclicknullStringClient side callback to execute when button is double clicked.onfocusnullStringClient side callback to execute when button receives focus.onkeydownnullStringClient side callback to execute when a key is pressed down over button.onkeypressnullStringClient side callback to execute when a key is pressed and released over button.onkeyupnullStringClient side callback to execute when a key is released over button.onmousedownnullStringClient side callback to execute when a pointer button is pressed down over button.onmousemovenullStringClient side callback to execute when a pointer button is moved within buttononmouseoutnullStringClient side callback to execute when a pointer button is moved away from button.onmouseovernullStringClient side callback to execute when a pointer button is moved onto button.onmouseupnullStringClient side callback to execute when a pointer button is released over button.stylenullStringInline style of the button.styleClassnullStringStyle class of the button.readOnlyFALSEBooleanMakes button read only.tabindexnullIntegerPosition in the tabbing order.titlenullStringAdvisory tooltip informaton.hrefnullStringResource to link directly to implement anchor behavior.iconnullStringIcon of the button.iconPosleftStringPosition of the button icon.escapeTRUEBooleanDefines whether label would be escaped or not.40 41. PrimeFaces Users GuideGetting Started with Button 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 icon 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. .star { background-image: url("images/star.png"); }Skinning Button renders a button tag which style and styleClass applies. Following is the list of structural style classes; Style ClassApplies.ui-buttonButton element.ui-button-text-onlyButton element when icon is not used.ui-button-textLabel of buttonAs skinning style classes are global, see the main theming section for more information.41 42. PrimeFaces Users Guide3.8 Calendar Calendar is an input component used to select a date featuring display modes, paging, localization, ajax selection and more.Info TagcalendarComponent Classorg.primefaces.component.calendar.CalendarComponent Typeorg.primefaces.component.CalendarComponent Familyorg.primefaces.componentRenderer Typeorg.primefaces.component.CalendarRendererRenderer Classorg.primefaces.component.calendar.CalendarRendererAttributes NameDefaultTypeDescriptionidnullStringUnique identifier of the componentrenderedTRUEBooleanBoolean value to specify the rendering of the component.bindingnullObjectAn el expression that maps to a server side UIComponent instance in a backing beanvaluenulljava.util.DateValue of the componentconverternullConverter/ StringAn 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 idimmediateFALSEBooleanWhen set true, process validations logic is executed at apply request values phase for this component. 42 43. PrimeFaces Users GuideNameDefaultTypeDescriptionrequiredFALSEBooleanMarks component as requiredvalidatornullMethodExprA method expression that refers to a method validationg the inputvalueChangeListenernullMethodExprA method expression that refers to a method for handling a valuchangeeventrequiredMessagenullStringMessage to be displayed when required field validation fails.converterMessagenullStringMessage to be displayed when conversion fails.validatorMessagenullStringMessage to be displayed when validation fails.widgetVarnullStringName of the client side widget.mindatenullDate or StringSets calendar's minimum visible datemaxdatenullDate or StringSets calendar's maximum visible datepagesint1Enables multiple page rendering.disabledFALSEBooleanDisables the calendar when set to true.modepopupStringDefines how the calendar will be displayed.patternMM/dd/ yyyyStringDateFormat pattern for localizationlocalenullLocale/StringLocale to be used for labels and conversion.popupIconnullStringIcon of the popup buttonpopupIconOnlyFALSEBooleanWhen enabled, popup icon is rendered without the button.navigatorFALSEBooleanEnables month/year navigatortimeZonenullTimeZoneString or a java.util.TimeZone instance to specify the timezone used for date conversion, defaults to TimeZone.getDefault()readonlyInputFALSEBooleanMakes input text of a popup calendar readonly.showButtonPanelFALSEBooleanVisibility of button panel containing today and done buttons.effectnullStringEffect to use when displaying and showing the popup calendar.effectDurationnormalStringDuration of the effect.showOnbothStringClient side event that displays the popup calendar. 43 44. PrimeFaces Users GuideNameDefaultTypeDescriptionshowWeekFALSEBooleanDisplays the week number next to each week.disabledWeekendsFALSEBooleanDisables weekend columns.showOtherMonthsFALSEBooleanDisplays days belonging to other months.selectOtherMonthsFALSEBooleanEnables selection of days belonging to other months.yearRangenullStringYear range for the navigator, default "c-10:c +10"timeOnlyFALSEBooleanShows only timepicker without date.stepHour1IntegerHour steps.stepMinute1IntegerMinute steps.stepSecond1IntegerSecond steps.minHour0IntegerMinimum boundary for hour selection.maxHour23IntegerMaximum boundary for hour selection.minMinute0IntegerMinimum boundary for minute selection.maxMinute59IntegerMaximum boundary for hour selection.minSecond0IntegerMinimum boundary for second selection.maxSecond59IntegerMaximum boundary for second selection.pagedatenullObjectInitial date to display if value is null.accesskeynullStringAccess key that when pressed transfers focus to the input element.altnullStringAlternate textual description of the input field.autocompletenullStringControls browser autocomplete behavior.dirnullStringDirection indication for text that does not inherit directionality. Valid values are LTR and RTL.labelnullStringA localized user presentable name.langnullStringCode describing the language used in the generated markup for this component.maxlengthnullIntegerMaximum number of characters that may be entered in this field.onblurnullStringClient side callback to execute when input element loses focus.44 45. PrimeFaces Users GuideNameDefaultTypeDescriptiononchangenullStringClient side callback to execute when input element loses focus and its value has been modified since gaining focus.onclicknullStringClient side callback to execute when input element is clicked.ondblclicknullStringClient side callback to execute when input element is double clicked.onfocusnullStringClient side callback to execute when input element receives focus.onkeydownnullStringClient side callback to execute when a key is pressed down over input element.onkeypressnullStringClient side callback to execute when a key is pressed and released over input element.onkeyupnullStringClient side callback to execute when a key is released over input element.onmousedownnullStringClient side callback to execute when a pointer button is pressed down over input elementonmousemovenullStringClient side callback to execute when a pointer button is moved within input element.onmouseoutnullStringClient side callback to execute when a pointer button is moved away from input element.onmouseovernullStringClient side callback to execute when a pointer button is moved onto input element.onmouseupnullStringClient side callback to execute when a pointer button is released over input element.onselectnullStringClient side callback to execute when text within input element is selected by user.readonlyFALSEBooleanFlag indicating that this component will prevent changes by the user.sizenullIntegerNumber of characters used to determine the width of the input element.tabindexnullIntegerPosition of the input element in the tabbing order.titlenullStringAdvisory tooltip informaton.beforeShowDaynullStringClient side callback to execute before displaying a date, used to customize date display.45 46. PrimeFaces Users GuideGetting Started with Calendar Value of the calendar should be a java.util.Date. public class DateBean { private Date date; }//Getter and SetterDisplay Modes Calendar has two main display modes, popup (default) and inline. Inline Popup 46 47. PrimeFaces Users GuideshowOn 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 the pages attribute. 47 48. PrimeFaces Users GuideLocalization 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+LocalesTranslation is a simple javascript object, we suggest adding the code to a javascript file and include in your application. Following is a Turkish calendar. To override calculated pattern from locale, use the pattern option; 48 49. PrimeFaces Users GuideEffects Various effects can be used when showing and hiding the popup calendar, options are; show slideDown fadeIn blind bounce clip drop fold slideAjax Behavior Events 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.SelectEvent instance. public void handleDateSelect(SelectEvent event) { Date date = (Date) event.getObject(); //Add facesmessage }In popup mode, calendar also supports regular ajax behavior events like blur, keyup and more. Date Ranges Using mindate and maxdate options, selectable dates can be restricted. Values for these attributes can either be a string or a java.util.Date. 49 50. PrimeFaces Users GuideNavigator Navigator is an easy way to jump between months/years quickly. TimePicker TimePicker functionality is enabled by adding time format to your pattern. Advanced Customization Use beforeShowDay javascript callback to customize the look of each date. The function returns an array with two values, first one is flag to indicate if date would be displayed as enabled and second parameter is the optional style class to add to date cell. Following example disabled tuesdays and fridays. 50 51. PrimeFaces Users Guide functiontuesdaysAndFridaysDisabled(date) { var day = date.getDay(); return [(day != 2 && day != 5), ''] }Client Side API Widget: PrimeFaces.widget.Calendar MethodParams -getDate() setDate(date)Return Type DateReturn selected datevoidSets display datedate: Date to displayDescriptiondisable()-voidDisables calendarenable()-voidEnables calendarSkinning Calendar resides in a container element which style and styleClass options apply. Following is the list of structural style classes; Style ClassApplies.ui-datepickerMain container.ui-datepicker-headerHeader container.ui-datepicker-prevPrevious month navigator.ui-datepicker-nextNext month navigator.ui-datepicker-titleTitle.ui-datepicker-monthMonth display.ui-datepicker-tableDate table.ui-datepicker-week-endLabel of weekends.ui-datepicker-other-monthDates belonging to other months.ui-datepicker tdEach cell date.ui-datepicker-buttonpaneButton panel 51 52. PrimeFaces Users GuideStyle ClassApplies.ui-datepicker-currentToday button.ui-datepicker-closeClose buttonAs skinning style classes are global, see the main theming section for more information.52 53. PrimeFaces Users Guide3.9 Captcha Captcha is a form validation component based on Recaptcha API.Info TagcaptchaComponent Classorg.primefaces.component.captcha.CaptchaComponent Typeorg.primefaces.component.CaptchaComponent Familyorg.primefaces.componentRenderer Typeorg.primefaces.component.CaptchaRendererRenderer Classorg.primefaces.component.captcha.CaptchaRendererAttributes NameDefaultTypeDescriptionidnullStringUnique identifier of the component.renderedTRUEBooleanBoolean value to specify the rendering of the component, when set to false component will not be rendered.bindingnullObjectAn el expression that maps to a server side UIComponent instance in a backing bean.valuenullObjectValue of the component than can be either an EL expression of a literal text.converternullConverter/ StringAn 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.immediateFALSEBooleanWhen set true, process validations logic is executed at apply request values phase for this component.requiredFALSEBooleanMarks component as required. 53 54. PrimeFaces Users GuideNameDefaultTypeDescriptionvalidatornullMethodExprA method binding expression that refers to a method validationg the input.valueChangeListenernullValueChange ListenerA method binding expression that refers to a method for handling a valuchangeevent.requiredMessagenullStringMessage to be displayed when required field validation fails.converterMessagenullStringMessage to be displayed when conversion fails.validatorMessagenullStringMessage to be displayed when validation fields.publicKeynullStringPublic recaptcha key for a specific domain (deprecated)themeredStringTheme of the captcha.languageenStringKey of the supported languages.tabindexnullIntegerPosition of the input element in the tabbing order.labelnullStringUser presentable field name.secureFALSEBooleanEnables https supportGetting Started with Captcha 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_KEYYOUR_PRIVATE_KEYprimefaces.PUBLIC_CAPTCHA_KEYYOUR_PUBLIC_KEYThat is it, now you can use captcha as follows; 54 55. PrimeFaces Users GuideThemes Captcha features following built-in themes for look and feel customization. red (default) white blackglass cleanThemes are applied via the theme attribute. Languages Text instructions displayed on captcha is customized with the language attribute. Below is a captcha with Turkish text. Overriding Validation Messages By default captcha displays its own validation messages, this can be easily overridden by the JSF message bundle mechanism. Corresponding keys are; Summaryprimefaces.captcha.INVALIDDetailprimefaces.captcha.INVALID_detailTips Use label option to provide readable error messages in case validation fails. Enable secure option to support https otherwise browsers will give warnings. See http://www.google.com/recaptcha/learnmore to learn more about how reCaptcha works.55 56. PrimeFaces Users Guide3.10 Carousel Carousel is a multi purpose component to display a set of data or general content with slide effects.Info TagcarouselComponent Classorg.primefaces.component.carousel.CarouselComponent Typeorg.primefaces.component.CarouselComponent Familyorg.primefaces.componentRenderer Typeorg.primefaces.component.CarouselRendererRenderer Classorg.primefaces.component.carousel.CarouselRendererAttributes NameDefaultTypeDescriptionidnullStringUnique identifier of the componentrenderedTRUEBooleanBoolean value to specify the rendering of the component, when set to false component will not be rendered.bindingnullObjectAn el expression that maps to a server side UIComponent instance in a backing beanvaluenullObjectA value expression that refers to a collectionvarnullStringName of the request scoped iteratornumVisible3IntegerNumber of visible items per pagefirstVisible0IntegerIndex of the first element to be displayedwidgetVarnullStringName of the client side widget.circularFALSEBooleanSets continuous scrollingverticalFALSEBooleanSets vertical scrolling56 57. PrimeFaces Users GuideNameDefaultTypeDescriptionautoPlayInterval0IntegerSets the time in milliseconds to have Carousel start scrolling automatically after being initializedpageLinks3IntegerDefines the number of page links of paginator.effectslideStringName of the animation, could be fade or slide.easingeaseInOutCircStringName of the easing animation.effectDuration500IntegerDuration of the animation in milliseconds.dropdownTemplate.{page}StringTemplate string for dropdown of paginator.stylenullStringInline style of the component..styleClassnullStringStyle class of the component..itemStylenullStringInline style of each item.itemStyleClassnullStringStyle class of each item.headerTextnullStringLabel for header.footerTextnullStringLabel for footer.Getting Started with Carousel 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 } }//getter setterCarListController() { cars = new ArrayList(); cars.add(new Car("myModel", 2005, "ManufacturerX", "blue")); //add more cars57 58. PrimeFaces Users 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. Limiting Visible Items 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 easeInOutCirc easeOutStrong elasticBoth elasticIn elasticOut 58 59. PrimeFaces Users GuideSlideShow Carousel can display the contents in a slideshow, for this purpose autoPlayInterval 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.59 60. PrimeFaces Users GuideItem Selection Sample below selects an item from the carousel and displays details within a dialog. public class CarBean { private List cars;private Car selected; }//getters and settersHeader and Footer Header and Footer of carousel can be defined in two ways either, using headerText and footerText options that take simple strings as labels or by header and footer facets that can take any custom content. Skinning Carousel resides in a container element which style and styleClass options apply. itemStyle and itemStyleClass attributes apply to each item displayed by carousel. Following is the list of structural style classes; Style ClassApplies.ui-carouselMain container.ui-carousel-headerHeader container.ui-carousel-header-titleHeader content.ui-carousel-viewportContent container 60 61. PrimeFaces Users GuideStyle ClassApplies.ui-carousel-buttonNavigation buttons.ui-carousel-next-buttonNext navigation button of paginator.ui-carousel-prev-buttonPrev navigation button of paginator.ui-carousel-page-linksPage links of paginator..ui-carousel-page-linkEach page link of paginator..ui-carousel-itemEach item.As skinning style classes are global, see the main theming section for more information. Tips Carousel is a NamingContainer, make sure you reference components outside of carousel properly following conventions.61 62. PrimeFaces Users Guide3.11 CellEditor CellEditor is a helper component of datatable used for incell editing. Info TagcellEditorComponent Classorg.primefaces.component.celleditor.CellEditorComponent Typeorg.primefaces.component.CellEditorComponent Familyorg.primefaces.componentRenderer Typeorg.primefaces.component.CellEditorRendererRenderer Classorg.primefaces.component.celleditor.CellEditorRendererAttributes NameDefaultTypeDescriptionidnullStringUnique identifier of the componentrenderedTRUEBooleanBoolean value to specify the rendering of the component, when set to false component will not be rendered.bindingnullObjectAn el expression that maps to a server side UIComponent instance in a backing beanGetting Started with CellEditor See inline editing section in datatable documentation for more information about usage.62 63. PrimeFaces Users Guide3.12 Charts Charts are used to display graphical data. Therere various chart types like pie, bar, line and more.3.12.1 Pie Chart Pie chart displays category-data pairs in a pie graphic. Info TagpieChartComponent Classorg.primefaces.component.chart.pie.PieChartComponent Typeorg.primefaces.component.chart.PieChartComponent Familyorg.primefaces.componentRenderer Typeorg.primefaces.component.chart.PieChartRendererRenderer Classorg.primefaces.component.chart.pie.PieChartRendererAttributes NameDefaultTypeDescriptionidnullStringUnique identifier of the componentrenderedTRUEBooleanBoolean value to specify the rendering of the component, when set to false component will not be rendered.bindingnullObjectAn el expression that maps to a server side UIComponent instance in a backing beanwidgetVarnullStringName of the client side widgetvaluenullChartModelDatasource to be displayed on the chartstylenullStringInline style of the chart.styleClassnullStringStyle class of the chart.titlenullStringTitle of the chart.legendPositionnullStringPosition of the legend.seriesColorsnullStringComma separated list of colors in hex format.diameternullIntegerDiameter of the pie, auto computed by default.sliceMargin0IntegerGap between slices.fillTRUEBooleanRender solid slices. 63 64. PrimeFaces Users GuideNameDefaultTypeDescriptionshadowTRUEBooleanShows shadow or not.showDataLabelsFALSEBooleanDisplays data on each slice.dataFormatpercentStringFormat of data labels.legendCols1IntegerColumn count of legend.legendRowsnullIntegerRow count of legend.extendernullStringClient side function to extend chart with low level jqplot options.Getting started with PieChart PieChart is created with an org.primefaces.model.chart.PieChartModel instance. public class Bean { private PieChartModel model; public } }public PieChartModel getModel() { return model; }Bean() { model = new PieChartModel(); model.set("Brand 1", 540); model.set("Brand 2", 325); model.set("Brand 3", 702); model.set("Brand 4", 421);64 65. PrimeFaces Users GuideCustomization PieChart can be customized using various options such as fill, sliceMargin and diameter, here is an example; 65 66. PrimeFaces Users Guide3.12.2 Line Chart Line chart visualizes one or more series of data in a line graph. Info TaglineChartComponent Classorg.primefaces.component.chart.line.LineChartComponent Typeorg.primefaces.component.chart.LineChartComponent Familyorg.primefaces.componentRenderer Typeorg.primefaces.component.chart.LineChartRendererRenderer Classorg.primefaces.component.chart.line.LineChartRendererAttributes NameDefaultTypeDescriptionidnullStringUnique identifier of the componentrenderedTRUEBooleanBoolean value to specify the rendering of the component, when set to false component will not be rendered.bindingnullObjectAn el expression that maps to a server side UIComponent instance in a backing beanwidgetVarnullStringName of the client side widgetvaluenullChartModelDatasource to be displayed on the chartstylenullStringInline style of the chart.styleClassnullStringStyle class of the chart.titlenullStringTitle of the chart.legendPositionnullStringPosition of the legend.minYnullDoubleMinimum Y axis value.maxYnullDoubleMaximum Y axis value.minXnullDoubleMinimum X axis value.maxXnullDoubleMaximum X axis value.breakOnNullFALSEBooleanWhether line segments should be broken at null value, fall will join point on either side of line.seriesColorsnullStringComma separated list of colors in hex format.66 67. PrimeFaces Users GuideNameDefaultTypeDescriptionshadowTRUEBooleanShows shadow or not.fillFALSEBooleanWhether to fill under lines.stackedFALSEBooleanWhether to stack series.showMarkersTRUEBooleanDisplays markers at data points.xaxisLabelnullStringLabel of the x-axis.yaxisLabelnullStringLabel of the y-axis.xaxisAnglenullIntegerAngle of the x-axis ticks.yaxisAnglenullIntegerAngle of the y-axis ticks.legendCols1IntegerColumn count of legend.legendRowsnullIntegerRow count of legend.zoomFALSEBooleanEnables plot zooming.extendernullStringClient side function to extend chart with low level jqplot options.animateFALSEBooleanEnables animation on plot rendering.showDataTipTRUEBooleanDefines visibility of datatip.datatipFormatnullStringTemplate string for datatips.Getting started with LineChart LineChart is created with an org.primefaces.model.chart.CartesianChartModel instance.67 68. PrimeFaces Users Guide public class Bean { private CartesianChartModel model; public ChartBean() { model = new CartesianChartModel(); ChartSeries girls = new ChartSeries(); girls.setLabel("Girls"); } }model.addSeries(boys); model.addSeries(girs);ChartSeries boys = new ChartSeries(); boys.setLabel("Boys"); boys.set("2004", 120); boys.set("2005", 100);girls.set("2004", 52); girls.set("2005", 60);public CartesianChartModel getModel() { return model; }AreaChart AreaCharts is implemented by enabling stacked and fill options. 68 69. PrimeFaces Users Guide69 70. PrimeFaces Users Guide3.12.3 Bar Chart Bar chart visualizes one or more series of data using bars. Info TagbarChartComponent Classorg.primefaces.component.chart.bar.BarChartComponent Typeorg.primefaces.component.chart.BarChartComponent Familyorg.primefaces.componentRenderer Typeorg.primefaces.component.chart.BarChartRendererRenderer Classorg.primefaces.component.chart.bar.BarChartRendererAttributes NameDefaultTypeDescriptionidnullStringUnique identifier of the componentrenderedTRUEBooleanBoolean value to specify the rendering of the component, when set to false component will not be renderedbindingnullObjectAn el expression that maps to a server side UIComponent instance in a backing beanwidgetVarnullStringName of the client side widgetvaluenullChartModelDatasource to be displayed on the chartstylenullStringInline style of the chart.styleClassnullStringStyle class of the chart.titlenullStringTitle of the chart.legendPositionnullStringPosition of the legend.barPadding8IntegerPadding of bars.barMargin10IntegerMargin of bars.orientationverticalStringOrientation of bars, valid values are vertical and horizontal.stackedFALSEBooleanEnables stacked display of bars.minnullDoubleMinimum boundary value.maxnullDoubleMaximum boundary value.70 71. PrimeFaces Users GuideNameDefaultTypeDescriptionbreakOnNullFALSEBooleanWhether line segments should be broken at null value, fall will join point on either side of line.seriesColorsnullStringComma separated list of colors in hex format.shadowTRUEBooleanShows shadow or not.xaxisLabelnullStringLabel of the x-axis.yaxisLabelnullStringLabel of the y-axis.xaxisAnglenullIntegerAngle of the x-axis ticks.yaxisAnglenullIntegerAngle of the y-axis ticks.legendCols1IntegerColumn count of legend.legendRowsnullIntegerRow count of legend.zoomFALSEBooleanEnables plot zooming.extendernullStringClient side function to extend chart with low level jqplot options.animateFALSEBooleanEnables animation on plot rendering.showDataTipTRUEBooleanDefines visibility of datatip.datatipFormatnullStringTemplate string for datatips.Getting Started with Bar Chart BarChart is created with an org.primefaces.model.chart.CartesianChartModel instance. Reusing the same model sample from lineChart section; 71 72. PrimeFaces Users GuideOrientation Bars can be displayed horizontally using the orientation attribute. Stacked BarChart Enabling stacked option displays bars in stacked format.. 72 73. PrimeFaces Users Guide3.12.4 Donut Chart DonutChart is a combination of pie charts. Info TagdonutChartComponent Classorg.primefaces.component.chart.donut.DonutChartComponent Typeorg.primefaces.component.chart.DonutChartComponent Familyorg.primefaces.componentRenderer Typeorg.primefaces.component.chart.DonutChartRendererRenderer Classorg.primefaces.component.chart.donut.DonutChartRendererAttributes NameDefaultTypeDescriptionidnullStringUnique identifier of the componentrenderedTRUEBooleanBoolean value to specify the rendering of the component, when set to false component will not be rendered.bindingnullObjectAn el expression that maps to a server side UIComponent instance in a backing bean.widgetVarnullStringName of the client side widgetvaluenullChartModelDatasource to be displayed on the chartstylenullStringInline style of the chart.styleClassnullStringStyle class of the chart.titlenullStringTitle of the chart.legendPositionnullStringPosition of the legend.seriesColorsnullStringComma separated list of colors in hex format.sliceMargin0IntegerGap between slices.fillTRUEBooleanRender solid slices.shadowTRUEBooleanShows shadow or not.showDataLabelsFALSEBooleanDisplays data on each slice.dataFormatpercentStringFormat of data labels.legendCols1IntegerColumn count of legend.73 74. PrimeFaces Users GuideNameDefaultTypeDescriptionlegendRowsnullIntegerRow count of legend.extendernullStringClient side function to extend chart with low level jqplot options.Getting started with DonutChart PieChart is created with an org.primefaces.model.chart.DonutChartModel instance. public class Bean { private DonutChart model; public Bean() { model = new DonutChart(); Map circle1 = new LinkedHashMap(); circle1.put("Brand 1", 150); circle1.put("Brand 2", 400); circle1.put("Brand 3", 200); circle1.put("Brand 4", 10); donutModel.addCircle(circle1); Map circle2 = new LinkedHashMap(); circle2.put("Brand 1", 540); circle2.put("Brand 2", 125); circle2.put("Brand 3", 702); circle2.put("Brand 4", 421); donutModel.addCircle(circle2); Map circle3 = new LinkedHashMap(); circle3.put("Brand 1", 40); circle3.put("Brand 2", 325); circle3.put("Brand 3", 402); circle3.put("Brand 4", 421); donutModel.addCircle(circle3);} }public DonutChart getModel() { return model; }74 75. PrimeFaces Users GuideCustomization DonutChart can be customized using various options; 75 76. PrimeFaces Users Guide3.12.5 Bubble Chart BubbleChart visualizes entities that are defined in terms of three distinct numeric values. Info TagbubbleChartComponent Classorg.primefaces.component.chart.bubble.BubbleChartComponent Typeorg.primefaces.component.chart.BubbleChartComponent Familyorg.primefaces.componentRenderer Typeorg.primefaces.component.chart.BubbleChartRendererRenderer Classorg.primefaces.component.chart.bubble.BubbleChartRendererAttributes NameDefaultTypeDescriptionidnullStringUnique identifier of the componentrenderedTRUEBooleanBoolean value to specify the rendering of the component, when set to false component will not be renderedbindingnullObjectAn el expression that maps to a server side UIComponent instance in a backing beanwidgetVarnullStringName of the client side widgetvaluenullChartModelDatasource to be displayed on the chartstylenullStringInline style of the chart.styleClassnullStringStyle class of the chart.titlenullStringTitle of the chart.shadowTRUEBooleanShows shadow or not.seriesColorsnullStringComma separated list of colors in hex format.bubbleGradientsFALSEBooleanEnables gradient fills instead of flat colors.bubbleAlpha70IntegerAlpha transparency of a bubble.showLabelsTRUEBooleanDisplays labels on buttons.xaxisLabelnullStringLabel of the x-axis.yaxisLabelnullStringLabel of the y-axis.xaxisAnglenullIntegerAngle of the x-axis ticks. 76 77. PrimeFaces Users GuideNameDefaultTypeDescriptionyaxisAnglenullIntegerAngle of the y-axis ticks.zoomFALSEBooleanEnables plot zooming.extendernullStringClient side function to extend chart with low level jqplot options.showDataTipTRUEBooleanDefines visibility of datatip.datatipFormatnullStringTemplate string for datatips.Getting started with BubbleChart PieChart is created with an org.primefaces.model.chart.BubbleChartModel instance. public class Bean { private BubbleChartModel model; public Bean() { bubbleModel = new BubbleChartModel(); bubbleModel.addBubble(new bubbleModel.addBubble(new bubbleModel.addBubble(new bubbleModel.addBubble(new bubbleModel.addBubble(new bubbleModel.addBubble(new bubbleModel.addBubble(newBubbleChartSeries("Acura", 70, 183,55)); BubbleChartSeries("Alfa Romeo", 45, 92, 36)); BubbleChartSeries("AM General", 24, 104, 40)); BubbleChartSeries("Bugatti", 50, 123, 60)); BubbleChartSeries("BMW", 15, 89, 25)); BubbleChartSeries("Audi", 40, 180, 80)); BubbleChartSeries("AstonMartin", 70, 70, 48));} }public BubbleChartModel getModel() { return model; }77 78. PrimeFaces Users GuideCustomization BubbleChart can be customized using various options; 78 79. PrimeFaces Users Guide3.12.6 Ohlc Chart An open-high-low-close chart is a type of graph typically used to visualize movements in the price of a financial instrument over time. Info TagohlcChartComponent Classorg.primefaces.component.chart.ohlc.OhlcChartComponent Typeorg.primefaces.component.chart.OhlcChartComponent Familyorg.primefaces.componentRenderer Typeorg.primefaces.component.chart.OhlcChartRendererRenderer Classorg.primefaces.component.chart.ohlc.OhlcChartRendererAttributes NameDefaultTypeDescriptionidnullStringUnique identifier of the componentrenderedTRUEBooleanBoolean value to specify the rendering of the component, when set to false component will not be renderedbindingnullObjectAn el expression that maps to a server side UIComponent instance in a backing beanwidgetVarnullStringName of the client side widgetvaluenullChartModelDatasource to be displayed on the chartstylenullStringInline style of the chart.styleClassnullStringStyle class of the chart.titlenullStringTitle of the chart.seriesColorsnullStringComma separated list of colors in hex format.candleStickFALSEBooleanEnables candle stick display mode.xaxisLabelnullStringLabel of the x-axis.yaxisLabelnullStringLabel of the y-axis.xaxisAnglenullIntegerAngle of the x-axis ticks.yaxisAnglenullIntegerAngle of the y-axis ticks.zoomFALSEBooleanEnables plot zooming.79 80. PrimeFaces Users GuideNameDefaultTypeDescriptionextendernullStringClient side function to extend chart with low level jqplot options.animateFALSEBooleanEnables animation on plot rendering.showDataTipTRUEBooleanDefines visibility of datatip.datatipFormatnullStringTemplate string for datatips.Getting started with OhlcChart OhlcChart is created with an org.primefaces.model.chart.OhlcChartModel instance. public class Bean { private OhlcChartModel model;public Bean() { model = new OhlcChartModel(); ohlcModel.addRecord(new ohlcModel.addRecord(new ohlcModel.addRecord(new ohlcModel.addRecord(new ohlcModel.addRecord(new ohlcModel.addRecord(new ohlcModel.addRecord(newOhlcChartSeries(2007,143.82,144.56,136.04,136.97)); OhlcChartSeries(2008,138.7,139.68,135.18,135.4)); OhlcChartSeries(2009,143.46,144.66,139.79,140.02)); OhlcChartSeries(2010,140.67,143.56,132.88,142.44)); OhlcChartSeries(2011,136.01,139.5,134.53,139.48)); OhlcChartSeries(2012,124.76,135.9,124.55,135.81)); OhlcChartSeries(2012,123.73,129.31,121.57,122.5));} //getter }80 81. PrimeFaces Users GuideCandleStick OhlcChart can display data in candle stick format as well. 81 82. PrimeFaces Users Guide3.12.7 MeterGauge Chart MeterGauge chart visualizes data on a meter gauge display. Info TagmeterGaugeChartComponent Classorg.primefaces.component.chart.metergauge.MeterGaugeChartComponent Typeorg.primefaces.component.chart.MeterGaugeComponent Familyorg.primefaces.componentRenderer Typeorg.primefaces.component.chart.MeterGaugeChartRendererRenderer Classorg.primefaces.component.chart.metergauge.MeterGaugeChartRendererAttributes NameDefaultTypeDescriptionidnullStringUnique identifier of the componentrenderedTRUEBooleanBoolean value to specify the rendering of the component, when set to false component will not be rendered.bindingnullObjectAn el expression that maps to a server side UIComponent instance in a backing beanwidgetVarnullStringName of the client side widgetvaluenullChartModelDatasource to be displayed on the chartstylenullStringInline style of the chart.styleClassnullStringStyle class of the chart.titlenullStringTitle of the chart.seriesColorsnullStringComma separated list of colors in hex format.showTickLabelsTRUEBooleanDisplays ticks around gauge.labelHeightAdjust-25IntegerNumber of pixels to offset the label up and down.intervalOuterRadius85IntegerRadius of the outer circle of the internal ring.minnullDoubleMinimum boundary value.maxnullDoubleMaximum boundary value.labelnullStringLabel of the gauge.82 83. PrimeFaces Users GuideNameDefaultextendernullType StringDescription Client side function to extend chart with low level jqplot options.Getting started with MeterGaugeChart PieChart is created with an org.primefaces.model.chart.MeterGaugeChartModel instance. public class Bean { private MeterGaugeChartModel model; public Bean() { List intervals = new ArrayList(){{ add(20); add(50); add(120); add(220); }};} }public MeterGaugeChartModel getModel() { return model; }model = new MeterGaugeChartModel(140, intervals);Customization MeterGaugeChart can be customized using various options; 83 84. PrimeFaces Users Guide3.12.8 Skinning Charts Charts are built on top of jqlot javascript library that uses a canvas tag and can be styled using regular css. Following is the list of style classes; Style ClassApplies.jqplot-targetPlot target container..jqplot-axisAxes..jqplot-xaxisPrimary x-axis..jqplot-yaxisPrimary y-axis..jqplot-x2axis, .jqplot-x3axis ...2nd, 3rd ... x-axis..jqplot-y2axis, .jqplot-y3axis ...2nd, 3rd ... y-axis..jqplot-axis-tickAxis ticks..jqplot-xaxis-tickPrimary x-axis ticks..jqplot-x2axis-tickSecondary x-axis ticks..jqplot-yaxis-tickPrimary y-axis-ticks..jqplot-y2axis-tickSeconday y-axis-ticks.table.jqplot-table-legendLegend table..jqplot-titleTitle of the chart..jqplot-cursor-tooltipCursor tooltip..jqplot-highlighter-tooltipHighlighter tooltip.div.jqplot-table-legend-swatchColors swatch of the legend.Additionally style and styleClass options of charts apply to the container element of charts, use these attribute to specify the dimensions of a chart. In case youd like to change the colors of series, use the seriesColors options. 84 85. PrimeFaces Users Guide3.12.9 Ajax Behavior Events itemSelect is one and only ajax behavior event of charts, this event is triggered when a series of a chart is clicked. In case you have a listener defined, itll be executed by passing an org.primefaces.event.ItemSelectEvent instance. Example above demonstrates how to display a message about selected series in chart. public class Bean implements Serializable { //Data creation omitted public }void itemSelect(ItemSelectEvent event) { FacesMessage msg = new FacesMessage(); msg.setSummary("Item Index: " + event.getItemIndex()); msg.setDetail("Series Index:" + event.getSeriesIndex()); FacesContext.getCurrentInstance().addMessage(null, msg);}85 86. PrimeFaces Users Guide3.12.10 Charting Tips jqPlot Charts components use jqPlot as the underlying charting engine which uses a canvas element under the hood with support for IE. Extender Charts provide high level access to commonly used jqplot options however there are many more customization options available in jqplot. Extender feature provide access to low level apis to do advanced customization by enhancing this.cfg object, here is an example to increase shadow depth of the line series; function ext() { //this = chart widget instance //this.cfg = options this.cfg.seriesDefaults = { shadowDepth: 5 }; }Refer to jqPlot docs for the documentation of available options; http://www.jqplot.com/docs/files/jqPlotOptions-txt.htmlConverter Support Charts support converters for category display, an example case would be java.util.Date objects for categories, in case youd like charts to do the date formatting, bind a converter. jFreeChart If you like to use static image charts instead of canvas based charts, see the JFreeChart integration example at graphicImage section. Note that static images charts are not rich as PrimeFaces chart components and you need to know about jFreeChart apis to create the charts.86 87. PrimeFaces Users Guide3.13 Clock Clock displays server or client datetime live.Info TagclockComponent Classorg.primefaces.component.clock.ClockComponent Typeorg.primefaces.component.ClockComponent Familyorg.primefaces.componentRenderer Typeorg.primefaces.component.ClockRendererRenderer Classorg.primefaces.component.clock.ClockRendererAttributes NameDefaultTypeDescriptionidnullStringUnique identifier of the component.renderedTRUEBooleanBoolean value to specify the rendering of the component, when set to false component will not be rendered.bindingnullObjectAn el expression that maps to a server side UIComponent instance in a backing bean.patternnullStringDatetime format.modeclientStringMode value, valid values are client and server.autoSyncFALSEBooleanSyncs time periodically in server mode.syncInterval60000IntegerDefines the sync in ms interval in autoSync setting.Getting Started with Clock Clock has two modes, client (default) and server. In simples mode, datetime is displayed by just adding component on page. On page load, clock is initialized and start running based on client time.87 88. PrimeFaces Users Guide Server Mode In server mode, clock initialized itself with the servers datetime and starts running on client side. To make sure client clock and server clock is synced, you can enable autoSync option that makes an ajax call to the server periodically to refresh the server time with client. DateTime Format Datetime format used can be changed using pattern attribute. Skinning Clock resides in a container element which style and styleClass options apply. Following is the list of structural style classes; Style Class .ui-clockApplies Container element.88 89. PrimeFaces Users Guide3.14 Collector Collector is a simple utility to manage collections declaratively. Info TagcollectorActionListener Classorg.primefaces.component.collector.CollectorAttributes NameDefaultTypeDescriptionvaluenullObjectValue to be used in collection operationaddTonulljava.util.CollectionReference to the Collection instanceremoveFromnulljava.util.CollectionReference to the Collection instanceGetting started with Collector Collector requires a collection and a value to work with. Its important to override equals and hashCode methods of the value object to make collector work. public class BookBean { private Book book = new Book(); private List books; public CreateBookBean() { books = new ArrayList(); } public String createNew() { book = new Book(); //reset form return null; } }//getters and setters

89 90. PrimeFaces Users Guide3.15 Color Picker ColorPicker is an input component with a color palette.Info TagcolorPickerComponent Classorg.primefaces.component.colorpicker.ColorPickerComponent Typeorg.primefaces.component.ColorPickerComponent Familyorg.primefaces.componentRenderer Typeorg.primefaces.component.ColorPickerRendererRenderer Classorg.primefaces.component.colorpicker.ColorPickerRendererAttributes NameDefaultTypeDescriptionidnullStringUnique identifier of the componentrenderedTRUEBooleanBoolean value to specify the rendering of the component, when set to false component will not be rendered.bindingnullObjectAn el expression that maps to a server side UIComponent instance in a backing beanvaluenullObjectValue of the component.converternullConverter/ StringAn 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 idimmediateFALSEBooleanWhen set true, process validations logic is executed at apply request values phase for this component.requiredFALSEBooleanMarks component as required. 90 91. PrimeFaces Users GuideNameDefaultTypeDescriptionvalidatornullMethodExprA method expression that refers to a method for validation the input.valueChangeListenernullValueChange ListenerA method binding expression that refers to a method for handling a valuchangeevent.requiredMessagenullStringMessage to be displayed when required field validation fails.converterMessagenullStringMessage to be displayed when conversion fails.validatorMessagenullStringMessage to be displayed when validation fields.widgetVarnullStringName of the client side widget.modepopupStringDisplay mode, valid values are popup and inline.stylenullStringInline style of the component.styleClassnullStringStyle class of the component.Getting started with ColorPicker ColorPickers value should be a hex string. public class Bean { private String color; public String getColor() { return this.color; } }public void setColor(String color) { this.color = color; }Display Mode ColorPicker has two modes, default mode is popup and other available option is inline. 91 92. PrimeFaces Users GuideSkinning ColorPicker resides in a container element which style and styleClass options apply. Following is the list of structural style classes; Style ClassApplies.ui-colorpickerContainer element..ui-colorpicker_colorBackground of gradient..ui-colorpicker_hueHue element..ui-colorpicker_new_colorNew color display..ui-colorpicker_current_colorCurrent color display..ui-colorpicker-rgb-rRed input..ui-colorpicker-rgb-gGreed input..ui-colorpicker-rgb-bBlue input..ui-colorpicker-rgb-hHue input..ui-colorpicker-rgb-sSaturation input..ui-colorpicker-rgb-bBrightness input..ui-colorpicker-rgb-hexHex input.92 93. PrimeFaces Users Guide3.16 Column Column is an extended version of the standard column used by various PrimeFaces components like datatable, treetable and more. Info TagcolumnComponent Classorg.primefaces.component.column.ColumnComponent Typeorg.primefaces.component.ColumnComponent Familyorg.primefaces.componentAttributes NameDefaultTypeDescriptionidnullStringUnique identifier of the componentrenderedTRUEBooleanBoolean value to specify the rendering of the component, when set to false component will not be rendered.bindingnullObjectAn el expression that maps to a server side UIComponent instance in a backing beanstylenullStringInline style of the column.styleClassnullStringStyle class of the column.sortBynullValueExprProperty to be used for sorting.sortFunctionnullMethodExprCustom pluggable sortFunction.filterBynullValueExprProperty to be used for filtering.filterStylenullStringInline style of the filter elementfilterStyleClassnullStringStyle class of the filter elementfilterOptionsnullObjectA collection of selectitems for filter dropdown.filterMatchModestartsWithStringMatch mode for filtering.rowspan1IntegerDefines the number of rows the column spans.colspan1IntegerDefines the number of columns the column spans.headerTextnullStringShortcut for header facet.footerTextnullStringShortcut for footer facet.selectionModenullStringEnables selection mode. 93 94. PrimeFaces Users GuideNameDefaultTypeDescriptiondisabledSelectionFALSEBooleanDisables row selection.filterMaxLengthnullIntegerMaximum number of characters for an input filter.resizableTRUEBooleanSpecifies resizable feature at column level. Datatable's resizableColumns must be enabled to use this option.widthnullStringWidth in pixels or percentage.exportableTRUEBooleanDefines if the column should be exported by dataexporter.filterValuenullStringValue of the filter field.Note As column is a reused component, not all attributes of column are implemented by the components that use column, for example filterBy is only used by datatable whereas sortBy is used by datatable and sheet. Getting Started with Column As column is a reused component, see documentation of components that use a column.94 95. PrimeFaces Users Guide3.17 Columns Columns is used by datatable to create columns programmatically. Info TagcolumnsComponent Classorg.primefaces.component.column.ColumnsComponent Typeorg.primefaces.component.ColumnsComponent Familyorg.primefaces.componentAttributes NameDefaultTypeDescriptionidnullStringUnique identifier of the componentrenderedTRUEBooleanBoolean value to specify the rendering of the component, when set to false component will not be rendered.bindingnullObjectAn el expression that maps to a server side UIComponent instance in a backing beanvaluenullObjectData to represent columns.varnullStringName of iterator to access a column.stylenullStringInline style of the column.styleClassnullStringStyle class of the column.sortBynullValueExprProperty to be used for sorting.sortFunctionnullMethodExprCustom pluggable sortFunction.filterBynullValueExprProperty to be used for filtering.filterStylenullStringInline style of the filter elementfilterStyleClassnullStringStyle class of the filter elementfilterOptionsnullObjectA collection of selectitems for filter dropdown.filterMatchModestartsWithStringMatch mode for filtering.rowspan1IntegerDefines the number of rows the column spans.colspan1IntegerDefines the number of columns the column spans.headerTextnullStringShortcut for header facet.footerTextnullStringShortcut for footer facet. 95 96. PrimeFaces Users GuideNameDefaultTypeDescriptionfilterMaxLengthnullIntegerMaximum number of characters for an input filter.resizableTRUEBooleanSpecifies resizable feature at column level. Datatable's resizableColumns must be enabled to use this option.widthnullStringWidth in pixels or percentage.exportableTRUEBooleanDefines if the column should be exported by dataexporter.columnIndexVarnullStringName of iterator to refer each index.Getting Started with Columns See dynamic columns section in datatable documentation for detailed information.96 97. PrimeFaces Users Guide3.18 ColumnGroup ColumnGroup is used by datatable for column grouping. Info TagcolumnGroupComponent Classorg.primefaces.component.columngroup.ColumnGroupComponent Typeorg.primefaces.component. ColumnGroupComponent Familyorg.primefaces.componentAttributes NameDefaultTypeDescriptionidnullStringUnique identifier of the componentrenderedTRUEBooleanBoolean value to specify the rendering of the component, when set to false component will not be rendered.bindingnullObjectAn el expression that maps to a server side UIComponent instance in a backing beantypenullStringType of group, valid values are header and footer.Getting Started with ColumnGroup See grouping section in datatable documentation for detailed information.97 98. PrimeFaces Users Guide3.19 CommandButton CommandButton is an extended version of standard commandButton with ajax and theming.Info TagcommandButtonComponent Classorg.primefaces.component.commandbutton.CommandButtonComponent Typeorg.primefaces.component.CommandButtonComponent Familyorg.primefaces.componentRenderer Typeorg.primefaces.component.CommandButtonRendererRenderer Classorg.primefaces.component.commandbutton.CommandButtonRendererAttributes NameDefaultTypeDescriptionidnullStringUnique identifier of the componentrenderedTRUEBooleanBoolean value to specify the rendering of the component, when set to false component will not be rendered.bindingnullObjectAn el expression that maps to a server side UIComponent instance in a backing beanvaluenullStringLabel for the buttonactionnullMethodExpr/ StringA method expression or a String outcome thatd be processed when button is clicked.actionListenernullMethodExprAn actionlistener thatd be processed when button is clicked.immediateFALSEBooleanBoolean value that determines the phaseId, when true actions are processed at apply_request_values, when false at invoke_application phase.typesubmitStringSets the behavior of the button.ajaxTRUEBooleanSpecifies the submit mode, when set to true(default), submit would be made with Ajax.asyncFALSEBooleanWhen set to true, ajax requests are not queued.processnullStringComponent(s) to process partially instead of whole view.updatenullStringComponent(s) to be updated with ajax. 98 99. PrimeFaces Users GuideNameDefaultTypeDescriptiononstartnullStringClient side callback to execute before ajax request is begins.oncompletenullStringClient side callback to execute when ajax request is completed.onsuccessnullStringClient side callback to execute when ajax request succeeds.onerrornullStringClient side callback to execute when ajax request fails.globalTRUEBooleanDefines whether to trigger ajaxStatus or not.partialSubmitFALSEBooleanEnables serialization of values belonging to the partially processed components only.stylenullStringInline style of the button element.styleClassnullStringStyleClass of the button element.onblurnullStringClient side callback to execute when button loses focus.onchangenullStringClient side callback to execute when button loses focus and its value has been modified since gaining focus.onclicknullStringClient side callback to execute when button is clicked.ondblclicknullStringClient side callback to execute when button is double clicked.onfocusnullStringClient side callback to execute when button receives focus.onkeydownnullStringClient side callback to execute when a key is pressed down over button.onkeypressnullStringClient side callback to execute when a key is pressed and released over button.onkeyupnullStringClient side callback to execute when a key is released over button.onmousedownnullStringClient side callback to execute when a pointer button is pressed down over button.onmousemovenullStringClient side callback to execute when a pointer button is moved within button.onmouseoutnullStringClient side callback to execute when a pointer button is moved away from button.onmouseovernullStringClient side callback to execute when a pointer button is moved onto button.onmouseupnullStringClient side callback to execute when a pointer button is released over button.onselectnullStringClient side callback to execute when text within button is selected by user. 99 100. PrimeFaces Users GuideNameDefaultTypeDescriptionaccesskeynullStringAccess key that when pressed transfers focus to the button.altnullStringAlternate textual description of the button.dirnullStringDirection indication for text that does not inherit directionality. Valid values are LTR and RTL.disabledFALSEBooleanDisables the button.imagenullStringStyle class for the button icon. (deprecated: use icon)labelnullStringA localized user presentable name.langnullStringCode describing the language used in the generated markup for this component.tabindexnullIntegerPosition of the button element in the tabbing order.titlenullStringAdvisory tooltip information.readonlyFALSEBooleanFlag indicating that this component will prevent changes by the user.iconnullStringIcon of the button as a css class.iconPosleftStringPosition of the icon.inlineFALSEStringUsed by PrimeFaces mobile only.escapeTRUEBooleanDefines whether label would be escaped or not.widgetVarnullStringName of the client side widget.Getting started with CommandButton CommandButton usage is similar to standard commandButton, by default commandButton submits its enclosing form with ajax. public class BookBean {public void saveBook() { //Save book }}100 101. PrimeFaces Users GuideReset Buttons Reset buttons do not submit the form, just resets the form contents. Push Buttons Push buttons are used to execute custom javascript without causing an ajax/non-ajax request. To create a push button set type as "button". AJAX and Non-AJAX CommandButton has built-in ajax capabilities, ajax submit is enabled by default and configured using ajax attribute. When ajax attribute is set to false, form is submitted with a regular full page refresh. The update attribute is used to partially update other component(s) after the ajax response is received. Update attribute takes a comma or white-space separated list of JSF component ids to be updated. Basically any JSF component, not just PrimeFaces components should be updated with the Ajax response. In the following example, form is submitted with ajax and display outputText is updated with the ajax response. Tip: You can use the ajaxStatus component to notify users about the ajax request.Icons An icon on a button is provided using icon option. iconPos is used to define the position of the button which can be left or right. 101 102. PrimeFaces Users Guide.disk is a simple css class with a background property; .disk { background-image: url(disk.png) !important; }You can also use the pre-defined icons from ThemeRoller like ui-icon-search. Client Side API Widget: PrimeFaces.widget.CommandButton MethodParams