Primefaces 11 Migration
Breaking Changes from version 7 to 11
Unfortunately, Primefaces made some breaking changes in its latest versions:
UI components have been removed or were deprecated.
UI components have different CSS classes.
Attributes of UI components have been removed, moved, renamed or have a different behavior.
Java API have been removed or changed.
This means that your user interfaces are most likely broken.
For a complete list of all changes see Primefaces 11 Migration Guide
How to avoid migration pain
Use the provided standard themes freya-ivy or serenity-ivy.
Use as few own CSS rules as possible.
Use as few different Primefaces components as possible.
Project Converter
To mitigate the migration pain, we have built a project converter that fixes the most important of the breaking changes.
To start the converter select a project in your Designer and press the context menu Convert. Then select Convert project to use latest Primefaces version and press the Next > and then the Convert button. Review the applied changes in the conversion log or the Git Staging view.
The project converter will fix most common broken Java APIs in your Java, Process (IvyScript) and Data Class files. It also fixes renamed UI components and attributes.
However, some attributes have been moved from one UI component to a child component or have a different behavior. Those changes cannot be fixed automatically. Check your WebTests or manually test your UI components to find problems and then fix them manually.
Common Manual Migration Tasks
Component p:layout removed
See Primefaces 10 Migration Notes - Layout
Use pure CSS instead (e.g. with the Primefaces Grid System). Or, the similar component from Primefaces Extensions pe:layout.
Component p:themeSwitcher removed
See Primefaces 10 Migration Notes - ThemeSwitcher
Use a p:selectOneMenu
to switch the theme. See example provided in the link above.
Component pe:gravatar removed
See Primefaces Extension 10 Migration Notes
Instead of pe:gravatar
use new Primefaces component p:gravatar
Sorting and filtering of component p:dataTable and p:treeTable
See Primefaces 10 Migration Notes - DataTable
Sorting and filtering of of component p:dataTable
and p:treeTable
has been changed.
Instead of defining the attributes sortField
, sortOrder
, sortFunction
and filterBy
on the p:dataTable
component
you now have to define them on the p:column
component.
Example:
Primefaces 7:
<p:dataTable var="person" value="#{data.persons}" sortField="#{person.name}" sortOrder="ASCENDING" filteredBy="#{person.surname}"> <p:column><h:outputText value="#{person.name}"/></p:column> <p:column><h:outputText value="#{person.surname}"/></p:column> </p:dataTable>
Primefaces 11:
<p:dataTable var="person" value="#{data.persons}"> <p:column field="#{person.name}" sortOrder="ASCENDING"><h:outputText value="#{person.name}"/></p:column> <p:column sortBy="#{person.surname}" filterBy="#{person.surname}"><h:outputText value="#{person.surname}"/></p:column> </p:dataTable>
In rare situations, it is not possible to set the filter and sort attributes on the p:column
component.
In this case you can use the attributes sortBy
and filterBy
on the p:dataTable
component.
However, these attributes need to be bound to objects of type SortMeta
and FilterMeta
.
The following example shows how to use them:
<p:dataTable sortBy="#{bean.sortById}" id="table" value="#{bean.dataModel}" var="table" > ... <p:dataTable />@ManagedBean @ViewScoped public class Bean { private SortMeta buildSortMeta(String field, boolean isSortDescending) { return SortMeta.builder() .field(field) .order(isSortDescending ? SortOrder.DESCENDING : SortOrder.ASCENDING) .build(); } public SortMeta getSortById() { return buildSortMeta("ID", false); } }
Similar for p:treeTable
.
Attribute columns of p:panelGrid
Either attribute columns
must be set on a p:panelGrid
or a p:row
child component must be defined.
Component Carousel and Galeria
See Primefaces 11 Migration Notes - Carousel and Galeria
Most of the attributes have been removed or renamed. See Carousel or Galeria documentation for details.
Java class TreeUtils removed
See Primefaces Forum
Copy the source code from the original TreeUtils class into your project.
Components have different CSS classes
Some components have new CSS classes. You may need to adjust your CSS rules and WebTests if they select a component by its CSS classes.
Font-Awesome upgraded to 6.1.0
See Fontawesome 4 Migration Notes
You should use the new CSS class fa-solid
instead of fa
.
Example:
Font-Awasome 4.7
<i class="fa fa-camera-retro">
Font-Awesome 6.1
<i class="fa-solid fa-camera-retro">
However, because we provide a compatibility library the old fa
class should still work.
JQuery icons removed
The JQuery icons (CSS classes ui-icon-*
) are no longer supported.
Instead, use icons of the supported icon libraries:
Rendering time changed
Some components now need more time to render. You may need to adjust the timeout settings of your WebTests.
ChartJS library upgraded
The integrated ChartJS library has been upgraded. If you have used additional ChartJS plugins you may need to upgrade them as well.