Documentation‎ > ‎

Migrating from OpenFaces 2.0 EAP2

This document describes the changes that have to be made in your application for migrating to the final OpenFaces 2.0 version from the prerelease version OpenFaces EAP2.

Library Changes

  1. OpenFaces now requires Commons-Collections library (commons-collection.jar) as a runtime dependency.
  2. OpenFaces was upgraded to work with the new versions of the CSSParser and JFreeChart libraries.

IMPORTANT: since the new versions of these libraries have some incompatible changes, you have to replace the old versions of these libraries with the new ones when upgrading from OpenFaces EAP2 or earlier. Here's the list of files that must be updated with their new versions which can be found in OpenFaces distribution package:
  • For JFreeChart library, just update jfreechart.jar and jcommon.jar to the new versions.
  • For CSSParser library, remove the old ss_css2.jar file, and add cssparser.jar and sac.jar instead.

  You can find the new libraries in the lib directory of the OpenFaces distribution package.

API Changes

Component/Tag/ClassChange Description
all column tagsRenamed attributes: filterCellStyle/filterCellClass -> subHeaderStyle/subHeaderClass
<o:confirmation>Renamed attribute: captionText -> caption
<o:dataTable> and <o:treeTable>Renamed attributes:
allRecordsFilterName -> allRecordsFilterText,
emptyRecordsFilterName -> emptyRecordsFilterText,
nonEmptyRecordsFilterName -> nonEmptyRecordsFilterText
<o:dataTable> and <o:treeTable>Renamed attributes:
filterRowStyle -> subHeaderRowStyle,
filterRowClass -> subHeaderRowClass,
filterRowSeparator -> subHeaderRowSeparator
<o:eventActionBar>Renamed attributes:
backgroundTransparencyLevel -> backgroundTransparency,
backgroundIntensityLevel -> backgroundIntensity
<o:foldingPanel> and <o:tabbedPane>The value "ajax" of loadingMode attribute has been renamed to "ajaxLazy". The appropriate enumeration constant in theorg.openfaces.component.LoadingMode enumeration has also been renamed from AJAX toAJAX_LAZY.
<o:foreach>Renamed attribute: statusVar -> varStatus
<o:scrollPosition>The scrollX and scrollY attributes of <o:scrollPosition> tag were combined into one value attribute that should be specified as a binding to a property of type java.awt.Point.
<o:tabbedPaneItem>Renamed tag <o:tabbedPaneItem> -> <o:subPanel>
Renamed "tag" facet to "caption"
<o:tabbedPaneItems>Renamed tag <o:tabbedPaneItems> -> <o:subPanels>
<o:timetableEvent>Renamed attributes:
backgroundTransparencyLevel -> backgroundTransparency,
backgroundIntensityLevel -> backgroundIntensity
Confirmation, FoldingPanel, SidePanel, WindowRenamed getCaption/setCaption methods to getCaptionFacet/setCaptionFacet
SelectBooleanCheckboxMoved component class:
org.openfaces.component.input.SelectBooleanCheckbox ->
  1. Renamed class: FacesUtil -> Faces
  2. Replaced getRequestMapValue(String varName) method with var(String varName) method, which is more universal as it can fetch not just request-scope variables.
  3. Renamed method: getRequestParameterMapValue(String paramName) -> requestParam(String paramName).
  4. Removed getRequestParameterMapValueAsDate(String paramName) method. Its invocations should now be replaced with requestParam(String paramName, Date.class).
org.openfaces.component.table package classesThe following classes were renamed to match the appropriate tag names:
TableColumnGroup -> ColumnGroup,
TableColumn -> Column,
DynamicTableColumn -> DynamicColumn,
TableColumns -> Columns,
TableCell -> Cell,
TableRow -> Row .
The appropriate COMPONENT_TYPE and COMPONENT_FAMILY strings were changed accordingly.
Moved all classes from package: org.openfaces.component.action to package org.openfaces.component.command

