prime faces - user guide 3

USERS GUIDEAuthoraatay ivici

Covers 3.0.M4 Last Update: 14.11.11

PrimeFaces Users Guide

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

aatay ivici

2


About the Author! 1. Introduction!1.1 What is PrimeFaces?! 1.2 Prime Teknoloji!

10 1111 11

2. Setup!2.1 Download! 2.2 Dependencies! 2.3 Conguration! 2.4 Hello World!

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 Pie Chart! 3.11.2 Line Chart! 3.11.3 Bar Chart! 3.11.4 Donut Chart!3

1414 18 20 23 31 34 37 47 50 56 5757 60 63 66


3.11.5 Bubble Chart! 3.11.6 Ohlc Chart! 3.11.7 MeterGauge Chart! 3.11.8 Skinning Charts! 3.11.9 Ajax Behavior Events! 3.11.10 Charting Tips!

69 72 74 76 77 78

3.12 Collector! 3.13 Color Picker! 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 143143 147

3.28 Dock! 3.29 Editor!4

152 154


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. Partial Rendering and Processing!4.1 Partial Rendering!4.1.1 Infrastructure! 4.1.2 Using IDs! 4.1.3 Notifying Users! 4.1.4 Bits&Pieces!

396396396 396 399 399

4.2 Partial Processing!4.2.1 Partial Validation! 4.2.2 Keywords! 4.2.3 Using Ids!

400400 401 401

5. PrimeFaces Mobile! 6. PrimeFaces Push!6.1 Setup! 6.2 Push API! 6.3 Push Component! 6.4 Samples!6.4.1 Counter! 6.4.2 Chat!

402 403403 404 404 404404 405

7. Javascript API!8

407


7.1 PrimeFaces Namespace! 7.2 Ajax API!

407 408

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

410411 412 413 414

9. Utilities!9.1 RequestContext! 9.2 EL Functions!

415415 418

10. Portlets!10.1 Dependencies! 10.2 Conguration!

420420 421

11. Integration with Java EE! 12. IDE Support !12.1 NetBeans! 12.2 Eclipse!

424 425425 426

13. Project Resources! 14. FAQ!

427 428

9

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


1. Introduction1.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 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 Prime TeknolojiPrimeFaces is maintained by Prime Teknoloji, a Turkish software development company specialized in Agile and Java EE consulting. PrimeFaces Team members are full time engineers at Prime Teknoloji. aatay ivici - Architect and Lead Developer Levent Gnay - Core Developer / QA&Test Yiit Darn - Core Developer / QA&Test Mustafa Dagn - Core Developer / QA&Test 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, 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.html

Download with Maven Group id of the dependency is org.primefaces and artifact id is primefaces. org.primefaces primefaces 3.0.M4

In addition to the configuration above you also need to add Prime Technology 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 ConfigurationPrimeFaces does not require any mandatory configuration.

2.4 Hello WorldOnce 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 Component Type 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 FALSE TRUE null null FALSE 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.

Getting Started with Accordion Panel Accordion panel consists of one or more tabs and each tab can group any content. ...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. This 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.15

PrimeFaces Users Guide //..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 function handleChange(panel) { //panel: new tab content container }

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. Dynamic Number of 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

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.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 FALSE 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

FALSE null null null null null null TRUE FALSE null

Boolean String String String String String String Boolean Boolean String

Getting Started with AjaxBehavior 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 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.

19


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

InfoTag Component Class Component Type 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


Getting 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.

21


Custom 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.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 AutoCompleteAutoComplete provides live suggestions while an input is being typed.

InfoTag Component Class Component Type 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 FALSE

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

FALSE null null null null null null null null null null unlimited 1 300 FALSE null null TRUE null null 400 FALSE null

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 FALSE 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 FALSE 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.

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; public List complete(String query) { List results = new ArrayList(); for (int i = 0; i < 10; i++) results.add(query + i); return results; } //getter setter

Pojo 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.26


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 setter

Limiting the Results Number of results shown can be limited, by default there is no limit.

27


Minimum 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.

28


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.

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 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.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 Component Type 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 FALSE 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

Getting Started with BreadCrumb 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.

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


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

Durations are defined in milliseconds. Skinning Breadcrumb resides in a container element that style 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 ButtonButton is an extension to the standard h:button component with skinning capabilities.

InfoTag Component Class Component Type 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 FALSE null FALSE 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 FALSE null null

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

