Migration Guide

This is the migration guide to different PrimeFaces versions. Feel free to drop a comment to add any missing points. Please note that this is not a changelog as it only lists changes that may cause backward compatibility issues in your applications.

5.3 to 6.0

If manually included, the primefaces.js include must be changed to include core.js and components.js
The same also applies for the MenuRenderers of all PrimeFaces Layouts (before new layout versions will be released). Please change
@ResourceDependency(library="primefaces", name="primefaces.js")
to
@ResourceDependency(library="primefaces", name="core.js"), @ResourceDependency(library="primefaces", name="components.js")
Following components were migrated from PrimeFaces Extensions to PrimeFaces:
- InputNumber
- Timeline
- Knob
- KeyFilter
- ImportConstants
- ImportEnum
ImportConstants: className has been renamed to type
Search Expressions: SEF was refactored to skip unrendered components per default. If you would like to search for unrendered components in your application, please pass SearchExpressionFacade#Options#VISIT_UNRENDERED as option.
"last" facet for resources: before 6.0, it was possible to use the last facade inside any tag to add resources. We never implemented this feature so it was just a random feature as the facet always belongs to the direct parent. Please use the "last" facet only in h:head.
Dynamic Resource Loading: We reimplemented this feature, so that it will even work for other libraries like PrimeFaces Extensions. If you dynamically add components via Java code, please make sure you create the component via the #createComponent API:
ColorPicker colorPicker = (ColorPicker) FacesContext.getCurrentInstance().getApplication().createComponent(ColorPicker.COMPONENT_TYPE);
instead:
ColorPicker colorPicker = new ColorPicker();
Per default, DataTable now skips processing child components for some events like paging. If you need child processing, you can set skipChildren="false" on p:ajax.
GMap Rectangles: SouthWest and NorthEast was rendered the wrong direction. You probably need to switch the constructor parameters of LatLngBounds now.
ContextMenu: p:contextMenu must be placed AFTER the target component (e.g. datatable) in the xhtml now.
CommandButton: onclick will not be rendered if disable is set to false. This may cause unexpected behavior if the component is enabled on the client.

5.2 to 5.3

Fully backward compatible.

5.1 to 5.2

Fully backward compatible.

5.0 to 5.1

Support for literal texts in filterBy-sortBy expressions were deprecated in 5.0 and it is removed in 5.1. These attributes only work with value expression as in the past.
Deprecated chart components are removed.

4.0 to 5.0

Chart components are deprecated in favor of new generic chart component with new Chart API. Old chart components are still supported but will be removed in a future release.
ToolbarGroup deprecated, use left and right facets of toolbar instead. (Reverted back as of 5.0.1, both facets and toolbar groups will be supported instead)
Defining fields in sortBy-filterBy attributes is deprecated use a value expression instead.e.g. sortBy="#{user.name}" instead of sortBy="name"
DataTable frozen rows feature take an integer value instead of a collection from now on. This value defined how many rows from the start should be frozen.
LazyDataModel's filters parameter changed to Map<String,Object> instead of Map<String,String> as a requirement of the new Advanced Filtering Feature.
Dialog: appendToBody was removed in favor of appendTo="@(body)" to gain more flexibility
Watermark: forElement was removed in favor of for="@(yourSelector)"
Widgets must be referenced via "PF". e.g. PF('widgetVarName').show() instead of widgetVarName.show();
DataTable layout changed to table-layout:fixed.
PrimeFaces Push is reimplemented, PushContext is deprecated, use EventBus instead along with the new Push API.
ScrollPanel is reimplemented, usage is backward compatible however UI is slightly different.

3.5 to 4.0

MenuModel is rewritten and not backward compatible with the old version.
DataTable sortBy and filterBy expressions require the plain property name meaning "name" instead of "#{person.name}". Backward compatibility is maintained for expressions like "#{var.property}" but not for complex expressions.
FileUpload is reimplemented and it is backward compatible except "showButtons" option is removed. disabledSelection option of column, moved to DataTable, change is backward compatible and the option will be removed from column in a future release.
AutoComplete: removed process/global/onstart/oncomplete in favor of "p:ajax event="query" process/global/onstart/oncomplete"
Preferred way of accessing widgets is via PF('widgetVarName').show(), old way (e.g. widgetVarName.show()) is still supported and will be removed in a future version.

3.4 to 3.5

DateSelectEvent, ScheduleDateSelectEvent, ScheduleEntrySelectEvent classes are removed, use SelectEvent instead.
Column class in SortEvent and ColumnResizeEvent is replaced with UIColumn to support dynamic columns.
Scrollable and Resizable DataTable-TreeTable features are reimplemented.
DataTable and TreeTable no longer render cell container div element with classes ui-dt-c and ui-tt-c.
Sheet component is removed as it duplicated functionality of DataTable.
Galleria is reimplemented.
IE7 support is phased out.

3.3 to 3.4