Other changes:
  • Changed event attribute usage for <o:confirmation>, <o:popupMenu> and <o:ajax> (former <o:reloadComponents>) tags: now there shouldn't be "on" prefix in event names, e.g. you should use "click" instead of "onclick".
  • Renamed the dayTable parameter to timetable in oncreate and onedit event handlers of <o:customEventEditor> tag. See the Custom Event Editor section in the DayTable component documentation.
  • Renamed enumeration: org.openfaces.component.HorizontalAlignment -> org.openfaces.component.Side.
  • Renamed enumeration org.openfaces.component.timetable.HorizontalAlignment to org.openfaces.component.HorizontalAlignment and renamed its values as follows:
    • HorizontalAlignment.LEFT -> HorizontalAlignment.LEFT_OUTSIDE
    • HorizontalAlignment.RIGHT -> HorizontalAlignment.RIGHT_OUTSIDE
    • HorizontalAlignment.LEFT_EDGE -> HorizontalAlignment.LEFT
    • HorizontalAlignment.RIGHT_EDGE -> HorizontalAlignment.RIGHT
  • Renamed enumeration org.openfaces.component.timetable.HorizontalAlignment to org.openfaces.component.HorizontalAlignment and renamed its values as follows:
    • VerticalAlignment.TOP_EDGE -> VerticalAlignment.TOP
    • VerticalAlignment.BOTTOM_EDGE -> VerticalAlignment.BOTTOM
  • Changed values of verticalAlignment attribute of <o:eventPreview>, <o:eventArea> tags: "topEdge" -> "top", "bottomEdge" -> "bottom"
  • Changed values of horizontalAlignment attribute of <o:eventPreview>, <o:eventArea> tags: "left" -> "leftOutside", "right" -> "rightOutside", "leftEdge" -> "left", "rightEdge" -> "right".
  • The default values for the Spinner's minValue and maxValue attributes are now unspecified by default making it possible to enter a number without range restrictions by default. If you'd like to retain the old default range of 0..100, specify minValue="0" and maxValue="100"attributes explicitly.

Migrating to the New Ajax API

The component names changing affected both tag and attributes names. The JS function names have been also changed. The instructions below will help you to migrate to the new API:
1. Rename <o:reloadComponents> tag name to <o:ajax>.
2. Rename attributes and make changes in their values as follows:
Old attribute nameNew attribute nameValue syntax changeOld value exampleNew value example
componentIdsrenderspace delimited instead of comma delimited"totalInput, saveButton""totalInput saveButton"
submittedComponentIdsexecutespace delimited instead of comma delimited"form:window, form:dropDown""form:window form:dropDown"
action– (use listener instead)
eventeventevent name (without "on" prefix)"onclick""click"
disableDefault– (now works automatically)

Here's an example of migrating to the new tag API.
Old-style code:

<h:inputText id="input">
<o:reloadComponents event="onkeypress" componentIds="counter"
    submittedComponentIds="inputStep, checkboxIncrease" requestDelay="500"
public void incrementCounter() {

New-style code:

<h:inputText id="input">
<o:ajax event="keypress" render="counter"
    submit="inputStep checkboxIncrease" delay="500"
public void incrementCounter(ActionEvent actionEvent) {
3. Client-side API has also been changed to match the appropriate API in JSF 2.0 more closely. Replace O$.reloadComponents(componentIds, options) JS function invocations with O$.ajax.request(source, event, options) function with the following changes:
- The list of components to be reloaded that was formerly passed as the first parameter has changed its type from array to a space delimited string and it should now be passed inside of the options parameter object as a render field.
- The function now receives three parameters instead of two. The first parameter should now refer to the to the element that initiated the request, and the second parameter should refer the the event that has triggered the request. These first two parameters are optional and you can pass null values if required. The third parameter is the options array as it was before, though there are some option changes as outlined below.
- The submittedComponentIds parameter in options object has been renamed to the execute parameter and changed its type from an array to a space delimited string.
- The action parameter in options object is now replaced with the listener parameter, and the referred server-side method should receive one parameter of type javax.faces.event.ActionEvent like with the listener attribute of <o:ajax> tag mentioned above.

Here's an example of migrating to the new client-side API.

Old-style code:

<input type="button" onclick="O$.reloadComponents(['form:panel1'], {
action: 'MyBean.doAction',
submittedComponentIds: ['form:field1', 'form:field2']}); return false;"/>
public void doAction() {
// execute the action

New-style code:

<input type="button" onclick="O$.ajax.request(this, event, {
render: 'form:panel1',
listener: 'MyBean.doAction',
execute: 'form:field1 form:field2'}); return false;"/>
public void doAction(ActionEvent event) {
  // execute the action

Migrating to the New Filtering API
All of the filtering-related attributes were removed from <o:column> tag and should now be specified inside of one of the new filter tags, depending on type of the filter (formerly specified with the filterKind attribute). There's the new "subHeader" facet in <o:column> tag, where the filter tag should be placed. Here are the instructions that you can use to migrate to the new API:

1. Place the filter tag inside of the column's "subHeader" facet depending on a value of filterKind attribute and remove the filterKind attribute from column tag as follows:
filterKind valueTag name
"searchField" or no filterKind attribute<o:inputTextFilter>

2. Move all of the filtering-related attributes from the column tag to the filter tag and rename them as follows:
Old attribute nameNew attribute name

Here's an example of migrating to the new API.
Old-style code:

<o:column filterKind="dropDownField" filterExpression="#{product.category}" filterValues="#{Products.categories}">

New-style code:

<f:facet name="subHeader">
    <o:dropDownFieldFilter expression="#{product.category}" options="#{Products.categories}"/>

3. [Required if you are using custom data providing or filter criterion classes in Java code]
3.1. The type of the filterCriteria request-scope variable was changed from List to org.openfaces.component.filter.CompositeFilterCriterion. TheCompositeFilterCriterion class has the getCriteria() method that returns a list of criterion objects.

3.2. The EmptyFilterCriterion, NonEmptyFilterCriterion and TextFilterCriterion classes were replaced with a generic org.openfaces.component.filter.ExpressionFilterCriterion class, that is parameterized with filter condition to address different filtering scenarios (see the getCondition()and isInverse() methods). See the following items for detilas.

3.3. The usage getColumnId() method of TextFilterCriterion is now replaced with the usage of getExpressionStr() method of ExpressionFilterCriterion class, and it now returns filter's expression string instead of column id. Replacement of column Id with filter's expression string is required because a filter is not required to be placed inside of table's column now, and can even be placed outside of the table, hence filter's expression is now the filter's identifier when using the custom data providing mode. So besides replacing getColumnId() invocations with getExpressionStr(), be sure to specify the appropriate string (a-la column id) in the filter's expression attribute.

3.4. The usage of getText() method of TextFilterCriterion is now replaced with usage of getArg1() method. Unlike the getText() method which returns java.lang.String, getArg1() returns java.lang.Object to allow non-string comparisons, so you should convert the result of invoking the getArg1() method using the toString() method to match the old behavior.

3.5. The checks for instances of EmptyFilterCriterion and NonEmptyFilterCriterion classes should now be replaced with checks of the ExpressionFilterCriterion's condition and inverse properties. The condition is an enumeration of org.openfaces.component.filter.FilterCondition type, which distinguishes between different types of filtering, and in particular the value of FilterCondition.EMPTY means that empty records should be accepted (and this is a replacement for checking the EmptyFilterCriterion class instance), and if isInverse() method returns true at the same time this is the case for filtering the non-empty records (and this is a replacement for checking the NonEmptyFilterCriterion class instance).

Here's a simple example of how the appropriate code is to be changed as a result of this change.
Old-style code:

<o:column id="name" filterKind="searchField">
List<ColumnFilterCriterion> criteria = (List) Faces.var("filterCriteria");
for (ColumnFilterCriterion criterion: criteria) {
String columnId = criterion.getColumnId();
String searchString = ((TextFilterCriterion)criterion).getText();

New-style code:
<f:facet name="subHeader">
    <o:inputTextFilter expression="name"/>
CompositeFilterCriterion criteria = Faces.var("filterCriteria", CompositeFilterCriterion.class);
for (FilterCriterion c: criteria.getCriteria) {
ExpressionFilterCriterion criterion = (ExpressionFilterCriterion) c;
String columnId = criterion.getExpressionStr();
String searchString = criterion.getArg1().toString();

Please see the "Handling Large Datasets" section in the DataTable documentation for the general description of the new API.

4. [Optional] Drop-down field filters are now configured to provide input suggestions by default, though you can turn this behavior off if you'd like the filters to behave exactly as before. This can be done by declaring the following attributes on the <o:dropDownFieldFilter> tag: suggestionMode="none" autoComplete="false"

5. [Optional] Input text filters now automatically perform filtering as the user types in the field. This behavior can be turned off to match the old behavior by specifying the following attribute for <o:inputTextFilter> tag: autoFilterDelay="-1"

6. [Optional] The default filtering condition for non-string values is now "equals" instead of "contains". If you'd like to retain the old behavior of always searching by substring anyway (e.g. if you'd like for filtering integer values "1" to match both "1" and "10"), declare the condition="contains" attribute on the appropriate filter tags.