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 tag-project-auto-convert

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.

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.