Tree components dom structure has been reimplemented, if you have overwritten trees look and feel, check for compatibility issues.
RightClick event to open a contextMenu on datatable does not invoke rowSelect ajax behavior event anymore, use dedicated contextMenu event instead.
DataTable filtering requires filteredValue reference in backing bean, for backwards compatibility if this reference is not defined, filtering will work using view state however this is a fallback and will be removed in future releases.
Default event of overlayPanel is changed from mousedown to click.
DataTable widget's clearFilters client side method, now does an ajax call to clear the filters and update the table compared to just clearing filters on client side in prior versions.
Dialogs on IE7 have fixed widths to overcome IE7 auto width bugs. height attribute of selectCheckboxMenu is renamed to scrollHeight.
DataExporter's excludeColumns is replaced by exportable attribute of column. effectDuration of selectOneMenu renamed to effectSpeed.
partialSubmit is now false by default. It can be globally configured using primefaces.SUBMIT context parameter and components can override the global setting with provided partialSubmit attribute.
RequestContext is also available for non-ajax requests as well.

3.2 to 3.3

Scrollable datatable now requires the column width to be defined via width attribute of column instead of style attribute. Tiered and sliding type menus have their own components, name tieredMenu and slideMenu. readOnlyInpuText attribute of calendar is renamed to readOnlyInput.
Menu component’s position attribute is renamed to overlay as a boolean.

3.1 to 3.2

Growl now uses css to display the severity icons instead of the previous Icon attributes.
Password component sets feedback mode to false by default.
Incell editing datatable requires editable attribute to be set true.
ProgressBar’s oncomplete attribute is removed in favor of complete ajax behavior.
Incell editing datatable requires editable attribute to be set true.

3.0 to 3.1

Component referencing is now aligned with JSF Spec, if PrimeFaces cannot find a component, it will throw an exception. Since PrimeFaces 2.2 we’ve been logging an info message that component cannot be found and falling back to the client id. If you haven’t ignored these messages and fixed your code since 2.2, there won’t be a problem. If not, you need to update your component referencing with respect to findComponent specification.
primefaces.THEME_FORMS setting is removed in favor of plain css, if you need to reset the theme aware styles on input components, add a reset css instead.
Timeline is removed
Lightbox is reimplemented
Selectable tree nodes get pointer cursor

2.x to 3.0

Taglib namespaces are changed as;

Component events are now decoupled and implemented as ajax behaviors to improve flexibility. Read more at here. Common Listener and onUpdate attributes are now removed, an example is rating component;

2.x;

<p:rating value="#{ratingController.ratingValue}" rateListener="#{ratingController.handleRate}" update="messages"/>

3.x;*

<p:rating value="#{ratingController.ratingValue}"> <p:ajax event="rate" listener="#{ratingController.handleRate}" update="messages" /> </p:rating>

User's guide and Taglib docs(IDE completion) will provide all the available events of a component.

RequestContext now allows to execute javascript from backing beans (e.g. deciding to keep a dialog open or hide it), In 2.x this conditional javascript execution on callbacks like oncomplete are achieved via callback params, execute("script here") makes it very easy to implement the same compared to callback params. Note that callback params are still supported and will be in future as they are also used internally in PrimeFaces.
Tag/Attribute docs are available again in facelet taglib to take advantage of quick documentation via IDE code completion.
Aristo replaced Sam as the built-in theme, sam is available at theme gallery as a downloadable theme.

Component Changes

AccordionPanel

Reimplemented as a native PrimeFaces widget instead of using jQuery UI's accordion widget. fillSpace, autoHeight, event, collapsible and effect attributes are removed.
Multiple selection of tabs are now supported so activeIndex is a string instead of an integer. Provide a comma seperated list of indexes to activate multiple tabs. onTabShow attribute is added as a client side callback to execute when a tab is shown. onTabChange is also available as a callback when a tab is clicked but not yet shown. Passed parameters to the callbacks are changed.
Dynamic number of tabs are now support by providing a collection, use this feature instead of c:forEach and ui:repeat.
AccordionPanel is a naming container so make sure to you are aware of how search algorithm works when referencing components.
Event listeners are reimplemented as ajax behaviors.

AutoComplete

Reimplemented as a native PrimeFaces widget instead of using jQuery UI's autocomplete widget. Custom content support is available. panelStyle and panelStyleClass options are added to customize the overlay.
New dropdown mode places a button next to the input element to display all the available suggestions. CSS selectors are changed to align with general theming architecture.
Event listeners are reimplemented as ajax behaviors.

Calendar

Added timePicker functionality.
I18N has been externalized via PrimeFacesLocales, PrimeFaces does not provide the translations anymore.
Event listeners are reimplemented as ajax behaviors.

Carousel

Reimplemented as a native PrimeFaces widget instead of using YUI's carousel widget.
Header and Footer support is added.
CSS selectors are changed to align with general theming architecture.

Charts

Reimplemented using jqPlot canvas based library instead of YUI's flash based charting library.

chartSeries tag support is dropped instead of ChartModel API.

Added donut, ohlc, meter gauge, area and bubble charts.
Built-in polling is dropped in favor of Poll component.
Added built-in resizing, axis titles, text rotation, enhanced legend and other useful features.
Event listeners are reimplemented as ajax behaviors.

