java + ajax

5/28/2018 java + ajax

1/373

Authors

agatay iviciYigit Darn

Covers 1.0.1 and 2.0.1Last Update: 19.04.2010

5/28/2018 java + ajax

2/373

This page is intentionally left blank

Prime Technology - 2010

2

5/28/2018 java + ajax

3/373

1. Introduction 9What is PrimeFaces? 9

2. Setup 102.1 Download 102.2 Dependencies 112.3 Configuration 11

2.3.1 JSF 1.2 with PrimeFaces 1.x 112.3.2 JSF 2.0 with PrimeFaces 2.x 12

2.4 Hello World 133. Component Suite 14

3.1 AccordionPanel 143.2 AjaxStatus 183.3 AutoComplete 213.4 BreadCrumb 273.5 Captcha 303.6 Calendar 333.7 Carousel 413.8 Charts 47

3.8.1 Pie Chart 473.8.2 Line Chart 503.8.3 Column Chart 533.8.4 Stacked Column Chart 553.8.5 Bar Chart 573.8.6 StackedBar Chart 593.8.7 Chart Series 613.8.8 Skinning Charts 62


3

5/28/2018 java + ajax

4/373

3.8.9 Real-Time Charts 653.8.10 Interactive Charts 67

3.9 Collector 693.10 Color Picker 713.11 Column 753.12 CommandButton 763.13 CommandLink 813.14 ConfirmDialog 853.15 ContextMenu 873.16 Dashboard 903.17 DataExporter 953.18 DataTable 993.19 Dialog 1163.20 Drag&Drop

122

3.21 Dock 1263.22 Editor 1283.23 Effect 1323.24 FileDownload 1353.25 FileUpload 1373.26 Focus 1433.27 GraphicImage 1453.28 GraphicText 1503.29 Growl 1523.30 HotKey 1553.31 IdleMonitor 158


4

5/28/2018 java + ajax

5/373

3.32 ImageCompare 1613.33 ImageCropper 1633.34 ImageSwitch 1673.35 Inplace 1703.36 InputMask 1723.37 Keyboard 1753.38 Layout 1833.39 LayoutUnit 1903.40 LightBox 1923.41 LinkButton 1973.42 Media 1993.43 Menu 2023.44 Menubar 2073.45 MenuButton 2113.46 MenuItem 2133.47 Message 2153.48 Messages 2173.49 NotificationBar 2193.50 OutputPanel 2223.51 Panel 2243.52 Password Strength 2313.53 PickList 2363.54 Poll 2413.55 Printer

244

3.56 ProgressBar 246


5

5/28/2018 java + ajax

6/373

3.57 Push 2513.58 Rating 2523.59 RemoteCommand 2553.60 Resizable 2573.61 Resource 2603.62 Resources 2613.63 Schedule 2633.64 ScheduleEventDialog 2783.65 Slider 2803.66 Spinner 2833.67 Submenu 2873.68 Stack 2883.69 TabSlider 2903.70 TabView 2923.71 Terminal 2973.72 Tooltip 3003.73 Tree 3043.74 TreeNode 3183.75 UIAjax 3193.76 Watermark 3223.77 Wizard 324

4. TouchFaces 3304.1 Getting Started with TouchFaces 3304.2 Views 3324.3 Navigations 335


6

5/28/2018 java + ajax

7/373

4.4 Ajax Integration 3374.5 Sample Applications 3384.6 TouchFaces Components 339

4.6.1 Application 3394.6.2 NavBarControl 3404.6.3 RowGroup 3414.6.4 RowItem 3424.6.5 Switch 3434.6.6 TableView 3454.6.7 View 346

5. Partial Rendering and Processing 3475.1 Partial Rendering 347

5.1.1 Infrastructure 3475.1.2 Using IDs 3475.1.3 Notifying Users 3505.1.4 Bits&Pieces 350

5.2 Partial Processing 3505.2.1 Partial Validation 3505.2.2 Keywords 3515.2.3 Using Ids 3525.2.4 Ajax vs Non-Ajax 352

6. Ajax Push/Comet 3536.1 Atmosphere 3536.2 PrimeFaces Push 354

6.2.1 Setup 3546.2.2. CometContext 3556.2.3 Push Component 355


7

5/28/2018 java + ajax

8/373

7. Javascript 3577.1 PrimeFaces Global Object 3577.2 Namespaces 3577.3 Ajax API 358

8. Utilities 3618.1 RequestContext 3618.2 EL Functions 363

Page Authorization 3639. Integration with Java EE 36510. IDE Support 366

10.1 NetBeans 36610.2 Eclipse 366

11. Portlets 36912. Project Resources 37113. FAQ 372


8

5/28/2018 java + ajax

9/373

1. Introduction

What is PrimeFaces?

PrimeFaces is an open source component suite for Java Server Faces featuring 70+ Ajaxpowered rich set of JSF components. Additional TouchFaces module features a UI kit fordeveloping mobile web applications. Main goal of PrimeFaces is to create the ultimatecomponent suite for JSF.

Rich set of components (HtmlEditor, Dialog, AutoComplete, Charts and more).

Built-in Ajax with Lightweight Partial Page Rendering.

Native Ajax Push/Comet support.

Mobile UI kit to create mobile web applications for handheld devices with webkit basedbrowsers.(IPhone, Palm, Android Phones, Nokia S60 and more)

Compatible with other component libraries.

Unobstrusive javascript. Extensive documentation.

Prime Technology

PrimeFaces is maintained by Prime Technology, a Turkish software development companyspecialized in Agile consulting, Enterprise Java and outsource software development.Project is led by a!atay ivici, a JSF Expert Group Member.

5/28/2018 java + ajax

10/373

2. Setup

2.1 Download

PrimeFaces has a single jar called primefaces-{version}.jar. There are two ways todownload this jar, you can either download from PrimeFaces homepage or if you are amaven user you can define it as a dependency.

Download manually

Download with Maven

Group id of the dependency is org.primefacesand artifact id is primefaces.

In addition to the configuration above you also need to add Prime Technology mavenrepository to the repository list so that maven can download it.


10
http://repository.prime.com.tr/http://repository.prime.com.tr/http://repository.prime.com.tr/http://www.primefaces.org/downloads.htmlhttp://www.primefaces.org/downloads.html

5/28/2018 java + ajax

11/373

2.2 Dependencies

PrimeFaces only requires a JAVA 5+ runtime and a JSF 1.2+ implementation asmandatory dependencies. Other than these required dependencies, there"re someoptional libraries for certain features.

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

2.3 Configuration

2.3.1 JSF 1.2 with PrimeFaces 1.x

Resource Servlet

Resource Servlet must be configured in web.xml.


11
http://web.xml/http://web.xml/

5/28/2018 java + ajax

12/373

Resources Component

Resource component needs to be present on a page that has PrimeFaces components,this component outputs the link and script tags that are necessary for PrimeFacescomponents to work. The ideal place to put resources component would be the html headelement.

We could have wrapped the output response with a servlet filter, parse the html, insert thelink and script tags to the head element but this would be an expensive operation andeffect the applications performance badly.

A tip regarding p:resources is to add this component to the facelets or jsp template once,so that it gets added to each page automatically using the application.

2.3.2 JSF 2.0 with PrimeFaces 2.x

Resource Servlet

Although PrimeFaces 2.x uses JSF2 resource APIs to place resources on page, due tolimitations of JSF2 resource loading mechanism, PrimeFaces Resource Servlet is requiredto stream the resources from the bundle. If you"re running PrimeFaces in a Servlet 3.0

environment like Glassfish V3, this servlet is auto-registered so you don"t need toconfigure it manually.

Allowing Text Children

When using Mojarra 2.x, enable allowTextChildren configuration.


12

5/28/2018 java + ajax

13/373

2.4 Hello World

That is all for configuration, now define the taglib to import PrimeFaces in your pages andtry a component to test if setup is working.

Taglib

If you're a facelets user, the xml namespace configuration would be;

If you're using jsp the taglib definition is;

Try a component

For JSF 1.2 and PrimeFaces 1.x an example page would be;

And with JSF 2.0 and PrimeFaces 2.x. (Note that you don"t need p:resources but needh:head in this case);


13
http://primefaces.prime.com.tr/uihttp://primefaces.prime.com.tr/uihttp://java.sun.com/jsf/htmlhttp://java.sun.com/jsf/htmlhttp://java.sun.com/jsf/corehttp://java.sun.com/jsf/corehttp://www.w3c.org/1999/xhtmlhttp://www.w3c.org/1999/xhtmlhttp://primefaces.prime.com.tr/uihttp://primefaces.prime.com.tr/uihttp://java.sun.com/jsf/htmlhttp://java.sun.com/jsf/htmlhttp://java.sun.com/jsf/corehttp://java.sun.com/jsf/corehttp://www.w3c.org/1999/xhtmlhttp://www.w3c.org/1999/xhtmlhttp://primefaces.prime.com.tr/uihttp://primefaces.prime.com.tr/uihttp://primefaces.prime.com.tr/uihttp://primefaces.prime.com.tr/ui

5/28/2018 java + ajax

14/373

3. Component Suite

3.1 AccordionPanel

AccordionPanel is a container component that renders it"s children in seperate tabs anddisplays a sliding animation when a tab is being collapsed or expanded.

Info


14

5/28/2018 java + ajax

15/373

Attributes

Getting started with Accordion Panel

Accordion panel consists of one or more tabs and each tab can group any other jsfcomponents.


15

5/28/2018 java + ajax

16/373

Multiple Selection

By default, only one tab can be active, this behavior can be configured to multipleselection to activate more than one tab.

Animation Speed

Toggling of the tabs are animated and animation speed can be configured via the speedattribute, speed is considered in milliseconds and defaults to 0.5 seconds. Following

accordion will slide slower than default.

Hovering

Toggling happens when a tab header is clicked, if you need panels to be toggled on hoverenable hover setting. Also hoverDelay specifies the delay of toggle on hover. FollowingaccordionPanel would wait for 200 ms to toggle on hover.

Skinning

AccordionPanel resides in a main div container, style and styleClass apply to this mainelement. Use these two attributes to set common properties like width, margin etc. Insidethe main container accordion is represented as an unordered list() and each tab islocated inside a element.

Following is the list of skinning selectors;


16

5/28/2018 java + ajax

17/373

Here"s an example of how to skin an accordionPanel using these css selectors.

With these values accordionPanel will look like;


17

5/28/2018 java + ajax

18/373

3.2 AjaxStatus

AjaxStatus is a global notifier to ajax requests made by PrimeFaces Partial PageRendering components like button, poll, uiajax.

Info

Attributes


18

5/28/2018 java + ajax

19/373

Getting started with AjaxStatus

AjaxStatus uses facets to represent the ajax request status. Most common used facets arestartand complete. Start facet will be visible once ajax request begins and stay visible untilit"s completed. Once the ajax response is received start facet becomes hidden and

complete facet shows up.

More callbacks

Other than start and complete there"re three more callback facets you can use. These are;prestart, success and error.


19

5/28/2018 java + ajax

20/373

Custom Events

If you want to execute custom javascript instead of the default usage with facets, use on*event handlers. These are the event handler versions of facets.

Animations

Generally, it"s fancier to display animated gifs with ajax requests rather than plain texts.

Skinning AjaxStatus

AjaxStatus is equipped with style and styleClass. Styling directly applies to an html divelement which contains the facets.


20

5/28/2018 java + ajax

21/373

3.3 AutoComplete

AutoComplete is an ajax component that"s used to provide suggestions while an input fieldis being typed. AutoComplete uses JSON to transfer the suggestions on the server back tothe client.

Info

Attributes


21

5/28/2018 java + ajax

22/373


22

5/28/2018 java + ajax

23/373

Getting started with AutoComplete

A method expression is called on the server side with the text entered as the query

parameter. This method takes a string parameter.


23

5/28/2018 java + ajax

24/373

AutoComplete can use the complete method when querying the results. Also sinceautocomplete is an input component, the value attribute can be used to pass the text"svalue to the server side when the form is submitted.

Pojo Support

Instead of simple strings, pojos are also supported.

With the same principle of a select component, itemLabel is the text to display as asuggestion and itemValue is the value to be submitted. You may also bind your converterto the autocomplete.

Limiting the results

Number of results shown can be limited, by default the limit is 10.


24

5/28/2018 java + ajax

25/373

Minimum query length

By default queries are sent to the server and completeMethod is called as soon as usersstarts typing at the input text. This behavior is tuned using the minQueryLengthattribute.

With this setting, querying will start when user types the 3rd character at the input field.

Animation

When results are returned from the server, a vertical animation is displayed by default.Orientation of the animation is configured via animVert and animHoriz attributes. Inaddition animSpeed determines the speed of the animation.

Skinning

AutoComplete is skinned using CSS selectors, an example would be;


25

5/28/2018 java + ajax

26/373

Output of these styles;

Full list of CSS Selectors;


26
http://developer.yahoo.com/yui/examples/autocomplete/ac_skinning.htmlhttp://developer.yahoo.com/yui/examples/autocomplete/ac_skinning.html

5/28/2018 java + ajax

27/373

3.4 BreadCrumb

Breadcrumb is a handy navigation component that provides contextual information aboutpage hierarchy in the workflow.

Info

Attributes


27

5/28/2018 java + ajax

28/373

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. Also previewWidth attributedefines the reveal amount in pixels.


28

5/28/2018 java + ajax

29/373

Animation Configuration

Duration of effects can be customizated using several attributes. Here"s an example;

Durations are defined in milliseconds.

Skinning BreadCrumb

Here"s the list of pre defined breadcrumb style classes.

Style Class Applies

.pf-breadCrumb Main breadcrumb container element.

.pf-breadCrumb ul Container list of each menuitem.

.pf-breadCrumb ul li Each menuitem container.

.pf-breadCrumb ul li a Link element of each menuitem.

.pf-breadCrumb ul li.first a First element of breadcrumb.

.pf-breadCrumb ul li div.pf-breadCrumb-chevron Seperator of menuitems.


29

5/28/2018 java + ajax

30/373

3.5 Captcha

Captcha is a form validation component used to make sure submitter of the form is ahuman, not a bot. Captcha is based on the generic recaptcha api.

Info

Attributes


30

5/28/2018 java + ajax

31/373

Getting Started with Captcha

Catpcha uses reCaptcha api as the underlying captcha mechanism and captcha has abuilt-in captcha validator that always checks the value entered with reCaptcha.

First thing to do is to sign up to reCaptcha and gain public&private keys. Once you havethe keys for your domain, add your private key to web deployment descriptor as follows.

Once private key is installed, place the captcha component on your page as;

That"s it, now invalid values entered to the captcha will result in validation errors.

Themes

Captcha supports several themes, note that custom styling is not yet supported. Followingare the valid built-in themes.


31

5/28/2018 java + ajax

32/373

red (default)

white

blackglass

clean

Themes are applied via the theme attribute.

Languages

Text instructions displayed on captcha is customized with the language attribute. Belowdemonstrates a Turkish captcha.

Overriding Validation Messages

By default captcha displays it"s own validation messages, this can be easily overriden bythe JSF message bundle mechanism. Corresponding keys are;


32

5/28/2018 java + ajax

33/373

3.6 Calendar

Calendar is an input component allowing to enter a date in various ways. Other than basicfeatures calendar supports multiple date selection, paging, localization and more.

Info

Attributes


33

5/28/2018 java + ajax

34/373


34

5/28/2018 java + ajax

35/373

Getting started with Calendar

Calendar works with java.util.Date class. In simple selection a Date object needs to bebound as the value.


35

5/28/2018 java + ajax

36/373

Since default mode is popup, this calendar would render as;

Calendar modes

Calendar has two different rendering modes, popup(default) and inline. Popup mode

displays and input text and a calendar button that pops up the calendar. Inline mode justdisplays the calendar without an inputtext.

Multiple Selection

Calendar also has support for multiple date selection, in this case the value should be aDate array instead of a single Date.


36

5/28/2018 java + ajax

37/373

L11N

Calendar has a built-in converter so there"s no need to define a datetimeconverter. Defaultpattern is MM/dd/yyyy. It"s possible to change the default pattern for localization usingthe pattern attribute.

I18N

By default locale information is retrieved from the view"s locale and can be overriden bythe locale attribute. Locale attribute can take a locale key as a String or a java.util.Localeinstance.

Following languages are supported out of the box;


37

5/28/2018 java + ajax

38/373

Patches are welcome for more i18n support.

Paging

Calendar can also be rendered in multiple pages where each page corresponds to onemonth. This feature is tuned with the pagesattribute.

Following calendar has all the months displayed;


38

5/28/2018 java + ajax

39/373

Ajax Selection

Calendar supports instant ajax selection, whenever a date is selected a server sideselectListener can be invoked with an org.primefaces.event.DateSelectEvent instance as aparameter.

PageDate

PageDate defines the initial month and year visible on calendar. By default current day"smonth and year is displayed. This can be changed using the pagedate attribute which canbe a java.util.Date or a String, note that format used is MM/yyyy. Following exampledisplays all months in a year.

Start of week

Start of week is sunday by default(0 index), this can be configured via the startWeekdayattribute. This calendar will start the weeks from monday.

Label formats

Month and weekday label supports various formats. By default full name of months andshort name of weekdays are displayed. Formats can be configured by monthFormat andweekdayFormat attibutes.

Please see the attributes list description section for the all possible values for these fields.


39

5/28/2018 java + ajax

40/373

Skinning calendar

CSS Selectors List


40
http://developer.yahoo.com/yui/examples/calendar/calskin.htmlhttp://developer.yahoo.com/yui/examples/calendar/calskin.html

5/28/2018 java + ajax

41/373

3.7 Carousel

Carousel is a generic datalist component that displays it"s children in a slideshow style.Carousel gets a collection as the value, iterates the collection and renders the children foreach item.

Info

Attributes


41

5/28/2018 java + ajax

42/373

Getting started with Carousel

To begin with, Carousel needs a java.util.Collection as it"s value to iterate. Followingexample gets a players list and renders the player"s photo along with player"s name. Let"sstart with creating the player list to display with Carousel.


42

5/28/2018 java + ajax

43/373


43

5/28/2018 java + ajax

44/373

Similar to the datatable usage, carousel iterates through the players collection and rendersit"s children for each of the player.

Limiting Visible Items

Bu default carousel lists it"s items in pages with size 3. This is customizable with the rows

attribute.

Reveal Amount

Reveal amount is the percentage of the next and previous item to be shown, it can betuned by the reveralAmount attribute. Example above reverals %20 of the next andprevious items.


44

5/28/2018 java + ajax

45/373

Effects

By default paging happens with a slider effect, there are also more effects available forpaging. Valid values are;

backBoth

backIn

backOut

bounceBoth bounceIn

bounceOut

easeBoth

easeBothStrong

easeIn

easeInStrong

easeNone

easeOut

easeOutStrong

elasticBoth elasticIn

elasticOut

SlideShow

Carousel can display the contents in a slideshow as well, for this purpose autoPlayInterval

and circular attributes are used.


45

5/28/2018 java + ajax

46/373

Skinning

An example skinning is as follows;

CSS Selectors List


46
http://developer.yahoo.com/yui/carousel/#skinninghttp://developer.yahoo.com/yui/carousel/#skinning

5/28/2018 java + ajax

47/373

3.8 Charts

Charts are flash based JSF components to display graphical data. There"re various charttypes like pie, column, line and more. Charts can also display real-time data and also canfire server side events as response to user interaction.

3.8.1 Pie Chart

Pie chart displays category-data pairs in a pie graphic.

Info

Attributes


47

5/28/2018 java + ajax

48/373

Getting started with PieChart

Chart needs a collection like a java.util.List to display the data, in addition to thedatasource categoryField is used to identify the pie section and dataField is used to holdthe value of the corresponding categoryField. As an example, suppose there are 4 brandsand each brand has made x amount of sales last year. We begin with creating the saleclass to represent this model.


48

5/28/2018 java + ajax

49/373

In SaleDisplay bean, a java.util.List holds sale data of the 4 brands.

That"s all the information needed for the pieChart to start working. Sales list can bevisualized as follows;

Output would be;


49

5/28/2018 java + ajax

50/373

3.8.2 Line Chart

Line chart visualizes one or more series of data in a line graph.

Info

Attributes


50

5/28/2018 java + ajax

51/373

Getting started with LineChart

LineChart mainly needs a collection as the value, the xField data for the x-axis and one ormore series data each corresponding to a line on the graph. To give an example, we"ddisplay and compare the number of boys and girls year by year who was born last year atsome place on earth. To model this, we need the Birth class.


51

5/28/2018 java + ajax

52/373

Next thing to do is to prepare the data year by year in BirthDisplayBean.

Given this birth p:chartSeriescollection, a linechart can visualize this data as follows;

Output of this lineChart would be;


52

5/28/2018 java + ajax

53/373

3.8.3 Column Chart

Column chart visualizes one or more series of data using a column graph.

Info

Attributes


53

5/28/2018 java + ajax

54/373

Getting started with Column Chart

Column chart usage is very similar to line chart, as an example following column chartdisplays the birth rate data in the lineChart example. Please see the lineChart section toget more information about the structure of the birth data.


54

5/28/2018 java + ajax

55/373

3.8.4 Stacked Column Chart

Stacked Column chart is similar to column chart but the columns are stacked per eachxField data.

Info

Attributes


55

5/28/2018 java + ajax

56/373

Getting started with Stacked Column Chart

Stacked column chart usage is very similar to line chart, as an example following stacked

column chart displays the birth rate data in the lineChart example. Please see thelineChart section to get more information about the structure of the birth data.


56

5/28/2018 java + ajax

57/373

3.8.5 Bar Chart

Bar Chart is the horizontal version of the column chart where columns are aligned on xaxis as bars.

Info

Attributes


57

5/28/2018 java + ajax

58/373

Getting started with Bar Chart

Bar chart usage is very similar to line chart, as an example following bar chart displays thebirth rate data in the lineChart example. Important difference is that barchart uses yfieldattribute instead of the xfield attribute. Please see the lineChart section to get moreinformation about the structure of the birth data.


58

5/28/2018 java + ajax

59/373

3.8.6 StackedBar Chart

Stacked Bar chart is similar to bar chart but the bar are stacked per each yField data.

Info

Attributes


59

5/28/2018 java + ajax

60/373

Getting started with StackedBar Chart

StackedBar chart usage is very similar to line chart, as an example following stacked bar

chart displays the birth rate data in the lineChart example. Important difference is thatstackedbarchart uses yfield attribute instead of the xfield attribute. Please see thelineChart section to get more information about the structure of the birth data.


60

5/28/2018 java + ajax

61/373

3.8.7 Chart Series

A chart can have one or more series and a chartSeries component represents each seriesin a chart.

Info

Attributes

Getting started with ChartSeries

ChartSeries is nested inside a chart component, you can have as many series as you wanton a chart by nesting multiple series. Please see the other chart componentdocumentations to see the usage of chartSeries.


61

5/28/2018 java + ajax

62/373

3.8.8 Skinning Charts

Charts are highly customizable in terms of skinning however they are flash based, as aresult regular CSS styling is not possible. Charts are styled through Javascript and theobject is passed to the chart"s style attribute.

There are two attributes in chart components related to skinning.

styleClass : Each chart resides in an html div element, style class applies to this containerelement. Style class is mainly useful for setting the width and height of the chart.

style : Style should be the javascript object variable name used in styling, as a simpleexample to start with; Style below effects chart padding, border and legend. See the full listof style selectors link for the complete list of selectors.

Skinning Series

ChartSeries can be styled individually using the style attribute. Styling is same as chartsand done via javascript.


62

5/28/2018 java + ajax

63/373

Extreme Makeover

To give a complete styling example, we"ll skin the chart described in colum chart section.In the end, after the extreme makeover chart will look like;


63

5/28/2018 java + ajax

64/373

Full List of Style Selectors


64
http://developer.yahoo.com/yui/charts/#http://developer.yahoo.com/yui/charts/#

5/28/2018 java + ajax

65/373

3.8.9 Real-Time Charts

Charts have built-in support for ajax polling and live data display. As an example supposethere"s an ongoing vote between two candidates. To start with, create the Vote classrepresenting the voting model.

Next step is to provide the data;


65

5/28/2018 java + ajax

66/373

For displaying the voting, we"ll be using a pie chart as follows;

This live piechart is almost same as a static pie chart, except live attribute is set to true.When a chart is live, the collection bind to the value is read periodically in a specifiedinterval. In this example, getVotes() would be called continuosly in 5 seconds interval.Polling interval is tuned using the refreshInterval attribute which is set to 3000milliseconds.


66

5/28/2018 java + ajax

67/373

3.8.10 Interactive Charts

Charts are interactive components and they can respond to events like series itemselection. When a series item is clicked an ajax request is sent to the server and anitemSelectListener is notified passing an itemSelectEvent. ItemSelectEvent contains usefulinformation about the selected item like series index and item index.

Chart components also use PrimeFaces Partial Page Rendering mechanism so using theupdate attribute, it"s possible to refresh other components on the page. In the examplebelow, message outputText is refreshed with the message provided in itemSelectListener.

Please note that interactive charts must be nested inside a form.


67

5/28/2018 java + ajax

68/373

3.8.11 Charting FAQ

Flash Version

Chart components require flash player version 9.0.45 or higher.

Express Install

In case the users of your application use an older unsupported version of flash player,chart components will automatically prompt to install or update users"flash players. Thescreen would look like this for these users.

JFreeChart Integration

If you like to use static image charts instead of flash based charts, see the JFreeChartintegration example at p:graphicImage section.


68

5/28/2018 java + ajax

69/373

3.9 Collector

Collector is a simple utility component to manage collections without writing java code onbacking beans.

Info

Attributes

Getting started with Collector

Collector requires a collection and a value to work with. It"s important to overrive equalsand hashCode methods of the value object to make collector work.


69

5/28/2018 java + ajax

70/373

Valueattribute is required and sets the object to be added or removed to/from a collection.


70

5/28/2018 java + ajax

71/373

3.10 Color Picker

ColorPicker component enhances color selection with color visualization.

Info

Attributes


71

5/28/2018 java + ajax

72/373


72

5/28/2018 java + ajax

73/373

Getting started with ColorPicker

ColorPicker component just needs a value to work. By default this value should be in typeof java.awt.Color class. When user selects a color from the popup, the selected color"scorresponding red,green,blue ( RGB ) values are populated to that object.

Headless ColorPicker

For headless servers that have no java.awt.* you can still use colorPicker by the help of acustom converter. Here"s an example.


73

5/28/2018 java + ajax

74/373

This way selected color will not be converted to java.awt.Color but used as a simple rgbstring such as #250, 214, 255".


74

5/28/2018 java + ajax

75/373

3.11 Column

Column is an extended version of the standard column providing features like sorting,selection, resizing, filtering and more.

Info

Attributes


75

5/28/2018 java + ajax

76/373

3.12 CommandButton

CommandButton extends standard JSF commandButton by adding ajax and confirmationfeatures.

Info

Attributes


76

5/28/2018 java + ajax

77/373


77

5/28/2018 java + ajax

78/373

Getting started with commandButton

CommandButton component submits it"s enclosed form unless it is defined as reset. The

submittype works exactly same as a standard commandButton. To have a reset buttonthe typeof the button should be written as reset.

Reset

Reset mode does not do a form submit and just resets the form contents.


78

5/28/2018 java + ajax

79/373

AJAX

CommandButton has built-in ajax capabilities, to enable partial submit the attribute asyncneeds to be true which is the default setting (Set it to false to disable ajax submission).When button is in async mode, it submits the parent form via ajax.

The update attribute is used to partially update the components after the ajax response isreceived. Update attribute takes a comma seperated list client idsof JSF components tobe updated. Basically any JSF component, not just primefaces components can beupdated with the Ajax response.

In the following example, form is submitted with ajax and form contents are updated withthe ajax response..

Update with Ajax Response

In previous example commandButton processes and updates it"s parent form by default. Incases where you require to update any JSF component on page, use the update attributeand provide the client side id(s) of the component you wish to update with ajax response.As an example in order to just update the display panelGrid"s contents;


79

5/28/2018 java + ajax

80/373

onstart and oncomplete

The two callbacks onstart and oncomplete allows you to execute custom javascript forthese events. onstart is called before ajax request begins, similary oncomplete after ajaxrequests ends and dom is updated.

Note: See the ajaxStatus component for global start and complete callbacks.

Confirmation

Confirmation on commandButton click is a common use case in applications, thetraditional way to do is using javascript confirm function, downside is that confirm boxes

lack customization, styling and can be blocked by popup blockers. CommandButton isequipped with a built-in confirmation dialog.

When there"s a nested confirmDialog component, commandButton click would not triggerinstantly and display a confirmation before taking action. Default dialog looks like thefollowing;

ConfirmDialog is a highly customizable component, buttons, message, header, styles andmore can be tuned. Please see the confirmDialog section for more information.

Skinning

CommandButton renders an input type=submitelement and can be easily skinned usingstyle&styleClass attributes.


80

5/28/2018 java + ajax

81/373

3.13 CommandLink

CommandLink extends standard JSF commandLink with Ajax capabilities.

Info

Attributes


81

5/28/2018 java + ajax

82/373


82

5/28/2018 java + ajax

83/373

Getting started with commandLink

CommandLink is used just like the standard h:commandLink. The difference is

commandLink requires component client ids to update after the ajax request.

Note: If you don"t provide the components to update via the update attribute, by defaultparent form of commandLink is updated.

onstart and oncomplete

The two callbacks onstart and oncomplete allows you to execute custom javascript forthese events. onstart is called before ajax request begins, similary oncomplete after ajaxrequests ends and dom is updated.


83

5/28/2018 java + ajax

84/373

Skinning

CommandLink renders an html anchor element, use style and styleClass attributes forskinning this anchor element.


84

5/28/2018 java + ajax

85/373

3.14 ConfirmDialog

ConfirmDialog is a replacement to the legacy javascript confirmation box. Its main use is tohave the user do a binary decision(either yes or no). Skinning, customization and avoidingpopup blockers are some the advantages over classic javascript confirmation.

Info

Attributes


85

5/28/2018 java + ajax

86/373

Getting started with ConfirmDialog

ConfirmDialog is used by commandButton and commandLink. Please see thecommandButton component documentation for more information.

Skinning

Please check dialog component for styling confirm dialog.


86

5/28/2018 java + ajax

87/373

3.15 ContextMenu

ContextMenu provides a popup menu that is displayed on mouse right-click event.

Info

Attributes

Getting started with ContextMenu

Just like any other PrimeFaces menu component, contextMenu is created with menuitems.


87

5/28/2018 java + ajax

88/373

Optional for attribute defines which component the contextMenu is attached to. When for isnot defined, contextMenu is attached to the page meanining, right-click on anywhere onpage will display the menu.

ContextMenu example above is attached to the whole page and consists of three differentmenuitems with different use cases. First menuitem triggers an ajax action, second onetriggers a non-ajax action and third one is used for navigation.

Attaching

ContextMenu can be attached to any JSF component, this means right clicking only on theattached component will display the contextMenu. Following example demonstrates anintegration between contextMenu and imageSwitcher, contextMenu here is used tonavigate between images.

Now right-clicking anywhere on an image will display the contextMenu like;


88
http://www.primefaces.org/http://www.primefaces.org/

5/28/2018 java + ajax

89/373

Skinning

ContextMenu resides in a div container element, style and styleClass attributes apply tothis element. For advanced styling contextMenu is an extension to menu, same CSS rulesapply.

Default skin of contextMenu looks like;

This is easy to customize using well defined CSS selectors.

Will result in;

For full list of CSS selectors and detailed information on which style applies where, take alook at;


89
http://developer.yahoo.com/yui/examples/editor/skinning_editor.htmlhttp://developer.yahoo.com/yui/examples/editor/skinning_editor.html

5/28/2018 java + ajax

90/373

3.16 Dashboard

Dashboard provides a portal like layout with drag&drop based reorder capabilities andmore.

Info

Attributes


90

5/28/2018 java + ajax

91/373

Getting started with Dashboard

Dashboard is backed by a DashboardModel and consists of panel components.

Backing dashboard model simply defines the number of columns and defines the widgetsto be placed in each column. Additionally dashboardcolumn is used to define a column inlayout. APIs for these classes are;

Class Description

org.primefaces.model.DashboardModel Dashboard model contract

org.primefaces.model.DefaultDashboardModel Default implementation of dashboard model

org.primefaces.model.DashboardColumn Dashboard column contract

org.primefaces.model.DefaultDashboardColumn Default implementation of dashboard column

See the javadoc to see the full Dashboard API.


91

5/28/2018 java + ajax

92/373

State

Dashboard is a stateful component, whenever a widget is reordered dashboard model willbe updated, by persisting this information, you can easily create a stateful dashboard sofor example if your applications allows users to change the layout, next time a user logs inyou can present the dashboard layout based on the preferences of user.

Ajax Reorder

As most of other PrimeFaces components, dashboard provides flexible callbacks for pageauthors to invoke custom logic. Ajax reorderListener is one of them, optionally you canupdate a certain part of your page with onReorderUpdate option.


92

5/28/2018 java + ajax

93/373

This dashboard displays a facesmessage added at reorderlistener using growl.

org.primefaces.event.DashboardReorderEventprovides useful information regarding thereorder event.

Property Description

widgetId Id of the panel that is reordered

itemIndex Index of the reordered item in column

columnIndex Index of the current column of reordered item

senderColumnIndex * Index of the new column of reordered item

If a widget is reordered in the same column, senderColumnIndex will be null. This field ispopulated only when widget is moved to a column from another column. Also whenreorderListener is invoked, dashboard has already updated it"s model, reorderListener isused for custom logic like persisting the model.

Disabling Dashboard

If you"d like to disable reordering, setting disabled to true would be enough.

Toggle and Close

Widgets presented in dashboard can be closable and toggleable as well, dashboarddoesn"t implement it by itself as these features are provided by the panel component.


93

5/28/2018 java + ajax

94/373

Panel has also advanced features like ajax toggle and close listeners, built-in popup menuand more, see panel documentation for more information.


94

5/28/2018 java + ajax

95/373

3.17 DataExporter

DataExporter is handy for exporting data listed in a Primefaces Datatable to variousformats such as excel, pdf, csv and xml.

Info

Attributes

Getting started with DataExporter

DataExporter is nested in a UICommand component such as commandButton orcommandLink. For pdf exporting itextand for xls exporting poilibraries are required in theclasspath. Target must point to a PrimeFaces Datatable.

Excel export


95

5/28/2018 java + ajax

96/373

PDF export

CSV export

XML export

PageOnly

By default dataExporter works on whole dataset, if you"d like export only the datadisplayed on current page, set pageOnly to true.

Excluding Columns

Usually datatable listings contain command components like buttons or links that need to

be excluded from the exported data. For this purpose optional excludeColumns property isused to defined the column indexes to be omitted during data export.

Exporter below ignores first column, to exclude more than one column define the indexesas a comma seperated string (excludeColumns=0,2,6)


96

5/28/2018 java + ajax

97/373

Pre and Post Processors

In case you need to customize the exported document (add logo, caption ...), use theprocessor method expressions. PreProcessors are executed before the data is exportedand PostProcessors are processed after data is included in the document. Processors aresimple java methods taking the document as a parameter.

Change Excel Table Header

First example of processors changes the background color of the exported excel"sheaders.

Add Logo to PDF

This example adds a logo to the PDF before exporting begins.


97

5/28/2018 java + ajax

98/373


98

5/28/2018 java + ajax

99/373

3.18 DataTable

DataTable is an enhanced version of the standard Datatable and provides built-in solutionsto many commons use cases like paging, sorting, scrolling, selection, lazy loading,filtering, resizable colums and more.

Info

Attributes


99

5/28/2018 java + ajax

100/373


100

5/28/2018 java + ajax

101/373

Getting started with the DataTable

We will be using a list of cars to display throughout the datatable examples.


101

5/28/2018 java + ajax

102/373

The code for CarBean that would be used to bind the datatable to the car list.


102

5/28/2018 java + ajax

103/373

Dynamic vs Non-Dynamic

DataTable has two main modes, when it is non-dynamic(default) it works as a pure clientside component, on the other hand dynamic datatables fetch their data from backing beanmodel with ajax. Features including paging, sorting and filtering are both implemented onclient side and server side to handle both cases of dynamic seting.

For small datasets non-dynamic datatables is much faster and have the advantage ofavoiding roundtrips to server with ajax.

Pagination

Pagination is a powerful feature of DataTable that can be handled purely on client side oron server side enhanced with ajax. Just set the paginator to true and define number ofrows to display to enable the pagination.

By default all data is sent with the response and pagination is handled on client side.Although this is very fast, for huge data it"s not the optimal solution. In order to save somebandwidth and still keep the rich user experience enable the dynamicmode to bring in theajax pagination.

Customized Paginator

Default paginator is based on this template;

Paginator is highly customizable and paginatorTemplatetunes this feature.


103

5/28/2018 java + ajax

104/373

With this setting paginator looks like;

Full is of valid template values for paginator are;

FirstPageLink

PreviousPageLink

NextPageLink

LastPageLink

PageLinks

RowsPerPageDropdown (Also customizable with rowsPerPageTemplate attribute)

CurrentPageReport

Location of the datatable is also customizable with the paginatorPosition attribute, default

setting is both meaning two paginators are displayed at the top and bottom of datatable. Ifyou only need one paginator use #top"or #bottom"depending on your choice.


104

5/28/2018 java + ajax

105/373

Sorting

Sorting is controlled at column level, defining sortBy attribute enables sorting on thatparticular column. If datatable is dynamic, sorting is handled on server side with ajax, if notsorting happens on client side.

When sorting is handled on client side, you need to define built-in client side data parsersfor proper sorting. Possible values for parser attribute of column are #string"(default),#number"and #date".

Custom Sorting

Instead of using the default sorting algorithm, you can plug-in your own sort function.

When ajax sorting enabled sorting must refer to a java method that takes two parametersand return an integer value.


105

5/28/2018 java + ajax

106/373

In case datatable is not dynamic then sortFunction must refer to a javascript function.

Client side javascript function gets four parameters;


106

5/28/2018 java + ajax

107/373

Parameter Description

a Javascript object representing a row data

b Javascript object representing a row data

desc Boolean value of order, returns true if order is descending

field Column key to be used to retrieve column value

Scrolling

Scrolling is another way of displaying huge amount data in a space saving way. When adatatable is scrollable the header becomes fixed and a scrollbar is displayed for thescrolling. Currently scrolling can be enabled both vertically and horizontally. Scrollingattribute is used along with height and width attribute to manage the scrolling. Followingexample is a vertically scrolling datatable with fixed header.

When the datatable contents get more space then 200px, datatable starts scrolling. Topreserve more space horizontally, use the width attribute to enable horizontal scrolling.


107

5/28/2018 java + ajax

108/373

Scrolling does not support dynamic tables and support only client side datatables fornow. Live scrolling will be added in a future release.

Resizable Columns

A column can be made resizable by setting resizableattribute to true. A resizable columnenables users to change the width of the column using the column header.

Row Selection

There are several built-in solutions that make row selection a piece of cake. One way is todirectly click on table rows and second way is to use a selection column.

Select Single with Row Click

To select a single row when a row is clicked use the selectionMode attribute of thedatatable.


108

5/28/2018 java + ajax

109/373

selectedCar is a simple member of type Car that will be set with the selected data once theform is submitted. Note that when a row is clicked, row is highlighted.

Additionaly if you"d like allow row selection with double clicking to a row instead of singleclick set dblClickSelect option to true.


109

5/28/2018 java + ajax

110/373

Multiple Row Selection

If you require selecting multiple rows, set the selectionMode to multiple and define a Cararray. This way using modifier keys like ctrl or shift, multiple rows can be selected.


110

5/28/2018 java + ajax

111/373

Instant Ajax Row Selection

Two methods describe above requires the form to be submitted before the row selectioncan happen. If you need instant row selection with ajax define an update attribute pointingto the component to be updated. This way when a row is clicked ajax request is triggeredand selected row(s) are assigned to the selection model instantly without a need for animplicit form submit.


111

5/28/2018 java + ajax

112/373

When a row is selected on the datatable above, ajax request updates the display paneland shows a dialog with the selected cars information. Callbacks like onselectStart andonselectComplete allows creating flexible UIs. This is quite useful if you need to displaydetailed information about selected data instantly.

Data Filtering

Setting a column filter is as easy as specifying filterBy attribute to true.


112

5/28/2018 java + ajax

113/373

Similar to paging and sorting, dynamic datatables use ajax to filter data whereas non-dynamic datatables handle filtering on client side.

By default filtering is triggered with keyup event, this is configurable using filterEventattribute, in addition filter inputs can be styled using filterStyleand filterStyleClassattributes.

Lazy Loading

Dealing with huge sets of data like thousand and even millions is not a trivial task, goodnews is datatable provides a built-in feature that can even handle billions of data in anefficient way. The idea behind lazy loading is to load only the rows of the datatable page

being displayed.

In order to enable lazy loading you just need to set lazy attribute to true and provide aLazyDataModel as the value of the datatable.


113

5/28/2018 java + ajax

114/373

When lazy loading is enabled, datamodel will executed your LazyModel"s fetchLazyDatamethod with the first and pagesize variables. It"s your responsibility to load a chunk of datathat starts from the first offset and with size pageSize. For example if you"re using jpa youcan use setFirstResult(first) and setMaxResults(pageSize) api to load a certain amount ofdata. With lazy loading you never load the whole dataset but only the necessary portion.LazyLoading feature is also enhanced with ajax paging for rich user experience.

Skinning

As like any other primefaces component skinning is done via CSS selectors.

Full list of CSS Selectors is available at;


114
http://developer.yahoo.com/yui/examples/datatable/dt_skinning.htmlhttp://developer.yahoo.com/yui/examples/datatable/dt_skinning.html

5/28/2018 java + ajax

115/373


115

5/28/2018 java + ajax

116/373

3.19 Dialog

Dialog is a panel component that has the ability to overlay other elements. Dialog avoidspopup blockers, provides customization, resizing and ajax interactions.

Info

Attributes


116

5/28/2018 java + ajax

117/373


117

5/28/2018 java + ajax

118/373

Getting started with the Dialog

Since dialog is a container component it needs children components to display. Note thatby default dialog is not visible.

Positioning

Dialog can be positioned anywhere on the screen. X and Y attributes defined the left-topcoordinate of the panel. Another way is to set the fixedCenter attribute to true which will fixthe panel at the center of the page. Yet another way is to use the context relative

positioning.

Absolute

Centered

Context

In example above, dialog"s top left corner will be located at bottom right corner of button.

Showing&Hiding

Showing and hiding the dialog is easy using the client side api via widgetVar.

show() : Displays the dialog

hide() : Makes dialog invisible


118

5/28/2018 java + ajax

119/373

Ajax Interaction

A dialog can also be used for ajax interaction. Following example demonstrates anexample powered by PrimeFaces PPR.

When the dialog is shown, it displays a form to enter the firstname, once Ajax Submitbutton is clicked, dialog is hidden and outputText with id=name is partially updated.

Header and Footer

header and footer attributes are the easiest way to define the texts of dialogs. for customcontrols dialog has two facets named header and footer.


119

5/28/2018 java + ajax

120/373

Effects

When showing and hiding the dialog, effect can be displayed to emphasize dialog. Thereare two effects, FADE and SLIDE. In addition effect duration is customized viaeffectDuration attibute in seconds.

Dialog above displays a FADE effect when showing&hiding and it takes 0.5 seconds.

Ajax CloseListener and onCloseUpdate

If you"d like to execute custom logic when a dialog is closed, you can bind a server side

closeListener for this task. Optionally components to update after dialog is closed can bedefined with onCloseUpdate attribute. Example below adds a FacesMessage when dialogis closed and updates the messages component to display the added message.

org.primefaces.event.CloseEventhas a method called getComponent() that will return thedialog instance that is closed. You might use it if you reuse the same listener for multipledialogs on same page.

Skinning


120

5/28/2018 java + ajax

121/373

Skinned dialog above can be achieved with the following styles;

Full list of CSS Selectors


121
http://developer.yahoo.com/yui/examples/container/panelskin2.htmlhttp://developer.yahoo.com/yui/examples/container/panelskin2.htmlhttp://developer.yahoo.com/yui/examples/container/panelskin1.htmlhttp://developer.yahoo.com/yui/examples/container/panelskin1.html

5/28/2018 java + ajax

122/373

3.20 Drag&Drop

Drag&Drop utilities of PrimeFaces consists of two components; Draggable and Droppable.

Draggable

Info

Attributes

Getting started with Draggable

Basically draggable is used a child component and makes it"s parent draggable. Supposeyou have a panel that you want to enable dragging.


122

5/28/2018 java + ajax

123/373

Similarly a standard JSF component can be enabled for dragging as well. Following imageis enabled for dragging.

Proxy

By default, the actual item is used as drag indicator, for better performance a simple proxyitem can be used instead.

DragOnly

A draggable component can interact with drop zones which will be described in the nextsection. To disable this interaction, set dragOnly to false.

Droppable

Info


123

5/28/2018 java + ajax

124/373

Attributes

Getting started with Droppable

Usage of droppable is very similar to draggable, simply droppable makes it parent a dropzone, meaning the draggable components can be dropped onto the parent. Followingexamples demonstrates how to drop an image to a drop zone.

slot styleClass represents a small rectangle.

With this setup, an image with id messican be dropped onto the outputPanel with id zone.Best part is you can execute custom callbacks when drag&drop happens on server side.


124

5/28/2018 java + ajax

125/373

Drop Listener

A dropListener is a simple java method that"s executed when a draggable item is droppedonto a droppable component. A DragDrop event is passed as a parameter holdinginformation about the dragged and dropped components. Using the previous example justadd a dropListener to the droppable.

The method above just logs the item being dragged and dropped. Output of this methodwould be;

PrimeFaces component showcase demo contains a functional example to setup tacticalformation of F.C. Barcelona, see the source code for more information.


125

5/28/2018 java + ajax

126/373

3.21 Dock

Dock component mimics the well known dock interface of Mac OS X.

Info

Attributes


126

5/28/2018 java + ajax

127/373

Getting started with the Dock

A dock is composed of menuitems.

Position

Dock can be located in two locations, top or bottom(default). For a dock positioned at topset position to top.

Dock Effect

When mouse is over the dock items, icons enlarge. The configuration of this effect is donevia the maxWidth and proximity attributes.


127

5/28/2018 java + ajax

128/373

3.22 Editor

Editor is an enhanced input component providing rich text editing features. Editor supportsadvanced text editing features like fonts, colors, images, alignment and more.

Info

Attributes


128

5/28/2018 java + ajax

129/373


129

5/28/2018 java + ajax

130/373

Getting started with the Editor

Rich Text entered using the Editor is passed to the server using valueexpression.

Editor and I18N

Labels like Font Style, Paragraph Style can be localized using the language attribute.Default language is English and following languages are supported out of the box.

tr : Turkish

pt : Portuguese

Please contact PrimeFaces team using support forum if you"re willing to provide a newtranslation.

Header text of the editor can also be changed via the title attribute. Following is a Turkisheditor.


130

5/28/2018 java + ajax

131/373

Skinning Editor

Full list of CSS Selectors


131
http://developer.yahoo.com/yui/examples/editor/skinning_editor.htmlhttp://developer.yahoo.com/yui/examples/editor/skinning_editor.html

5/28/2018 java + ajax

132/373

3.23 Effect

Effect component is based on the jQuery effects library.

Info

Attributes

Getting started with Effect

Effect component needs to be nested inside another component. If for attribute is notprovided, by default parent would be animated.


132

5/28/2018 java + ajax

133/373

List of Effects

Following is the list of effects supported by PrimeFaces.

blind

clip

drop

explode

fold

puff

slide

scale bounce

highlight

pulsate

shake

size

transfer

Effect Configuration

Each effect has different parameters for animation like colors, duration and more. In orderto change the configuration of the animation, provide these parameters with the f:paramtag.

It"s important to provide string options with single quotes.


133

5/28/2018 java + ajax

134/373

For the full list of configuration parameters for each effect, please see the jquerydocumentation;

Animation Target

By default, effect is attached to it"s parent on the specified event. There may be caseswhere you want to display an effect on another component on the same page whilekeeping the parent as the trigger. For attribute is added for this purpose.

With this setting, outputLink becomes the trigger for the effect on graphicImage. When thelink is clicked, initially hidden graphicImage comes up with a fade effect.

Effect on Load

Effects can also be applied to any JSF component when page is loaded for the first time or after anajax request is completed. Following example animates messages with pulsate effect after ajaxrequest.


134
http://docs.jquery.com/UI/Effectshttp://docs.jquery.com/UI/Effects

5/28/2018 java + ajax

135/373

3.24 FileDownload

The legacy way to present dynamic binary data to the client is to write a servlet or a filterand stream the binary data. FileDownload does all the hardwork and presents an easybinary data like files stored in database.

Info

Attributes

Getting started with FileDownload

A user command action is required to trigger the filedownload process. FileDownload canbe attached to any command component like a commandButton or commandLink.

The value of the FileDownload must be an org.primefaces.model.StreamedContentinstance. We suggest using the ready DefaultStreamedContent implementation. Firstparameter of the constructor is the binary stream, second is the mimeType and the thirdparameter is the name of the file.

This streamed content should be bound to the value of the fileDownload.


135

5/28/2018 java + ajax

136/373

Similarly a more graphical presentation would be to use a commandlink with an image.

ContentDisposition

By default, content is displayed as an attachment with a download dialog box, anotheralternative is the inline mode, in this case browser will try to open the file internally withouta prompt. Note that content disposition is not part of the http standard although it is widelyimplemented.


136

5/28/2018 java + ajax

137/373

3.25 FileUpload

FileUpload goes beyond the browser input type=file functionality and features a flash-javascript solution for uploading files. File filtering, multiple uploads, partial page renderingand progress tracking are the significant features compared to legacy fileUploads.

Additionally in case the user agent does not support flash or javascript, fileUpload willfallback to the legacy input type=file and still work.

Info

Attributes


137

5/28/2018 java + ajax

138/373

Getting started with FileUpload

First thing to do is to configure the fileupload filter which parses the multipart request. It"simportant to make PrimeFaces file upload filter the very first filter to consume the request.


138

5/28/2018 java + ajax

139/373

Single File Upload

By default file upload allows selecting and uploading only one file at a time, simplest fileupload would be;

FileUploadListener is the way to access the uploaded files, when a file is uploaded definedfileUploadListener is processed with a FileUploadEvent as the parameter.

UploadedFile belongs to the PrimeFaces API and contains methods to retrieve various

information about the file such as filesize, contents, file type and more. Please see theJavaDocs for more information.

Multi FileUploads

Multiple fileuploads can be enabled using the multiple attribute. This way multiple files canbe selected and uploaded together.


139

5/28/2018 java + ajax

140/373

Auto Upload

Default behavior requires users to trigger the upload process, you can change this way bysetting auto to true. Auto uploads are triggered as soon as files are selected from thedialog.

Partial Page Update

After the fileUpload process completes you can use the PrimeFaces PPR to update anycomponent on the page. FileUpload is equipped with the update attribute for this purpose.Following example displays a File Uploaded message using the growl component afterfile upload.

File Filters

Users can be restricted to only select the file types you"ve configured, for example a filefilter defined on *.jpg will only allow selecting jpg files. Several different file filters can beconfigured for a single fileUpload component.

Size Limit

Most of the time you might need to restrict the file upload size, this is as simple as settingthe sizeLimit configuration. Following fileUpload limits the size to 10000 bytes for each file.


140

5/28/2018 java + ajax

141/373

Skinning FileUpload

FileUpload is a highly customizable component in terms of skinning. Best way to show thisis start with an example. After skinning the fileUpload will look like;

The image of the browse button is customized using the image attribute and the image forcancel button is configured with cancelImage attribute. Note that when you use a customimage for the browse button set the height and width properties to be same as the imagesize. In addition, style and styleClass attributes apply to the main container element(span)of fileupload controls.

Another important feature is the customUI. Since fileUpload is a composite component, wemade the UI flexible enough to customize it for your own requirements. When customUI isset to true, default upload and cancel links are not rendered and it"s up to you to handlethese events if you want using the client side api. There"re two simple methods upload()and clear() that you can use to plug-in your own UI.

Filter Configuration

FileUpload filter"s default settings can be configured with init parameters. Twoconfiguration options exist, threshold size and temporary file upload location.

Parameter Name Description

thresholdSize Maximum file size in bytes to keep uploaded files in memory. If

a file exceeds this limit, it"ll be temporarily written to disk.


141

5/28/2018 java + ajax

142/373

Parameter Name Description

uploadDirectory Disk repository path to keep temporary files that exceeds thethreshold size. By default it is System.getProperty(java.io.tmpdir)

An example configuration below defined thresholdSize to be 50kb and uploads to user"stemporary folder.


142

5/28/2018 java + ajax

143/373

3.26 Focus

Focus is a clever component that makes it easy for page authors to manage the elementfocus on a JSF page.

Info

Attributes

Getting started with Focus

In it"s simplest form, focus is enabled by just placing the component on the page as;

That"s it, now let"s add some input components to give something to focus on.


143

5/28/2018 java + ajax

144/373

Input Focus

You don"t need to explicitly define the component to receive focus as by default focus willfind the first enabled and visible input componenton page. Input component can be anyelement such as input, textarea and select. Following is a simple example;

When this page initially opens, input text with id firstname will receive focus as it is thefirst input component.

Validation Aware

Another useful feature of focus is that when validations fail, first invalid component will

receive a focus. So in previous example if firstname field is valid but surname field has noinput, a validation error will be raised for surname, in this case focus will be set onsurname field implicitly. Note that for this feature to work on ajax requests, you need toupdate p:focus component as well.

Explicit Focus

Additionally, using for attribute focus can be set explicitly on an input component.


144

5/28/2018 java + ajax

145/373

3.27 GraphicImage

PrimeFaces GraphicImage extends standard JSF graphic image component with theability of displaying binary data like an inputstream. Main use cases of GraphicImage is tomake displaying images stored in database or on-the-fly images easier. Legacy way to do

this is to come up with a Servlet that does the streaming, GraphicImage does all the hardwork without the need of a Servlet.

Info

Attributes


145

5/28/2018 java + ajax

146/373

Getting started with GraphicImage

GraphicImage requires a org.primefaces.model.StreamedContentcontent as it"s value.StreamedContent is an interface and PrimeFaces provides a ready implementation calledDefaultStreamedContent. Following examples loads an image from the classpath.


146

5/28/2018 java + ajax

147/373

DefaultStreamedContent gets an inputstream as the first parameter and mime type as thesecond. Please see the javadocs if you require more information.

In a real life application, you can create the inputstream after reading the image from thedatabase. For examplejava.sql.ResultsSetAPI has the getBinaryStream() method to readblob files stored in database.

Displaying Charts with JFreeChart

StreamedContent is a powerful API that can display images created on-the-fly as well.Here"s an example that generates a chart with JFreeChart and displays it withp:graphicImage.


147

5/28/2018 java + ajax

148/373

Basically p:graphicImage makes any JSF chart component using JFreechart obselete andlets you to avoid wrappers to take full advantage of JFreechart API.

Displaying a Barcode

Similar to the chart example, a barcode can be generated as well. This sample usesbarbecue project for the barcode API.


148

5/28/2018 java + ajax

149/373

Passing Parameters

Behind the scenes, dynamic images are generated by a different request whose format isdefined initially by the graphicImage. Suppose you want to generate different imagesdepending on a request parameter. Problem is the request parameter can only beavailable at initial load of page containing the graphicImage, you"d lose the value of the

parameter for the actual request that generates the image. To solve this, you can passrequest parameters to the graphicImage via f:param tags, as a result the actual requestrendering the image can have access to these values.

Displaying Regular Images

As GraphicImage extends standard graphicImage component, it can also display regularnon dynamic images.


149

5/28/2018 java + ajax

150/373

3.28 GraphicText

GraphicText can convert any text to an image format in runtime.

Info

Attributes


150

5/28/2018 java + ajax

151/373

Getting started with GraphicText

GraphicText only requires the text value to display.

Font Settings

Font of the text in generated image is configured via font* attributes.


151

5/28/2018 java + ajax

152/373

3.29 Growl

Growl is based on the Mac"s growl notification widget and used to display FacesMessagessimilar to h:messages.

Info

Attributes


152

5/28/2018 java + ajax

153/373

Getting Started with Growl

Growl is a replacement of h:messages and usage is very similar indeed. Simply placegrowl anywhere on your page, since messages are displayed as an overlay, the location ofgrowl in JSF page does not matter.

Lifetime of messages

By default each message will be displayed for 6000 ms and then hidden. A message ca bemade sticky meaning it"ll never be hidden automatically.

If growl is not working in sticky mode, it"s also possible to tune the duration of displayingmessages. Following growl will display the messages for 5 seconds and then fade-out.

Growl with Ajax

If you need to display messages with growl after an ajax request you just need to update itjust like a regular component.


153

5/28/2018 java + ajax

154/373

Positioning

Growl is positioned at top right corner by default, position can be controlled with a CSSselector called gritter-notice-wrapper.

With this setting growl will be located at top left corner.


154

5/28/2018 java + ajax

155/373

3.30 HotKey

HotKey is a generic key binding component that can bind any formation of keys tojavascript event handlers or ajax calls.

Info

Attributes


155

5/28/2018 java + ajax

156/373

Getting Started with HotKey

HotKey is used in two ways, either on client side with the event handler or with ajaxsupport. Simples example would be;

When this hotkey is on page, pressing the a key will alert the #Pressed key a"text.

Key combinations

Most of the time you"d need key combinations rather than a single key.

Integration

Here"s an example demonstrating how to integrate hotkeys with a client side api. Using leftand right keys will switch the images displayed via the p:imageSwitch component.


156

5/28/2018 java + ajax

157/373

Ajax Support

Ajax is a built-in feature of hotKeys meaning you can do ajax calls with key combinations.Following form can be submitted with the ctrl+shift+scombination.

Note that hotkey must be nested inside a form to use the ajax support. We"re also planningto add built-in hotkey support for p:commandButton and p:commandLink since hotkeys area common use case for command components.


157

5/28/2018 java + ajax

158/373

3.31 IdleMonitor

IdleMonitor watches users"actions on a page and notify several callbacks in case they goidle or active again.

Attributes


158

5/28/2018 java + ajax

159/373

Getting Started with IdleMonitor

To begin with, you can listen to events that are called when a user goes idle or becomesactive again. Example below displays a warning dialog onidle and hides it back when usermoves the mouse or uses the keyboard.

Controlling Timeout

By default, idleMonitor waits for 5 minutes (300000 ms) until triggering the onidle event.You can customize this duration with the timeout attribute.

IdleListener

Most of the time you may need to be notified on server side as well about IdleEvents sothat necessary actions like invalidating the session or logging can be done. For thispurpose use the idleListeners that are notified with ajax. A conventional idleEvent ispassed as parameter to the idleListener.

HandleIdle is a simple method that"s defined in idleMonitorController bean.


159

5/28/2018 java + ajax

160/373

AJAX Update

IdleMonitor uses PrimeFaces PPR to update the dom with the server response after anidleListener is notified. Example below adds a message and updates an outputText.


160

5/28/2018 java + ajax

161/373

3.32 ImageCompare

ImageCompare provides a rich user interface to compare two images.

Info

Attributes


161

5/28/2018 java + ajax

162/373

Getting started with imageCompare

ImageCompare is created with two images with same height and width.

It is required to always set width and height of the images.

Skinning

Two images are placed inside a div container element, styleand styleClassattributesapply to this element.


162

5/28/2018 java + ajax

163/373

3.33 ImageCropper

ImageCropper allows cropping a certain region of an image. A new image is createdcontaining the cropped area and assigned to a CroppedImage instanced on the serverside.

Info

Attributes


163

5/28/2018 java + ajax

164/373

Getting started with the ImageCropper

Image to be cropped is provided via the imageattribute. ImageCropper is an inputcomponent and the cropped area of the original image is used to create a new image, thisnew image can be accessed on the server side jsf backing bean by setting the valueattribute of the image cropper.


164

5/28/2018 java + ajax

165/373

Assuming the image is at %WEBAPP_ROOT%/campnou.jpg

CroppedImage is a PrimeFaces api and contains handy information about the cropprocess. Following table describes CroppedImage properties.

Probably most important property is the bytes since it contains the byte[] representation ofthe cropped area, an example that saves the cropped part to a folder in web server is

described below.


165

5/28/2018 java + ajax

166/373

External Images

ImageCropper has the ability to crop external images as well.

Context Relative Path

For local images, ImageCropper always requires the image path to be context relative. So

to accomplish this simply just add slash (/path/to/image.png) and imagecropper willrecognize it at %WEBAPP_ROOT%/path/to/image.png. Action url relative local images arenot supported.


166
http://primefaces.prime.com.tr/en/images/schema.pnghttp://primefaces.prime.com.tr/en/images/schema.png

5/28/2018 java + ajax

167/373

3.34 ImageSwitch

Imageswitch component is used to enable switching between a set of images with somenice effects. ImageSwitch also provides a simple client side api for flexibility.

Info

Attributes


167

5/28/2018 java + ajax

168/373

Getting started with ImageSwitch

ImageSwitch component needs a set of images to display. Provide the image collection asa set of children components.

You need to use the ImageSwitch client side api to trigger the transitions. Example belowuses two span elements to navigate between the images.

Client Side API

Method Description

void previous() Switches to previous image.

void next() Switches to next image.

void startSlideshow(); Manually starts a slideshow.

void stopSlideshow(); Manually stops a slidehow.

Use the widgetVar to get the variable name of the client side widget.

Effect Speed

The speed is considered in terms of milliseconds and specified via the speed attribute.


168

5/28/2018 java + ajax

169/373

List of Effects

ImageSwitch supports a wide range of transition effects. Following is the full list, note thatvalues are case sensitive.

FadeIn

FlyInFlyOut

FlipIn

FlipOut

ScrollIn

ScrollOut

SingleDoor

DoubleDoor


169

5/28/2018 java + ajax

170/373

3.35 Inplace

Inplace provides easy inplace editing and inline content display. Inplace consists of twomembers, display element is the inital clickable label and inline element is the hiddencontent that"ll be displayed when display element is toggled.

Info

Attributes


170

5/28/2018 java + ajax

171/373

Getting started with Inplace

The inline component needs to be a child of inplace.

Custom Labels

By default inplace displays it"s first childs value as the label, you can customize it via thelabel attribute.

Effects

Default effect is fadeIn and fadeOut meaning display element will fadeOut and inlinecontent will be shown with fadeOut effect. Other possible effect is #slide", also effect speedcan be tuned with values #slow", #normal"and #fast".

Skinning Inplace

Style Class Applies

.pf-inplace-highlight Display element when hovered.

.pf-inplace-display Display element.

.pf-inplace-display-disabled Disabled display element.

.pf-inplace-content Inline content.


171

5/28/2018 java + ajax

172/373

3.36 InputMask

InputMask forces an input to fit in a defined mask template.

Info

Attributes


172

5/28/2018 java + ajax

173/373


173

5/28/2018 java + ajax

174/373

Getting Started with InputMask

InputMask is actually an extended h:inputText and usage is very similar. InputMask below

enforces input to be in 99/99/9999 date format.

Mask Examples


174

5/28/2018 java + ajax

175/373

3.37 Keyboard

Keyboard is an input component that uses a virtual keyboard to provide the input.Important features are the customizable layouts and skinning capabilities.

Info

Attributes


175

5/28/2018 java + ajax

176/373


176

5/28/2018 java + ajax

177/373

Getting Started with Keyboard

Keyboard is used just like a simple inputText, by default when the input gets the focus akeyboard is displayed.


177

5/28/2018 java + ajax

178/373

Built-in Layouts

There"re a couple of built-in keyboard layouts these are #qwerty", #qwertyBasic"and#alphabetic". For example keyboard below has the alphabetic layout.

Custom Layouts

Keyboard has a very flexible layout mechanism allowing you to come up with your ownlayout.

Another example;


178

5/28/2018 java + ajax

179/373

A layout template consists of built-in keys and your own keys. Following is the list of allbuilt-in keys.

back

clear

close

shift

spacebar

space

halfspace

All other text in a layout is realized as seperate keys so prime would create 5 keys as pr i m e. Use dash to seperate each member in layout and use commas to create anew row.

Keypad

By default keyboard displays whole keys, if you only need the numbers use the keypadmode.

ShowMode

There"re a couple of different ways to display the keyboard, by default keyboard is shownonce input field receives the focus. This is customized using the showMode feature whichaccept values #focus", #button", #both". Keyboard below displays a button next to the inputfield, when the button is clicked the keyboard is shown.

Button can also be customized using the buttonImage and buttonImageOnly attributes.


179

5/28/2018 java + ajax

180/373

Skinning Keyboard

Skinning keyboard is achieved with CSS. Following are three different skinning examples.

Aqua


180

5/28/2018 java + ajax

181/373

Homebrew


181

5/28/2018 java + ajax

182/373

Brownie


182

5/28/2018 java + ajax

183/373

3.38 Layout

Layout component features a highly customizable borderLayout model making it very easyto create complex layouts even if you"re not familar with web design.

Info

Attributes


183

5/28/2018 java + ajax

184/373

Getting started with Layout

Layout is based on a borderLayout model that consists of 5 different layout units which aretop, left, center, right and bottom. This model is visualized in the schema below;


184

5/28/2018 java + ajax

185/373

Full Page Layout

Layout has two modes, you can either use it for a full page layout or

Documents

java + ajax