Documentation‎ > ‎

Migrating from QuipuKit 1.6.2

This document describes how to upgrade your application from QuipuKit 1.6.2 to OpenFaces 2.0. If you need to migrate from QuipuKit 1.6.2 to a later version of OpenFaces, then you should follow the appropriate migration instructions section for each major version, after following these instructions. You can see the migration instructions for OpenFaces 3.0 in the OpenFaces 3.0 Release Notes document.

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 toorg.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:
  • 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.


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:

Component

Old Attribute Name

Replacement

HintLabel

title

hint

DataTable, TreeTable

rowOnclick, rowOndblclick, rowOnmousedown, rowOnmousemove, rowOnmouseout, rowOnmouseover, rowOnmouseup

Place <o:row onclick="..."/> inside of your <o:dataTable> or <o:treeTable> tag (applicable for all listed events).

TabSet

submitOnChange

Use onchange attribute with manual form submission code, e.g. onchange="document.forms[0].submit()"; or use the <o:reloadComponents> tag to introduce Ajax interaction for the onchange event



The list of removed tags and their replacements:

Tag

Replacement

<q:cellStyle>

Rename all <q:cellStyle> tags to <o:cell> and enclose them into empty <o:row> tags with no additional attributes.

<q:rowStyle>

<o:row>



Renamed, Moved API

Moved/renamed packages:

Old Package Name

New Package Name

teamdev.jsf.component.ajaxsettings

org.openfaces.component.ajaxsettings

teamdev.jsf.component.calendar.daterange

org.openfaces.component.calendar

teamdev.jsf.component.confirmation

org.openfaces.component.window

teamdev.jsf.component.chart.impl.view

org.openfaces.component.chart

teamdev.jsf.component.chart.impl.model

org.openfaces.component.chart

teamdev.jsf.component.chart.impl.event

org.openfaces.component.chart

teamdev.jsf.component.chart.view

org.openfaces.component.chart

teamdev.jsf.component.datatable

org.openfaces.component.table

teamdev.jsf.component.datechooser

org.openfaces.component.input

teamdev.jsf.component.dropdownfield

org.openfaces.component.input

teamdev.jsf.component.dynamicImage

org.openfaces.component.output

teamdev.jsf.component.focus

org.openfaces.component.util

teamdev.jsf.component.foldingpanel

org.openfaces.component.panel

teamdev.jsf.component.graphicText

org.openfaces.component.output

teamdev.jsf.component.hintlabel

org.openfaces.component.output

teamdev.jsf.component.message

org.openfaces.component.validation

teamdev.jsf.component.inputText

org.openfaces.component.input

teamdev.jsf.component.inputTextarea

org.openfaces.component.input

teamdev.jsf.component.loadbundle

org.openfaces.component.util

teamdev.jsf.component.popuplayer

org.openfaces.component.window

teamdev.jsf.component.scrollposition

org.openfaces.component.util

teamdev.jsf.component.spinner

org.openfaces.component.input

teamdev.jsf.component.suggestionField

org.openfaces.component.input

teamdev.jsf.component.tabbedpane

org.openfaces.component.panel

teamdev.jsf.component.tabset

org.openfaces.component.select

teamdev.jsf.component.treetable

org.openfaces.component.table

teamdev.jsf.component.twolistselection

org.openfaces.component.select



Moved/renamed classes:

Old Class Name

New Class Name

teamdev.jsf.component.chart.impl.model.PlainModelImpl

org.openfaces.component.chart.PlainModel

teamdev.jsf.component.chart.impl.model.PlainSeriesImpl

org.openfaces.component.chart.PlainSeries

teamdev.jsf.component.chart.impl.model.TupleImpl

org.openfaces.component.chart.Tuple

teamdev.jsf.component.dropdown.DropDownField

org.openfaces.component.input.DropDownField

teamdev.jsf.component.dropdown.HorizontalAlignment

org.openfaces.component.Side

teamdev.jsf.component.message.FloatingIconMessage

org.openfaces.component.validation.FloatingIconMessage

teamdev.jsf.component.output.HintLabel

org.openfaces.component.output.HintLabel

teamdev.jsf.component.popuplayer.Confirmation

org.openfaces.component.window.Confirmation

teamdev.jsf.component.popuplayer.ButtonType

org.openfaces.component.window.ButtonType

teamdev.jsf.component.util.LoadingMode

org.openfaces.component.LoadingMode

teamdev.jsf.component.util.FacesUtil

org.openfaces.util.FacesUtil

teamdev.jsf.renderkit.validation.validator.ClientValidationEnum

org.openfaces.component.validation.ClientValidationMode



Renamed tags:

Old Tag Name

New Tag Name

<q:customValidator>

<o:validateCustom>

<q:emailValidator>

<o:validateEmail>

<q:equalValidator>

<o:validateEqual>

<q:regExpValidator>

<o:validateRegex>

<o:tabbedPaneItem>

<o:subPanel>

<o:tabbedPaneItems>

<o:subPanels>

<q:urlValidator>

<o:validateUrl>



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

DataTable and TreeTable

Component/Tag

Old Attribute Name

New Attribute Name

Chart

style

textStyle

Confirmation

captionText

caption

Confirmation

invokerId

for

Confirmation

invokerEventName

event

Confirmation

middleAreaClass

contentClass

Confirmation

middleAreaStyle

contentStyle

Confirmation

rolloverMiddleAreaClass

rolloverContentClass

Confirmation

rolloverMiddleAreaStyle

rolloverContentStyle

DataTable and TreeTable

allRecordsFilterName

allRecordsFilterText

DataTable and TreeTable

emptyRecordsFilterName

emptyRecordsFilterText

DataTable and TreeTable

nonEmptyRecordsFilterName

nonEmptyRecordsFilterText

DataTable and TreeTable

filterRowStyle

subHeaderRowStyle

DataTable and TreeTable

filterRowClass

subHeaderRowClass

DataTable and TreeTable

filterRowSeparator

subHeaderRowSeparator

GraphicText

style

textStyle

PopupLayer, Confirmation

closeOnOuterClick

hideOnOuterClick

TwoListSelection

allowSorting

sortingAllowed

TwoListSelection

allowItemsOrdering

reorderingAllowed

all column tags

filterCellStyle

subHeaderStyle

all column tags

filterCellClass

subHeaderClass



Renamed methods:

Class

Old Method Name

New Method Name

org.openfaces.component.chart.PlainSeries

setId

setKey

org.openfaces.component.chart.PlainSeries

setSeriesKey

setKey

org.openfaces.component.chart.PlainSeries

getSeriesKey

getKey

org.openfaces.component.chart.Series

getId

getKey



Component/Tag/Class

Change Description

<o:confirmation>

Changed event attribute usage for <o:confirmation> tag: now there shouldn't be "on" prefix in event names, e.g. you should use "click" instead of "onclick".

<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 to AJAX_LAZY.

<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"

Confirmation, FoldingPanel

Renamed getCaption/setCaption methods to getCaptionFacet/setCaptionFacet

org.openfaces.util.FacesUtil

  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).
Classes in org.openfaces.component.table package (formerteamdev.jsf.component.datatable) classes

The 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.



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 newO$(id) function to simplify this process. Here are some examples of replacing the old invocations with the new ones:

Old-Style Invocation

New-Style Invocation

q_showPopupLayer("form:popup1")

O$("form:popup1").show()

q_showPopupLayerAtXY("form:popup1", 150, 100)

O$("form:popup1").showAtXY(150, 100)

q_isTableSelectionEmpty("form:dataTable1")

O$("form:datatable1").isSelectionEmpty()



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:

Old-Style Invocation

New-Style Invocation

q_validate(myComponent)

O$.validate(myComponent)

q_validateForm(document.forms[0])

O$.validateForm(document.forms[0])



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:

filterKind value

Tag name

"searchField" or no filterKind attribute

<o:inputTextFilter>

"dropDownField"

<o:dropDownFieldFilter>

"comboBox"

<o:comboBoxFilter>



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

Old attribute name

New attribute name

filterExpression

expression

filterValue

value

filterValues

options

filterPromptText

promptText

filterPromptTextStyle

promptTextStyle

filterPromptTextClass

promptTextClass



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 replacinggetColumnId() 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 oforg.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 theEmptyFilterCriterion 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 thecondition="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.

Old-Style Invocation

New-Style Invocation

Notes

q_refreshTable("form:dataTable1")

O$.ajax.request(this, event, {render:"form:dataTable1"})

Refreshing the table without additional options

q_refreshTable("form:dataTable1",

["form:field1","form:field2"])

O$.ajax.request(this, event, {render:"form:dataTable1",

execute: "form:field1 form:field2"})

Refreshing the table with submitting data for two additional form fields

q_refreshTable("form:dataTable1",

["form:field1","form:field2"],

"MyBean.action1")

O$.ajax.request(this, event, {render:"form:dataTable1",

execute: "form:field1 form:field2",

listener: "MyBean.action1Listener"})

Refreshing the table with submitting data for two additional form fields and invoking the "MyBean.action1Listener" server action. Note that the action listener function action1Listener should take the additional ActionEvent parameter, so it'll be declared like this:

public void action1Listener(ActionEvent event) {

  // execute the action

}



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

API Changes

Component

Change Description

Confirmation

The q_runConfirmedFunctionByName/runConfirmedFunctionByName client-side function was removed. Use runConfirmedFunction function instead and pass an appropriate closure (aka anonymous function) there instead.



Other

Component/Attribute

Note

All components

All methods that received ValueBinding/MethodBinding arguments now receive ValueExpression/MethodExpression

Calendar, FoldingPanel, TabbedPane, TabSet

These components have been made focusable by default in OpenFaces 2.0. You can make them non-focusable as they were in QuipuKit 1.x by specifying the focusable="false" attribute.

Calendar, DateChooser

The showWeekNumber and weekText attributes were removed because of their counterintuitive display and meaning. An alternative implementation can be expected in future versions if needed.

Confirmation

The event attribute of <o:confirmation> tag now defaults to "onclick", so you can remove it for declarations where it equals to the default value.

Confirmation

Confirmation components that previously were declared without the for (former name is invokerId) attribute for explicit usage via JavaScript should now include the explicit standalone="true" attribute declaration. Otherwise these components will automatically be attached to the parent component.

Confirmation

closeButtonImageUrl and showCloseWindowButton attributes were replaced with a notion of caption areas that is a generic way of customizing caption buttons and is used in FoldingPanel and Window components in addition to the Confirmation component. Here's an example of migrating to the new API:

Old-style code:

<q:confirmation

  closeButtonImageUrl="close.gif"

  ...

/>

New-style code:

<o:confirmation ...>

  <o:captionArea>

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

  </o:captionArea>

</o:confirmation>


The new <o:closeWindowButton> tag also provides additional attributes for customizing other aspects of button's appearance such as a style and a hint. The window closing button is displayed by default, but you can hide it just by placing an empty<o:captionArea/> tag inside of <o:confirmation> tag. See the documentation for Confirmation component for more details about customizing the caption buttons.

FoldingPanel

Adding StateChangeListener to FoldingPanel doesn't trigger form submission on expanding/collapsing FoldingPanel anymore. Use onstatechange event with manual form submission script if necessary.

FoldingPanel

Changed the way of customizing toggle button's image and hint. Now there's the possibility to specify so called caption areas, which allows specifying additional buttons in the panel's caption. As a part of this, a new tag for the toggle button was created:<o:expansionToggleButton>, which now includes all of the image URL properties that were previously specified through <q:foldingPanel> (names were unchanged), the hint attribute instead of foldingPanel's buttonHint attribute and other new attributes. Usages of <q:foldingPanel> tag's buttonPlacement attribute should be replaced with using the alignment attribute of <o:captionArea> tag. Note that if you don't need customization of the toggle button itself, you should include an empty declaration of the <o:expansionToggleButton/> tag into the <o:captionArea> tag for the area to be non-empty. Here's an example of migrating to the new API:

Old-style code:

<q:foldingPanel

 collapsedImageUrl="collapsed.gif"

 expandedImageUrl="expanded.gif"

 buttonHint="Click here"

 buttonPlacement="left" ...>

  ...

</q:foldingPanel>

New-style code:

<o:foldingPanel ...>

  <o:captionArea alignment="left">

<o:expansionToggleButton

   collapsedImageUrl="collapsed.gif"

   expandedImageUrl="expanded.gif"

   hint="Click here"/>

  </o:captionArea>

  ...

</o:foldingPanel>

See FoldingPanel documentation for a detailed description of how to use caption areas and the <o:expansionToggleButton> tag.

ScrollPosition

Changed the way of specifying the "for" attribute to be consistent with other components. It should now be specified in the same way as a "for" attribute of <h:outputLabel>, <h:message> or <o:confirmation> components. Previously the whole tree was searched for the short id specified in this attribute. Now it's either an "absolute" id if it starts with a colon symbol, or a "relative" id otherwise. See ScrollPosition documentation for details.

Validation

The <q:message> and <q:messages> tags were removed. Since they are identical in API with the standard counterparts, you just need to replace them with the standard <h:message> and <h:messages> tags respectively.

Validation

Validator IDs were renamed to match the traditional convention:

org.openfaces.CustomValidator -> org.openfaces.Custom

org.openfaces.EmailValidator -> org.openfaces.EMail

org.openfaces.EqualValidator -> org.openfaces.Equal

org.openfaces.RegexValidator -> org.openfaces.RegularExpression

org.openfaces.URLValidator -> org.openfaces.URL


The following message bundle keys were amended to match the updated validator names:

org.openfaces.EmailValidatorMessage -> org.openfaces.EMailValidatorMessage

org.openfaces.RegExpValidatorMessage -> org.openfaces.RegexValidatorMessage


Comments