ColorPicker

Reimplemented with a jQuery plugin to drop YUI color picker.
Value only accepts hex value as String.
Added inline mode.

ConfirmDialog

Reimplemented as a native PrimeFaces instead of using jQuery UI dialog.

ContextMenu

Reimplemented as a native widget instead of wijmo.
ContextMenu has special integration with datatable, tree and treeTable.
Modality and Fade effect is always on.
Can be updated directly with ajax.

DataTable

Selection requires rowKeys compared to old problematic rowIndex approach. There is a new attribute called rowKey to define a row data identifier in your domain model, additionally SelectableDataModel is introduced to implement advanced and efficient selection.
Each cell is wrapped in a div with class .ui-dt-c, column style and styleClass apply to this wrapper.
DataTable has special integration with contextMenu.
Notable new features are column resizing and subtable for advanced grouping.
Lazy Loading has been greatly enhanced and showstopper bugs are fixed.
Event listeners are reimplemented as ajax behaviors.
New events are available to hook-in like page, sort and filter.
page attribute removed.

Dashboard

Event listeners are reimplemented as ajax behaviors.

GraphicImage

More secure way to stream dynamic content is implemented under the hood.

DragDrop

Event listeners are reimplemented as ajax behaviors.

Dialog

Reimplemented as a native PrimeFaces instead of using jQuery UI dialog.
Supports minimize and maximize.
Dynamic mode allows lazy loading of content until displaying for the first time.
Removed closeOnEscape option.
Event listeners are reimplemented as ajax behaviors.

Divider

Removed, use separator instead.

Fieldset

Event listeners are reimplemented as ajax behaviors.

FileUpload

Reimplemented using HTML5 widget instead of a flash based widget.
Mode option allows to choose between simple and advanced uploader.
Supports dragdrop from file system.
Changes in how upload restrictions are defined (e.g. allowTypes).

Galleria

Supports dynamic images via iteration.

GMap

Event listeners are reimplemented as ajax behaviors.
Support for circle and rectangles.

Growl

Displayed messages are removed in case a new message is added. Previously new messages are appended to the list of messages causing confusion.

IdleMonitor

Event listeners are reimplemented as ajax behaviors.

Inplace

Event listeners are reimplemented as ajax behaviors.

Layout

Reimplemented using a jQuery plugin.
LayoutUnit names are changed (e.g. top -> north, left -> west) size option is used instead of width and height to define unit dimension.
Support for nested layouts.
Event listeners are reimplemented as ajax behaviors.

Media

More secure way to stream dynamic content is implemented under the hood.

Menu

Reimplemented as a native widget instead of using wijmo.

Menubar

Reimplemented as a native widget instead of using wijmo.
autosubmenudisplay removed for now, might be added again in a future release.

MenuButton

Menu part reimplemented as a native widget instead of using wijmo.

Paginator

Reimplemented as a native widget instead of using yui.

Panel

Event listeners are reimplemented as ajax behaviors.

PickList

Custom content support is available.
Item visuals are improved.

RemoteCommand

Dynamic parameters can be passed into corresponding JavaScript function like remoteCommandName({ name1: 'value1', name2: 'value2' });

Slider

Event listeners are reimplemented as ajax behaviors.

Spinner

Reimplemented as a native PrimeFaces widget instead of using a jQuery plugin.
showOn option is removed.

Star Rating

Event listeners are reimplemented as ajax behaviors.

TabView Reimplemented as a native PrimeFaces widget instead of using jQuery UI's tabs widget. event and {}collapsible attributes are removed. New effects are added

Dynamic number of tabs are now support by providing a collection, use this feature instead of c:forEach and ui:repeat.
TabView is a naming container so make sure to you are aware of how search algorithm works when referencing components.
Event listeners are reimplemented as ajax behaviors.
Tabs can be closable.
Tabs can be disabled.
Passed parameters to the client side callbacks are changed.

ThemeSwitcher

Reimplemented as a native PrimeFaces widget instead of using jQuery UI's themeswitcher widget.
No need to require internet connection as themes are changed locally.
Used as a selectOneMenu.

Tooltip

Reimplemented as a native PrimeFaces widget instead of using a jQuery plugin.
Fixes to positioning and overlay issues.
Removed global tooltip and custom positioning.
More show/hide effects added.

Tree

Reimplemented as a native PrimeFaces widget instead of using YUI Tree widget.
Supports custom content in treeNodes.
Event listeners are reimplemented as ajax behaviors.
DragDrop feature is added.
Special contextMenu integration is available.

TreeTable

Reimplemented as a native PrimeFaces widget instead of using jQuery plugin.
Nodes are expanded/collapsed with ajax.
Event listeners are available as ajax behaviors.
Selection mode is added featuring single, multiple and instant selection.
Scrollable(horizontal and/or vertical) display.
Special contextMenu integration is available.
Resizable Columns.

PrimeFaces Mobile

TouchFaces has been rebranded as PrimeFaces Mobile and rewritten using jQuery Mobile.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly