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 NameSince 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- OpenFaces now requires Commons-Collections library (commons-collection.jar) as a runtime dependency.
- 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 APIIn 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 APIMoved/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 TreeTableComponent/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 | - Renamed class: FacesUtil -> Faces
- Replaced getRequestMapValue(String varName) method with var(String varName) method, which is more universal as it can fetch not just request-scope variables.
- Renamed method: getRequestParameterMapValue(String paramName) -> requestParam(String paramName).
- 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 ChangesThe New O$(id) FunctionOpenFaces 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 APIIn 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 FunctionsValidation 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 FunctionsIn 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.Customorg.openfaces.EmailValidator -> org.openfaces.EMailorg.openfaces.EqualValidator -> org.openfaces.Equalorg.openfaces.RegexValidator -> org.openfaces.RegularExpressionorg.openfaces.URLValidator -> org.openfaces.URL
The following message bundle keys were amended to match the updated validator names:org.openfaces.EmailValidatorMessage -> org.openfaces.EMailValidatorMessageorg.openfaces.RegExpValidatorMessage -> org.openfaces.RegexValidatorMessage
|
|
