This document describes how to upgrade your application from QuipuKit 1.6.2 to OpenFaces 2.0.

General

• OpenFaces 2.0 requires Java version 5 or higher.
• OpenFaces 2.0 requires JSF 1.2.x (Mojarra or MyFaces).
• As with QuipuKit 1.x, OpenFaces can be used with JSP and Facelets. Though if you are working with Facelets, please ensure that you are using a version 1.1.14 or higher.
• Support for Ajax4jsf framework of versions that existed prior to integrating Ajax4jsf into RichFaces has been dropped. Use RichFaces 3.3.0 or later instead of Ajax4jsf.
• Support for RichFaces library earlier than version 3.3.0 has been dropped. Upgrade to RichFaces 3.3.0 or later.
• Suppor for JBoss Seam framework of versions earlier than 2.0 has been dropped.
• OpenFaces 2.0 comes as a single Jar file named openfaces.jar . License jar file that was required for QuipuKit 1.x is not required anymore and should be removed. Other jar dependencies remained the same (see the Installation and Configuration section in OpenFaces Developer's Guide).

Changes Dependent on the New Product Name

Since version 2.0 QuipuKit has been renamed to OpenFaces. Hence all of the names that depended on the old product name must be changed. Here's the full list of changes that might require updates in your application:

• Renamed the root package from teamdev.jsf to org.openfaces. Therefore you need to update paths to imported packages in your code appropriately. Please also pay special attention to renaming the resource filter class in web.xml from teamdev.jsf.util.ResourceFilter to org.openfaces.util.ResourceFilter . The teamdev.jsf.portlet.QuipuKitPortlet class for configuring portlet applications has also been renamed to org.openfaces.portlet.OpenFacesPortlet.
• Changed prefixes of component-type and component-family strings from teamdev.jsf to org.openfaces .
• The prefixes for application parameters specified in web.xml file were changed from teamdev.jsf to org.openfaces .
• The /qk_internalResource/* resource mapping that can optionally be specified in web.xml for performance optimization has been renamed to /openFacesResources/* .
• Changed validation message key prefixes for message bundles from teamdev.jsf to org.openfaces .
• Namespace for OpenFaces component tags was changed from http://teamdev.com/quipukit  to http://org.openfaces/  . Although it is not required to change the namespace prefix in your page files, we recommend to use the "o" prefix when using OpenFaces tags, for example <o:dataTable>.

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:

Removal of Deprecated API

In version 2.0 we have removed the API that was marked as deprecated in QuipuKit 1.x. Below is the list of changes, with the description of how to retain the appropriate functionality using the new API.

The list of removed attributes, and the appropriate replacements:

The list of removed tags and their replacements:

Renamed, Moved API

Moved/renamed packages:

Moved/renamed classes:

Renamed tags:

Renamed attributes. These are applicable to both property names in the actual component classes and the appropriate attribute names.

DataTable and TreeTable

Renamed methods:

Client-Side API Changes

The New O$(id) Function

OpenFaces 2.0 introduces a new JavaScript function named "O$(id)" (capital letter O and a dollar sign) that locates a DOM element by its identifier. Locating element by id is a very common scenario, where the "document.getElementById(id)" function is usually invoked. The O$(id) function works in the same way and can be used as a short replacement for this expression. See the documentation for usage example.

Unified Client-Side API

In QuipuKit 1.x each method of component's client-side API was available in two ways:

• As a "global" function prefixed with "q_" and receiving component identifier as the first parameter, for example q_showPopupLayer(popupId);
• As a component instance method without a prefix and component id parameter, for example popup.show().

In OpenFaces 2.0, the first way of using the component's client-side API is not available anymore. Therefore you should replace invocations of all "global" functions, the functions that start with the "q_" prefix, with usages of the appropriate instance methods. We recommend using the new O$(id) function to simplify this process. Here are some examples of replacing the old invocations with the new ones:

Client-Side Validation Functions

Validation functions have undergone a change similar to the one described above. The notation for validation function names was changed. The "q_" prefix was removed, and all functions were placed into the "O$" namespace instead. That means that now you should invoke such functions as methods of the "O$" variable. Here are the examples:

Migrating to the New Filtering API

All of the filtering-related attributes were removed from <o:column> (former <q:column>) tag and should now be specified inside of one of the new filter tags, depending on type of the filter (formerly specified with thefilterKind 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:

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

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:

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

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 genericorg.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 ifisInverse() 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:

<o:column>

    <f:facet name="subHeader">

        <o:inputTextFilter expression="name"/>

    </f:facet>

...

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.

The q_refreshTable and q_refreshTreeTable Functions

In OpenFaces 2.0, the q_refreshTable and q_refreshTreeTable functions were removed in favor of the new API that allows reloading any components and provides a wider set of possibilities. OpenFaces 2.0 introduces the new ReloadComponents component that allows reloading one or more components with Ajax. This component provides programmatic access to its functionality using the O$.reloadComponents function. q_refreshTable and q_refreshTreeTable function invocations should be replaced with O$.ajax.request invocations as shown below.

The same replacements are applicable for the q_refreshTreeTable function. See the documentation for the ReloadComponents component for more information.

API Changes

Other

<q:confirmation
   closeButtonImageUrl="close.gif"
   ...
/>

<o:confirmation ...>
   <o:captionArea>
     <o:closeWindowButton imageUrl="close.gif"/>
   </o:captionArea>
</o:confirmation>

<q:foldingPanel
  collapsedImageUrl="collapsed.gif"
  expandedImageUrl="expanded.gif"
  buttonHint="Click here"
  buttonPlacement="left" ...>
   ...
</q:foldingPanel>

<o:foldingPanel ...>
   <o:captionArea alignment="left">
     <o:expansionToggleButton
       collapsedImageUrl="collapsed.gif"
       expandedImageUrl="expanded.gif"
       hint="Click here"/>
   </o:captionArea>
   ...
</o:foldingPanel>