35


Getting 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 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 a button 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 Component Type 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 FALSE

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

FALSE null null null null null null null null int FALSE popup MM/dd/ yyyy null null FALSE FALSE null

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

FALSE FALSE

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 FALSE FALSE FALSE FALSE null FALSE 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 FALSE 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.

Getting Started with Calendar Value of the calendar should be a java.util.Date.

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

Display Modes 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 the pages 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 a Turkish 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

Ajax 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.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


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.

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 Side API 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 Recaptcha API.

InfoTag Component Class Component Type 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

FALSE

Boolean

required

FALSE

Boolean


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

Default null null null null null null red en null null FALSE

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

Getting 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_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.

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;Summary Detail primefaces.captcha.INVALID primefaces.captcha.INVALID_detail

Tips 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.

49


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

InfoTag Component Class Component Type 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 FALSE FALSE

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.

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 } CarListController() { cars = new ArrayList(); cars.add(new Car("myModel", 2005, "ManufacturerX", "blue")); //add more cars

//getter setter

51


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 easeOutStrong elasticBoth elasticIn elasticOut52

PrimeFaces Users GuideNote: Easing names are case sensitive and incorrect usage may result in javascript errors

SlideShow 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.

53


Item Selection When selecting an item from a carousel with a command component, p:column is necessary to process selection properly. Following example displays selected car contents within a dialog; //more

240


Output of this lightbox is;

IFrame Mode LightBox also has the ability to display iframes inside the page overlay, following lightbox displays the PrimeFaces homepage when the link inside is clicked.

242


3.54 LogLog component is a visual console to display logs on JSF pages.

InfoTag Component Class Component Type Component Family log org.primefaces.component.log.Log org.primefaces.component.Log org.primefaces.component

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

binding

null

Object

Getting started with Log Log component is used simply as adding the component to the page.

243


Log API PrimeFaces uses client side log apis internally, for example you can use log component to see details of an ajax request. Log API is also available via global PrimeFaces object in case youd like to use the log component to display your logs. PrimeFaces.info(Info message); PrimeFaces.debug(Debug message); PrimeFaces.warn(Warning message); PrimeFaces.error(Error message);

244


3.55 MediaMedia component is used for embedding multimedia content such as videos and music to JSF views. Media renders or html tags depending on the user client. InfoTag Component Class Component Type Component Family Renderer Type Renderer Class media org.primefaces.component.media.Media org.primefaces.component.Media org.primefaces.component org.primefaces.component.MediaRenderer org.primefaces.component.media.MediaRenderer

AttributesName id rendered Default null TRUE String Boolean Type Description Unique identifier of the component. Boolean value to specify the rendering of the component, when set to false component will not be rendered. An el expression that maps to a server side UIComponent instance in a backing bean. Media source to play. Type of the player, possible values are "quicktime","windows","flash","real". Width of the player. Height of the player. Style of the player. StyleClass of the player.

binding value player width height style styleClass

null null null null null null null

Object String String String String String String

Getting started with Media In its simplest form media component requires a source to play, this is defined using the value attribute.

245


Player Types By default, players are identified using the value extension so for instance mov files will be played by quicktime player. You can customize which player to use with the player attribute.

Following is the supported players and file types.Player windows quicktime flash real asx, asf, avi, wma, wmv aif, aiff, aac, au, bmp, gsm, mov, mid, midi, mpg, mpeg, mp4, m4a, psd, qt, qtif, qif, qti, snd, tif, tiff, wav, 3g2, 3pg flv, mp3, swf ra, ram, rm, rpm, rv, smi, smil Types

Parameters Different proprietary players might have different configuration parameters, these can be specified using f:param tags.

StreamedContent Support Media component can also play binary media content, example for this use case is storing media files in datatabase using binary format. In order to implement this, bind a StreamedContent.

public class MediaBean { private StreamedContent media; public MediaController() { InputStream stream = //Create binary stream from database media = new DefaultStreamedContent(stream, "video/quicktime"); } public StreamedContent getMedia() { return media; } }

246


3.56 MenuMenu is a navigation component with various customized modes like multi tiers, ipod style sliding and overlays.

InfoTag Component Class Component Type Component Family Renderer Type Renderer Class menu org.primefaces.component.menu.Menu org.primefaces.component.Menu org.primefaces.component org.primefaces.component.MenuRenderer org.primefaces.component.menu.MenuRenderer

AttributesName id rendered binding widgetVar model trigger my Default null TRUE null null null null null Type String Boolean Object String MenuModel String String Description Unique identifier of the component. Boolean value to specify the rendering of the component, when set to false component will not be rendered. An el expression that maps to a server side UIComponent instance in a backing bean. Name of the client side widget. A menu model instance to create menu programmatically. Id of component whose click event will show the dynamic positioned menu. Corner of menu to align with trigger element.247


Name at position type style styleClass backLabel triggerEvent easing

Default null static plain null null Back click null

Type String String String String String String String String

Description Corner of trigger to align with menu element. Defines positioning type of menu, either static or dynamic. Type of menu, valid values are plain, tiered and sliding. Inline style of the main container element. Style class of the main container element. Text for back link, only applies to sliding menus. Event to show the dynamic positioned menu. Easing type.

Getting started with the Menu A menu is composed of submenus and menuitems.

248


Submenus are used to group menuitems;

Overlay Menu Menu can be positioned on a page in two ways; "static" and "dynamic". By default its static meaning the menu is in normal page flow. In contrast dynamic menus is not on the normal flow of the page allowing them to overlay other elements. A dynamic menu is created by setting position option to dynamic and defining a trigger to show the menu. Location of menu on page will be relative to the trigger and defined by my and at options that take combination of four values; left right bottom top249


For example, clicking the button below will display the menu whose top left corner is aligned with bottom left corner of button. ...submenus and menuitems

Menu Types Menu has three different types, plain, tiered and sliding. ...submenus and menuitems

Plain

Tiered

Sliding (iPod)

Ajax and Non-Ajax Actions As menu uses menuitems, it is easy to invoke actions with or without ajax as well as navigation. See menuitem documentation for more information about the capabilities.

250


Dynamic Menus Menus can be created programmatically as well, this is more flexible compared to the declarative approach. Menu metadata is defined using an org.primefaces.model.MenuModel instance, PrimeFaces provides the built-in org.primefaces.model.DefaultMenuModel implementation. For further customization you can also create and bind your own MenuModel implementation.

public class MenuBean { } private MenuModel model; public } MenuBean() { model = new DefaultMenuModel(); //First submenu Submenu submenu = new Submenu(); submenu.setLabel("Dynamic Submenu 1"); MenuItem item = new MenuItem(); item.setValue("Dynamic Menuitem 1.1"); item.setUrl("#"); submenu.getChildren().add(item); model.addSubmenu(submenu); //Second submenu submenu = new Submenu(); submenu.setLabel("Dynamic Submenu 2"); item = new MenuItem(); item.setValue("Dynamic Menuitem 2.1"); item.setUrl("#"); submenu.getChildren().add(item); item = new MenuItem(); item.setValue("Dynamic Menuitem 2.2"); item.setUrl("#"); submenu.getChildren().add(item); model.addSubmenu(submenu);

public MenuModel getModel() { return model; }

Skinning Menu resides in a main container element which style and styleClass attributes apply. Following is the list of structural style classes;251


Style Class .ui-menu .ui-menu-list .ui-menuitem .ui-menuitem-link .ui-menuitem-text .ui-menu-sliding Container element of menu List container Each menu item

Applies

Anchor element in a link item Text element in an item Container of ipod like sliding menu


252


3.57 MenubarMenubar is a horizontal navigation component.

InfoTag Component Class Component Type Component Family Renderer Type Renderer Class menubar org.primefaces.component.menubar.Menubar org.primefaces.component.Menubar org.primefaces.component org.primefaces.component.MenubarRenderer org.primefaces.component.menubar.MenubarRenderer

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. Name of the client side widget MenuModel instance to create menus programmatically Inline style of menubar Style class of menubar

binding widgetVar model style styleClass

null null null null null

Object String MenuModel String String

Getting started with Menubar Submenus and menuitems as child components are required to compose the menubar.

253


Nested Menus To create a menubar with a higher depth, nest submenus in parent submenus.

Root Menuitem Menubar supports menuitem as root menu options as well; Following example allows a root menubar item to execute an action to logout the user. //submenus

254


Ajax and Non-Ajax Actions As menu uses menuitems, it is easy to invoke actions with or without ajax as well as navigation. See menuitem documentation for more information about the capabilities.

Dynamic Menus Menus can be created programmatically as well, see the dynamic menus part in menu component section for more information and an example. Skinning Menubar resides in a main container which style and styleClass attributes apply. Following is the list of structural style classes;Style Class .ui-menubar .ui-menu-list .ui-menuitem .ui-menuitem-link .ui-menuitem-text Applies Container element of menubar. List container Each menu item Anchor element in a link item Text element in an item


255


3.58 MenuButtonMenuButton displays different commands in a popup menu.

InfoTag Component Class Component Type Component Family Renderer Type Renderer Class menuButton org.primefaces.component.menubutton.MenuButton org.primefaces.component.MenuButton org.primefaces.component org.primefaces.component.MenuButtonRenderer org.primefaces.component.menubutton.MenuButtonRenderer

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. Label of the button Style of the main container element Style class of the main container element Name of the client side widget MenuModel instance to create menus programmatically Disables or enables the button.

binding value style styleClass widgetVar model disabled

null null null null null null FALSE

Object String String String String MenuModel Boolean

256


Getting started with the MenuButton MenuButton consists of one ore more menuitems. Following menubutton example has three menuitems, first one is used triggers an action with ajax, second one does the similar but without ajax and third one is used for redirect purposes.

Dynamic Menus Menus can be created programmatically as well, see the dynamic menus part in menu component section for more information and an example. Skinning MenuButton resides in a main container which style and styleClass attributes apply. As skinning style classes are global, see the main Skinning section for more information. Following is the list of structural style classes;Style Class .ui-menu .ui-menu-list .ui-menuitem .ui-menuitem-link .ui-menuitem-text .ui-button .ui-button-text Applies Container element of menu. List container Each menu item Anchor element in a link item Text element in an item Button element Label of button

257


3.59 MenuItemMenuItem is used by various menu components of PrimeFaces. InfoTag Tag Class Component Class Component Type Component Family menuItem org.primefaces.component.menuitem.MenuItemTag org.primefaces.component.menuitem.MenuItem org.primefaces.component.MenuItem org.primefaces.component

AttributesName id rendered Default null TRUE String Boolean Type Description Unique identifier of the component. Boolean value to specify the rendering of the component, when set to false component will not be rendered. An el expression that maps to a server side UIComponent instance in a backing bean. Label of the menuitem Action listener to be invoked when menuitem is clicked. Action to be invoked when menuitem is clicked. When true, action of this menuitem is processed after apply request phase. Url to be navigated when menuitem is clicked Target type of url navigation Style of the menuitem label StyleClass of the menuitem label Javascript event handler for click event When set to true, ajax requests are not queued. Component id(s) to process partially instead of whole view.

binding value actionListener action immediate url target style styleClass onclick async process

null null null null FALSE null null null null null FALSE null

Object String javax.el.MethodE xpression javax.el.MethodE xpression Boolean String String String String String Boolean String

258


Name update disabled onstart oncomplete onsuccess onerror global

Default null FALSE null null null null TRUE String

Type

Description Client side id of the component(s) to be updated after async partial submit request. Disables the menuitem. Javascript handler to execute before ajax request is begins. Javascript handler to execute when ajax request is completed. Javascript handler to execute when ajax request succeeds. Javascript handler to execute when ajax request fails. Global ajax requests are listened by ajaxStatus component, setting global to false will not trigger ajaxStatus. Specifies submit mode. Path of the menuitem image.

Boolean String String String String Boolean

ajax icon

TRUE null

Boolean String

Getting started with MenuItem MenuItem is a generic component used by the following PrimeFaces components. Menu MenuBar Breadcrumb Dock Stack MenuButton

Note that some attributes of menuitem might not be supported by these menu components. Refer to the specific component documentation for more information. Navigation vs Action Menuitem has two use cases, directly navigating to a url with GET and doing a POST do execute an action which you can still do navigation with JSF navigation rules. This is decided by url attribute, if it is present menuitem does a GET request, if not parent form is posted. Icons There are two ways to specify an icon of a menuitem, you can either use bundled icons within PrimeFaces or provide your own via css.

259


ThemeRoller Icons

Custom Icons

.barca { background: url(barca_logo.png) no-repeat; height:16px; width:16px; }

260


3.60 MessageMessage is a pre-skinned extended version of the standard JSF message component.

InfoTag Component Class Component Type Component Family Renderer Type Renderer Class message org.primefaces.component.message.Message org.primefaces.component.Message org.primefaces.component org.primefaces.component.MessageRenderer org.primefaces.component.message.MessageRenderer

AttributesName id rendered binding showSummary showDetail for redisplay display Default null TRUE null FALSE TRUE null TRUE both Type String Boolean Object Boolean Boolean String Boolean String Description Unique identifier of the component. Boolean value to specify the rendering of the component, when set to false component will not be rendered. An el expression that maps to a server side UIComponent instance in a backing bean. Specifies if the summary of the FacesMessage should be displayed. Specifies if the detail of the FacesMessage should be displayed. Id of the component whose messages to display. Defines if already rendered messages should be displayed Defines the display mode.

Getting started with Message Message usage is exactly same as standard message.

261


Display Mode Message component has three different display modes; text : Only message text is displayed. icon : Only message severity is displayed and message text is visible as a tooltip. both (default) : Both icon and text are displayed. Skinning Message Full list of CSS selectors of message is as follows; Style Class ui-message-{severity} ui-message-{severity}-summary ui-message-{severity}-info Applies Container element of the message Summary text Detail text

{severity} can be info, error, warn and error.

262


3.61 MessagesMessages is a pre-skinned extended version of the standard JSF messages component.

InfoTag Component Class Component Type Component Family Renderer Type Renderer Class messages org.primefaces.component.messages.Messages org.primefaces.component.Messages org.primefaces.component org.primefaces.component.MessagesRenderer org.primefaces.component.messages.MessagesRenderer

AttributesName id rendered Default null TRUE String Boolean Type Description Unique identifier of the component. Boolean value to specify the rendering of the component, when set to false component will not be rendered. An el expression that maps to a server side UIComponent instance in a backing bean. Specifies if the summary of the FacesMessages should be displayed. Specifies if the detail of the FacesMessages should be displayed. When true, only facesmessages with no clientIds are displayed.263

binding showSummary showDetail globalOnly

null FALSE TRUE FALSE

Object Boolean Boolean String


Name redisplay autoUpdate

Default TRUE FALSE

Type Boolean Boolean

Description Defines if already rendered messages should be displayed Enables auto update mode if set true.

Getting started with Messages Message usage is exactly same as standard messages.

AutoUpdate When auto update is enabled, messages component is updated with each ajax request automatically. Skinning Message Full list of CSS selectors of message is as follows;Style Class ui-messages-{severity} ui-messages-{severity}-summary ui-messages-{severity}-detail ui-messages-{severity}-icon Applies Container element of the message Summary text Detail text Icon of the message.

{severity} can be info, error, warn and error.

264


3.62 NotificationBarNotificationBar displays a multipurpose fixed positioned panel for notification. InfoTag Component Class Component Type Component Family Renderer Type Renderer Class notificationBar org.primefaces.component.notificationbar.NotificationBar org.primefaces.component.NotificatonBar org.primefaces.component org.primefaces.component.NotificationBarRenderer org.primefaces.component.notificationbar.NotificationBarRenderer

AttributesName id rendered Default null TRUE String Boolean Type Description Unique identifier of the component Boolean value to specify the rendering of the component, when set to false component will not be rendered. An el expression that maps to a server side UIComponent instance in a backing bean Style of the container element StyleClass of the container element Position of the bar, "top" or "bottom". Name of the effect, "fade", "slide" or "none". Speed of the effect, "slow", "normal" or "fast". When true, panel is displayed on page load.

binding style styleClass position effect effectSpeed autoDisplay

null null null top fade normal FALSE

Object String String String String String Boolean

Getting started with NotificationBar As notificationBar is a panel component, any content can be placed inside. //Content

265


Showing and Hiding To show and hide the content, notificationBar provides an easy to use client side api that can be accessed through the widgetVar. show() displays the bar and hide() hides it. //Content Show Show

Note that notificationBar has a default built-in close icon to hide the content. Effects Default effect to be used when displaying and hiding the bar is "fade", another possible effect is "slide". //Content

If youd like to turn off animation, set effect name to "none". In addition duration of the animation is controlled via effectSpeed attribute that can take "normal", "slow" or "fast" as its value. Position Default position of bar is "top", other possibility is placing the bar at the bottom of the page. Note that bar positioning is fixed so even page is scrolled, bar will not scroll. //Content

Skinning style and styleClass attributes apply to the main container element. Additionally there are two predefined css selectors used to customize the look and feel.Selector .ui-notificationbar .ui-notificationbar-close Main container element Close icon element Applies

266


3.63 OrderListOrderList is used to sort a collection featuring drag&drop based reordering, transition effects and pojo support.

InfoTag Component Class Component Type Component Family Renderer Type Renderer Class orderList org.primefaces.component.orderlist.OrderList org.primefaces.component.OrderList org.primefaces.component org.primefaces.component.OrderListRenderer org.primefaces.component.orderlist.OrderListRenderer

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 referring to a List.

binding value

null null

Object Object

267


Name converter

Default null

Type Converter/String

Description An el expression or a literal text that defines a converter for the component. When its an EL expression, its resolved to a converter instance. In case its a static text, it must refer to a converter id When set true, process validations logic is executed at apply request values phase for this component. Marks component as required A method expression that refers to a method validationg the input A method expression that refers to a method for handling a valuechangeevent Message to be displayed when required field validation fails. Message to be displayed when conversion fails. Message to be displayed when validation fields. Name of the client side widget. Name of the iterator. Label of an item. Value of an item. Inline style of container element. Style class of container element. Disables the component. Name of animation to display. IconOnly mode renders reorder buttons without labels and just icons. Label of move up button. Label of move top button. Label of move down button. Label of move bottom button. Location of the reorder buttons, valid values are left, right and none.

immediate

FALSE

Boolean

required validator valueChangeListener requiredMessage converterMessage validatorMessage widgetVar var itemLabel itemValue style styleClass disabled effect iconOnly moveUpLabel moveTopLabel moveDownLabel moveBottomLabel controlsLocation

FALSE null null null null null null null null null null null FALSE fade FALSE Move Up Move Top Move Down Move Bottom left

Boolean MethodExpr MethodExpr String String String String String String String String String Boolean String Boolean String String String String String

268


Getting started with OrderList A list is required to use OrderList component.public class OrderListBean { private List cities; public OrderListBean() { cities = new ArrayList(); cities.add("Istanbul"); cities.add("Ankara"); cities.add("Izmir"); cities.add("Antalya"); cities.add("Bursa"); } } //getter&setter for cities

Item Selection A column is required to process item selection from ring properly. //UI to select an item e.g. commandLink

Easing Following is the list of available options for easing animation. swing easeInQuad easeOutQuad easeInOutQuad easeInCubic easeOutCubic easeInOutCubic easeInQuart easeOutQuart easeInOutQuart easeInQuint easeOutQuint easeInOutQuint easeInSine easeOutSine easeInExpo easeOutExpo easeInOutExpo easeInCirc easeOutCirc easeInOutCirc easeInElastic easeOutElastic easeInOutElastic easeInBack easeOutBack easeInOutBack easeInBounce easeOutBounce easeInOutBounce

305


Skinning Ring resides in a main container which style and styleClass attributes apply. Following is the list of structural style classes.Style Class .ui-ring .ui-ring-item Main container element. Each item in the list. Applies

306


3.76 RowRow is a helper component for datatable. InfoTag Component Class Component Type Component Family row org.primefaces.component.row.Row org.primefaces.component.Row org.primefaces.component


binding

null

Object

Getting Started with Row See datatable grouping section for more information about how row is used.

307


3.77 RowEditorRowEditor is a helper component for datatable. InfoTag Component Class Component Type Component Family Renderer Type Renderer Class rowEditor org.primefaces.component.roweditor.RowEditor org.primefaces.component.RowEditor org.primefaces.component org.primefaces.component.RowEditorRenderer org.primefaces.component.roweditor.RowEditorRenderer


binding

null

Object

Getting Started with RowEditor See inline editing section in datatable documentation for more information about usage.

308


3.78 RowExpansionRowExpansion is a helper component of datatable used to implement expandable rows. InfoTag Component Class Component Type Component Family rowExpansion org.primefaces.component.rowexpansion.RowExpansion org.primefaces.component.RowExpansion org.primefaces.component


binding

null

Object

Getting Started with RowExpansion See datatable expandable rows section for more information about how rowExpansion is used.

309


3.79 RowTogglerRowToggler is a helper component for datatable. InfoTag Component Class Component Type Component Family Renderer Type Renderer Class rowToggler org.primefaces.component.rowtoggler.RowToggler org.primefaces.component.RowToggler org.primefaces.component org.primefaces.component.RowTogglerRenderer org.primefaces.component.rowtoggler.RowTogglerRenderer


binding

null

Object

Getting Started with Row See expandable rows section in datatable documentation for more information about usage.

310


3.80 ScheduleSchedule provides an Outlook Calendar, iCal like JSF component to manage events.

InfoTag Component Class Component Type Component Family Renderer Type Renderer Class schedule org.primefaces.component.schedule.Schedule org.primefaces.component.Schedule org.primefaces org.primefaces.component.ScheduleRenderer org.primefaces.component.schedule.ScheduleRenderer

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 Name of the client side widget. An org.primefaces.model.ScheduleModel instance representing the backed model Locale for localization, can be String or a java.util.Locale instance

binding widgetVar value locale

null null null null

Object String Object Object

311


Name aspectRatio view

Default null month

Type Float String

Description Ratio of calendar width to height, higher the value shorter the height is The view type to use, possible values are 'month', 'agendaDay', 'agendaWeek', 'basicWeek', 'basicDay' The initial date that is used when schedule loads. If ommitted, the schedule starts on the current date Specifies inclusion Saturday/Sunday columns in any of the views Style of the main container element of schedule Style class of the main container element of schedule Defines whether calendar can be modified. When true, events are draggable. When true, events are resizable. Specifies visibility of header content. Content of left side of header. Content of center of header. Content of right side of header.

initialDate

null

Object

showWeekends style styleClass editable draggable resizable showHeader leftHeaderTemplate centerHeaderTemplate rightHeaderTemplate

TRUE null null FALSE FALSE FALSE TRUE prev, next today title month, agendaWeek, agendaDay TRUE 30 6 null null 0

Boolean String String Boolean Boolean Boolean Boolean String String String

allDaySlot slotMinutes firstHour minTime maxTime startWeekday

Boolean Integer Integer String String Integer

Determines if all-day slot will be displayed in agendaWeek or agendaDay views Interval in minutes in an hour to create a slot. First hour to display in day view. Minimum time to display in a day view. Maximum time to display in a day view. Specifies first day of week, by default it's 0 corresponding to sunday

Getting started with Schedule Schedule needs to be backed by an org.primefaces.model.ScheduleModel instance, a schedule model consists of org.primefaces.model.ScheduleEvent instances.312


public class ScheduleBean { } private ScheduleModel model; public ScheduleBean() { eventModel = new ScheduleModel(); eventModel.addEvent(new DefaultScheduleEvent("title", new Date(), new Date())); } public ScheduleModel getModel() { return model; }

DefaultScheduleEvent is the default implementation of ScheduleEvent interface. Mandatory properties required to create a new event are the title, start date and end date. Other properties such as allDay get sensible default values. Table below describes each property in detail.Property id title startDate endDate allDay styleClass data Description Used internally by PrimeFaces, you dont need to define it manually as id is autogenerated. Title of the event. Start date of type java.util.Date. End date of type java.util.Date. Flag indicating event is all day. Visual style class to enable multi resource display. Optional data you can set to be represented by Event.

Ajax Behavior Events Schedule provides various ajax behavior events to respond user actions.Event dateSelect eventSelect eventMove eventResize Listener Parameter org.primefaces.event.DateSelectEvent org.primefaces.event.ScheduleEntrySelectEvent org.primefaces.event.ScheduleEntryMoveEvent org.primefaces.event.ScheduleEntryResizeEvent Fired When a date is selected. When an event is selected. When an event is moved. When an event is resized.

313


Ajax Updates Schedule has a quite complex UI which is generated on-the-fly by the client side PrimeFaces.widget.Schedule widget to save bandwidth and increase page load performance. As a result when you try to update schedule like with a regular PrimeFacess PPR, you may notice a UI lag as the DOM will be regenerated and replaced. Instead, Schedule provides a simple client side api and the update method. Whenever you call update, schedule will query its server side ScheduleModel instance to check for updates, transport method used to load events dynamically is JSON, as a result this approach is much more effective then updating with regular PPR. An example of this is demonstrated at editable schedule example, save button is calling myschedule.update() at oncomplete event handler. Editable Schedule Lets put it altogether to come up a fully editable and complex schedule. Well use event and date event hooks and a dialog to create/update an event.

prime faces - user guide 3

Documents