TeamDev Support : Document List - OpenFaces

What's New in Nightly Builds

forum-admin@teamdev.com — Tue, 01 Dec 2009 18:35:16 GMT

This document summarizes the changes that haven't been released yet, but are already available in the nightly builds. Please note that we're updating this document when committing the appropriate changes to SVN, so you might need to wait for the nearest successful nightly build to see the recent changes added to this document. You can also follow the OpenFaces_JSF Twitter channel to receive notifications on the most notable new features as they are being implemented.

The nightly builds are usually published by 5:00am GMT+0 if successful.

Build number is not available on the site yet, though you can find it in openfaces.jar/META-INF/manifest.mf file – see the Build-Label field.

New Components

SelectOneMenu -- an extended version of the standard SelectOneMenu component with autocompletion support.
LevelIndicator -- a component that shows a numeric value in graphic style, similar to the LED volume meter and resource meter used in Windows Task Manager.

Enhancements

Ajax framework:
- Added AjaxRequest class that provides programmatic aspects for various aspects of OpenFaces Ajax requests.
- It's now possible to load application-specific data with Ajax requests. See the "Loading Data with Ajax" sections in "Ajax Framework" and "Ajax Component" documentation pages.
- It's now possible to specify components for reloading programmatically during the Ajax request. See the "The AjaxRequest Class" section in the "Ajax Framework" documentation.
- The render attribute of <o:ajax> is not required anymore, which simplifies the use cases when performing Ajax request just for loading data from the server.
- Added a new executeRenderedComponents attribute that allows skipping the "execute" lifecycle phases for components specified in the render attribute of such components as <o:ajax>, <o:commandButton>, etc.
- It's now possible to reload components in different forms simultaneously using the "absolute" id syntax, for example render=":form1:out1 :form2:out2".
Chart:
- Added interactive selection support for charts. It can be enabled by adding the <o:chartSelection> tag <o:chart> tag turns on an ability for interactive chart item selection. This means that a user can select a chart item (sector in pie charts, bar in bar charts, or shape in line charts) by clicking on it, and application developer has an ability to detect the selected item and optionally update the dependent content with Ajax on selection change. By default, chart's context menu have Save and Print menu item included that allows to download chart's image or easily display print dialog in order to print the chart's content.
- Now it is possible to add custom popups to the charts to allow displaying extended content for each chart item, which can be useful for example when implementing a drill down functionality. Custom item popups can be enabled by specifying the <o:chartPopup> tag as a child of chart view tags. As a container, the ChartPopup lets you place any kind of JSF components inside it to build its content. You can use the "sector" (for pie charts) and "point" (for bar and line charts) request scope variables when defining the child components of <o:chartPopup> tag to specify the item-dependent content.
- Implemented built in context menu support. Now it is possible to enable the standard chart context menu to allow performing useful actions on chart, like saving and printing the chart. The context menu support can be turned on by adding the <o:chartMenu> tag inside of the <o:chart> tag. It is possible to customize the content and appearance of the standard menu by customizing the <o:chartMenu> tag's attributes and child tags.
- Line Area Fill - Line charts has an advanced customization that enables an ability to fill the area below the line with a gradient or a flat color. This functionality can be enabled by adding either <o:gradientLineAreaFill> or <o:solidLineAreaFill> tag as a child of <o:lineChartView> tag. The <o:gradientLineAreaFill> tag is used to fill the area with a gradient from current line's color to the chart's background color.
- Added support for 3D mode in charts. 3D mode can be turned on/off using enable3D attribute of corresponding chart view tag.
- Added domain and range markers support for Bar and Line chart types. <o:marker> tag can be added as a child tag to <o:domainMarkers> and <o:rangeMarkers> tags. These tag should be added as a child tags of corresponding chart view tag.
- It's now possible to customize labels position for Bar and Line chart types.It can be done using defaultLabelsPosition, positiveLabelsPosition and negativeLabelsPosition attributes of <o:barChartView> and <o:lineChartView> tags.
- It's now possible to turn off gradients in Bar charts using showGradient attribute of <o:barChartView> tag
- Added support for bars' gradient customization. Gradient parameters allows customizing how the "shiny" part of the bar gradient is displayed. This is customized with three attributes: g1WhitePosition, g2FullIntensityPosition, g3LightIntensityPosition. These attributes should be specified as numbers in range [0..1], which correspond to the position of the appropriate gradient portion.
- Added support for shadow customization for both Bar and Pie chart views.
- Added support for outlines customization for Bar and Line chart types. Use defaultOutlineStyle and outlines attributes of <o:barChartView> or <o:lineChartView> tags.
- It's now possible to customize line styles for Line chart view using defaultLineStyle or lineStyles attributes of <o:lineChartView> tag.
Command components:
- Added onajaxstart/onajaxend/onerror events for CommandButton, CommandLink, CaptionButton, MenuItem and selection tags (<o:singleRowSelection>, <o:multipleNodeSelection>, etc.)
DataTable and TreeTable:
- Added disabled attribute for <o:checkboxColumn> and <o:selectAllCheckbox> tags.
- Added autoSaveState attribute to <o:columnResizing> tag for on-the-fly resizing state saving with Ajax (turned on by default).
- Added autoScrollbars attribute to <o:scrolling> tag that allows automatic hiding of scrollbars when the displayed data entirely fits in the visible area.
- Added rendered attribute to all selection tags to support scenarios where selection kind should be chosen at run-time.
- Greatly improved performance for DataTable and TreeTable components with scrolling and/or column resizing enabled under Internet Explorer.

Fixes

Ajax:
- Fixed Ajax "execute" functionality when "render" components are located in a different form (applicable to all components with Ajax execute and render attributes).
DataTable and TreeTable:
- Fixed the missing column resizing behavior when the sub-header row (aka filter row) is hidden with the "display:none" style.
- Selection functionality shouldn't be applied for the "no data" row.
- Fixed the problem of non-expanding TreeTable rows in IE quirks mode after adding any CSS styles dynamically.
- Fix for command components in TreeTables on deep hierarchy levels (2+ level).
- Fixed using the "subHeader" facet for <o:columns> tag.
- Fixed an issue with double-height nodes in case of empty node text under IE quirks mode.
- Fixed java.io.NotSerializableException exception on filterable DataTable/TreeTable components under MyFaces JSF implementation.
- Fixed "Unsupported binding type: class java.util.ArrayList" exception when binding multiple selection tags to a property of type ArrayList instead of List.
- Fixed "Unspecified error" in IE when reordering columns.
- Fixed declaring the resizingState attribute for <o:columnResizing> tag in JSP.
- Fixed ClassCastException when declaring "header"/"footer" facet without declaring "header"/"footer" facets for columns on a scrollable table.
- Fixed inability to select DataTable/TreeTable contents for copying to clipboard under IE.
- Fixed erroneous displaying of "Sort ascending" and "Sort descending" menu items for non-sortable columns.
- Fixed row heights mismatch when exanding nodes in horizontally-scrollable TreeTables in some cases.
- Fixed misplaced loading of child rows when expanding nodes in scrollable TreeTable in IE 6/7.
- Fixed writing column resizing state into a bound property.
- Fixed not saving collapsed nodes in TreeTable's expansion state.
- Fixed error on DataTable with zero-item model and column filters.
Chart:
- Fixed actionListener attribute for chart view tags which worked only when the tooltip attribute was declared.
DropDownField and SuggestionField:
- Fixed using the string-to-string converters.
- Fixed typing comma char in <o:dropDownField> and <o:suggestionField> with suggestionMode="custom".
Window
- Fixed an issue with <select> elements protruding through Window's modal area.
- Fixed an issue of empty window content when showing a window with Ajax call.
- Fixed the "Can't move focus to the control..." JavaScript error when opening a modal window under IE in some cases.
- Fixed an inability to specify draggable="false" for the Window component.
Other:
- Fixed automatic BorderLayoutPanel resizing when using it as a root component.
- Fixed attaching PopupMenu to FoldingPanel.
- Fixed client validation for required fields with a prompt text.
- Solved excessive "enclosing form cannot be found for component" log warnings when using <rich:tabPanel> with OpenFaces client validation enabled.
- Fixed adding the util-2.x.js file to the pages without OpenFaces components/functionality, though it can still be included on such pages by setting the org.openfaces.forceIncludingUtilJs init parameter if you'd like to have the O$ function on such pages (see the Common Concepts documentation section).
- Fixed "java.lang.InstantiationException: java.util.Arrays$ArrayList" exception during state restoring in some configurations.
- Specifying disabled images for image-based SelectManyCheckbox is now optional.
- Fixed using converter for <o:inputText> component.

Roadmap

forum-admin@teamdev.com — Thu, 23 Apr 2009 16:34:14 GMT

To know when the next version of OpenFaces will come out and what features or components will be available in it, use the OpenFaces roadmap. Note, however, that these are only preliminary plans for future releases and, therefore, they may change over time. Please also note that the roadmap lists only major features of these releases.

If you want to see more new features in the OpenFaces roadmap, let us know. Visit our forum, submit requests to our issue tracking system, or e-mail us directly at info@openfaces.org. You can also follow the current development news in OpenFaces twitter.

OpenFaces 3.0 Early Access 2 (released)

This release is going to have the following modifications since EA1 release:

A part of OpenFaces infrastructure transitioned to JSF 2.0 API instead of old JSF 1.2 ones.
Ajax state handling fixes, which resolves EA1 issues such as Ajax features of DataTable and TreeTable components.
A fix for a conflict with JSF 2.0 Ajax functionality (OF-34)

This version can be downloaded here. See the release notes.

OpenFaces 3.0 (September)

OpenFaces version 3.0 will be maintained in parallel with OpenFaces version 2.0 while there is still interest in JSF 1.2. Both of these versions will have the same set of features but they will be targeted at JSF 2.0 and JSF 1.2 respectively.

OpenFaces 2.1/3.1

Enhanced SelectOneMenu component.
WeekTable component, analogous to DayTable but showing events for a week.
MonthTable component, analogous to DayTable but showing events for a month.
Timetable component -- displays a schedule of events with multiple views (DayTable/WeekTable/MonthTable components combined).
DataTable extensions.

Future releases

MenuBar component.
Panel component.
ProgressBar component.
Interactive column list customization in DataTable and TreeTable components.
Add the nodeDataByKey attribute to the TreeTable (similar to rowDataByKey in the DataTable component for enhanced handling of concurrent data modifications).
Support for displaying a checkbox/selection column with images instead of check boxes.
Nesting of DataTable/TreeTable inside other DataTable/TreeTable.
Flexible paginator customization.
Additional chart types.
Validation groups.
Support for IDEs (NetBeans, IBM Rational Application Developer, Sun Java Studio Creator, JDeveloper, etc.).

Migrating from QuipuKit 1.6.2

forum-admin@teamdev.com — Thu, 30 Apr 2009 16:06:49 GMT

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

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 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.Faces
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	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 (former teamdev.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 new O$(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 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.

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

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", ["f`orm: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 }

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`

What's New in OpenFaces 2.0

forum-admin@teamdev.com — Thu, 30 Apr 2009 16:22:41 GMT

General Information

OpenFaces is an open-source library of AJAX-powered JSF components, an Ajax framework and a client-side validation framework. OpenFaces is based on the set of JSF components formerly known as QuipuKit library. Here's a list of components inherited from the QuipuKit library: Calendar, Chart, Confirmation, DataTable, DateChooser, DynamicImage, FoldingPanel, GraphicText, HintLabel, PopupLayer, SuggestionField, TabSet, TabbedPane, TreeTable, TwoListSelection, Utility Components (Focus, ScrollPosition, LoadBundle). See the OpenFaces Components page for the full description of these components. The rest of this document describes the changes and new features added in OpenFaces version 2.0 since the last release of QuipuKit (version 1.6.2).

Ajax Framework

OpenFaces 2.0 introduces an Ajax framework which allows adding Ajax-based interactions in cases when components' built-in Ajax capabilities are not enough. OpenFaces Ajax framework addresses a common scenario where the whole page has to be submitted to perform some application-specific action and reload the page with the results. OpenFaces Ajax framework allows resolving such use cases without full page reload using a new non-visual component called Ajax, and an appropriate client-side API. The main purpose of this component is reloading one or more components with Ajax, plus it provides additional features such as choosing the components whose data should be submitted to the server, invoking a server action as part of the Ajax request, and handling frequent requests.

Here's a simple example which demonstrates the usage of the new component:

  <h:inputText id="in" value="#{requestScope['ajaxText']}"/>
  <h:commandButton value="Update">
      <o:ajax execute="in" render="out"/>
  </h:commandButton>
  <h:outputText id="out" value="#{requestScope['ajaxText']}"/>

You can see Ajax Framework in action in OpenFaces demo.

In addition to the declarative tag-based syntax, you can use a client-side API that provides access to the same functionality for a JavaScript code. OpenFaces also allows customizing various aspects of Ajax framework using the AjaxSettings component, which can be used to customize Ajax progress message and the way of handling session expiration during Ajax requests. See the documentation for more information.

New Components

CommandButton – an extended version of the standard <h:commandButton> which includes the Ajax features and an ability to customize button's content with sub-components or HTML.
CommandLink – an extended version of the standard <h:commandLink> which includes the Ajax features.
CompositeFilter – allows the user to build complex filter crieteria with multiple filter conditions. Works as a standalone component or can be bound to DataTable/TreeTable components to filter their data.
BorderLayoutPanel – a container used to layout groups of components by container's edges. The separators between component groups can either be fixed to introduce a static layout, or can be made draggable and/or collapsible to make a dynamic layout.
DayTable – a component that allows displaying and editing schedule of events for a day. Each event has a start time, end time, event name, description and other fields. There is also the possibility to show timetable for multiple resources, for example the schedule of tasks for several people.
ForEach – an iterator component that renders the specified set of components multiple times based on its parameters. The ForEach component is similar to the JSTL <c:forEach> tag, though it can be used to overcome some of the shortcomings of <c:forEach> tag and to eliminate the need for an additional JSTL dependency.
InputText – supports all of the features of the standard JSF InputText component and extends it with some additional features like rollover and focused styles and prompt text.
InputTextarea – supports all of the features of the standard JSF InputTextarea component and extends it with some additional features like rollover and focused styles and prompt text.
LayeredPane – a container that allows switching between different sets of displayed components.
PopupMenu – a component that displays a set of actions in a pop-up box for a user to choose from, and is often used as a context menu. The PopupMenu component can be attached to any component to appear when any particular event occurs in that component. A PopupMenu can be configured to have sub-menus to represent complex hierarchies of actions.
SelectBooleanCheckbox – an extended version of the standard <h:selectBooleanCheckbox> component that adds such possibilities as tri-state support, customizing checkbox images and state-dependent styles.
SelectOneRadio – an extended version of the standard <h:selectOneRadio> component, which provides additional styling options and makes it possible to customize radio buttons with images.
SelectManyCheckbox – an extended version of the standard <h:selectManyCheckbox> component, which provides additional styling options and makes it possible to customize radio buttons with images.
Spinner – an input field for entering numbers, which consists of a text field and the attached increase/decrease buttons.
Window – a window-styled container for other JSF components that is displayed over the page content. The Window component has a caption and a content area, it can be dragged around on the page, and resized. Besides, it has the usual maximize/restore, minimize and close buttons in the caption.

New Features

Ajax settings:
- It's now possible to customize Ajax progress message position with new horizontalAlignment/verticalAlignment attributes of <o:defaultProgressMessage> tag.
- Ajax progress message can now be made semitransparent and shown with a smooth transparency transition (see <o:defaultProgressMessage> tag documentation).
- Added an option to disable mouse interoperation by shading window contents while Ajax request is in progress (see <o:defaultProgressMessage> tag documentation).
- It's now possible to customize the appearance of session expiration confirmation (see the <o:defaultSessionExpiration> tag documentation).
DataTable/TreeTable:
- Added support for content scrolling with header/footer row(s) freezing for DataTable and TreeTable components. Both vertical and horizontal scrolling with fixed columns is supported. See the Content Scrolling section in DataTable and TreeTable documentation for details.
- Added support for interactive drag & drop column reordering. See the Drag & Drop Column Reordering section in DataTable and TreeTable documentation for details.
- Added support for interactive column visibility customization. See the Displaying Column Menus section in DataTable and TreeTable documentation for details.
- Numerous filtering enhancements, see the "DataTable/TreeTable Filtering Enhancements" section below.
- Added support for specifying a popup menu for table columns, containing either the standard or customized set of actions.
- Added header and footer attributes to all column tags to serve as a convenient replacement for specifying the text in the "header" and "footer" facets.
- Significantly simplified handling large data sets using Hibernate library. See the Using DataTable with the Hibernate Library section in DataTable documentation for details.
- There's a new "subHeader" facet in the column tags for DataTable and TreeTable components that allows customizing the contents that appear in the table's header section under the column headers.
- Added a new DataTable.getPageIndexForRowKey method for scenarios like detecting the page(s) for selected item(s).
- Improved TreeTable configuration checking and error reporting.
- DataTable is now automatically focused when the pagination buttons are used.
- Resolved the known issue where editable and command components couldn't be used in the Ajax-enabled TreeTable.
TabbedPane:
- Added a new loading mode "ajaxAlways", which allows loading a fresh tab content on each tab switch. Also note the API change: the "ajax" mode has been renamed to "ajaxLazy".
FoldingPanel:
- Added a new loading mode "ajaxAlways", which allows loading a fresh content on each expansion of FoldingPanel. Also note the API change: the "ajax" mode has been renamed to"ajaxLazy".
- FoldingPanel's expansion state is now properly saved when placed inside of iteration components such as <o:dataTable> and <o:forEach>.
Other:
- Extended validation framework: added the possibility for annotation-based validation with <o:validateAll> tag.
- Added the caption attribute for <o:foldingPanel> and <o:subPanel> (former <o:tabbedPaneItem>) tags, which is a short replacement for the"caption" facet if you need to specify the caption as text.
- Added oncontextmenu event for all components.
- Added built-in Ajax support to <o:singleRowSelection>, <o:multipleRowSelection>, <o:singleNodeSelection>, and <o:multipleNodeSelection> tags with render and execute attributes.
- Improved JavaScript performance for the DataTable/TreeTable components.
- All popups in components like DropDownField, SuggestionField, Calendar, DateChooser, PopupMenu can now be closed by pressing Esc key.
- Added support for handling mouse events in <o:floatingIconMessage> tag.
- Improved error checking when processing default validation message presentation parameters in web.xml.
- A new simpler way of attaching Confirmation to components: now you can simply add a Confirmation component inside of other component (like it can be done with <o:ajax> tag) and it will automatically be attached to the "onclick" event of the parent component. The event to which confirmation is attached can be customized with the "event" attribute.
- New "draggableByContent" attribute for <o:confirmation> tag (false by default). If confirmation is configured to be draggable, chooses whether the confirmation window can be dragged by window caption (the default behavior), or by any part of the confirmation window.
- Added an ability to place custom caption buttons into Confirmation and FoldingPanel components.
- Added an ability to place custom caption buttons into FoldingPanel's caption
- Added pressedButtonStyle/pressedButtonClass attributes for DropDownButton and DateChooser.
- Added focusedStyle/focusedClass for all input components.
- Added tabIndex attribute for TwoListSelection component.
- Added standard client events to DynamicImage component.
- Added mouse events to GrahicText component.
- Extended client-side API for TabSet and TabbedPane components: added getTabCount and getPageCount functions respectively.
- Extended client-side API for TwoListSelection component: added selectAll and unselectAll functions.
- Added typingAllowed attribute for DateChooser component to enable scenario where a date should only be selectable from drop-down calendar.
- FoldingPanel's expansion state is now correctly saved when placed inside of iteration components such as <o:dataTable> and <o:forEach>.
- DataTable/TreeTable filter fields' text is now not marked with selection for convenient typing after filtering.
- Rollover button style for DateChooser and DropDownField is now applied when mouse is over the button itself rather than over the field.

DataTable/TreeTable Filtering Enhancements

The filtering API for DataTable and TreeTable components has been significantly reviewed and enhanced. The previous filtering API consisted of filtering-related attributes in <o:column> tag. Although this was enough for a simple API, different kinds of filters require different sets of attributes and additional features require much more attributes, so filters are now organized as separate tags – one tag per one type of filter: <o:inputTextFilter>, <o:dropDownFieldFilter>, and <o:comboBoxFilter>. Each tag has a set of attributes applicable for that particular type of filter. It's quite easy to migrate to the new API though, see the "Migrating to the New Filtering API" sub-section in the Migrating from QuipuKit 1.6.2 document.

Here are the new features that were implemented as part of the new API:

It's possible to customize whether search should be case sensitive or not.
It's now possible to customize the condition by which search has to be performed (contains, equals, less, greater, etc.).
It's now possible to specify style and all other component-specific attributes of filtering components.
There's now an option (turned on by default) that makes filtering to be performed on the fly as the user types in the filter field.
DropDownFieldFilter now suggests filter text as the user types it.
Filters can now be placed outside of their DataTable/TreeTable components.
The filtering expression can now be detected automatically when a filter resides in a table column.

Please see the Filtering section in the DataTable and TreeTable documentation for the comprehensive usage details.

Extended Keyboard Support

OpenFaces 2.0 has extended keyboard support for its components. The following components now include keyboard support:

Calendar
CommandButton
CommandLink
Confirmation
CompositeFilter
DataTable
DateChooser
DropDownField
InputText (native keyboard support)
InputTextarea (native keyboard support)
FoldingPanel
PopupMenu
SelectBooleanCheckbox
SelectOneRadio
SelectManyCheckbox
Spinner
SuggestionField
TabSet
TabbedPane
TreeTable
TwoListSelection (native keyboard support)

Migrating from QuipuKit 1.6.2

Please see the Migrating from QuipuKit 1.6.2 document for the migration instructions.

Migrating from OpenFaces EAP2

forum-admin@teamdev.com — Thu, 04 Mar 2010 18:28:25 GMT

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

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.

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/Class	Change Description
all column tags	Renamed 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 to AJAX_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, Window	Renamed getCaption/setCaption methods to getCaptionFacet/setCaptionFacet
SelectBooleanCheckbox	Moved component class: org.openfaces.component.input.SelectBooleanCheckbox -> org.openfaces.component.select.SelectBooleanCheckbox
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).
org.openfaces.component.table package 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.
org.openfaces.component.action.PopupMenu org.openfaces.component.action.MenuItem org.openfaces.component.action.MenuSeparator	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 name	New attribute name	Value syntax change	Old value example	New value example
`componentIds`	`render`	space delimited instead of comma delimited	"totalInput, saveButton"	"totalInput saveButton"
`submittedComponentIds`	`execute`	space delimited instead of comma delimited	"form:window, form:dropDown"	"form:window form:dropDown"
`actionListener`	`listener`
`action`	– (use `listener` instead)
`requestDelay`	`delay`
`event`	`event`	event 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"
        action="#{TableTestBean.incrementCounter}"/>
</h:inputText>
...
 public void incrementCounter() {
        counter++;
 }
...

New-style code:


<h:inputText id="input">
    <o:ajax event="keypress" render="counter"
        submit="inputStep checkboxIncrease" delay="500"
        listener="#{TableTestBean.incrementCounter}"/>
</h:inputText>
...
 public void incrementCounter(ActionEvent actionEvent) {
        counter++;
 }
...

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 paraemter of typejavax.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 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]

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.

OpenFaces FAQ

forum-admin@teamdev.com — Thu, 23 Apr 2009 16:37:07 GMT

General

OpenFaces is a JSF library that provides an extended set of advanced highly customizable JSF components, an Ajax framework and a validation framework. It extends the standard set of UI components with such sophisticated widgets as TreeTable, DataTable, DayTable, SuggestionField, DateChooser, Chart, and many others. Besides the components, OpenFaces has an Ajax framework and a validation framework. Ajax framework allows adding Ajax-based interaction to the pages where Ajax capabilities built into components are not enough, and Validation framework shifts the traditional JSF validation to the client side, provides new validators and a new kind of error presentation.

Roadmap

To learn when the next version of OpenFaces will come out and what new features or components will it have, see the OpenFaces Roadmap.

Quirks and Standards Compliance modes

The OpenFaces components were tested to work in both Quirks and Standards Compliance modes.

Licensing

I see that OpenFaces is dual licensed, can I use OpenFaces in a commercial project for free?

Yes you are welcome to use OpenFaces in commercial projects for free, like any other LGPL licensed libraries. The additional commercial license doesn't narrow the volume of OpenFaces users, but actually increases it, since it provides an additional way to use OpenFaces for companies that have a policy of not using open-source licensed software.

OpenFaces Licensing Models

OpenFaces is licensed under a dual license model. The functionality of the product is the same for both licensing options.
You can license OpenFaces binaries along with source code packages under the terms and conditions of a GNU LESSER GENERAL PUBLIC LICENSE (Version 2.1, February 1999).
Alternatively you can opt for a commercial license for OpenFaces under the terms and conditions of the Product License Agreement.

Open Source License Benefits

It is free of charge.

Open Source License Restrictions

This license does not restrict using OpenFaces in your proprietary software, though it has some peculiarities. As it follows from LGPL conditions, you may freely copy and distribute verbatim copies of the Library's complete source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and distribute a copy of this License along with the Library.

We do administer OpenFaces support community, but we cannot guarantee our feedback to all your posts.

Commercial License Benefits

The Commercial License exempts you from all the restrictions of the open-source license. This license is issued to a person or company and the license contains your name or the name of your company. Having once purchased the Commercial License you can perpetually use OpenFaces binaries in all your projects without any annual renewals, subscriptions or additional fees to us.

In addition to the license you'll receive a personal yearlong support via direct email with our Software Engineers and access to JIRA to track progress for your issues.

We guarantee our feedback to your support requests within 1 business day.

Commercial License Restrictions

Commercial License doesn't govern source code issues.

Support Policy

Free Support

Free support is provided via our support forum. It is constantly watched and administered by our support engineers, so we guarantee that none of your messages remains unnoticed. Though we do not guarantee that we will answer all the posts.

Paid Support

If you need to secure our feedback, you can consider our paid support. This will ensure our feedback to your request within one business day. It covers bugfixes and some assistance with the use of OpenFaces.

All holders of commercial licenses get one year of this support automatically. If you use Openfaces under LGPL, but you are interested in getting our paid support, please send your request to licensing@teamdev.com.

Project Infrastructure

OpenFaces web site

At OpenFaces web site you can find the detailed info about the project including demos, source codes, binaries and documentation, download the latest stable, nightly build or get the builds history. Refer to the readme.txt files in the respective packages for building instructions.

OpenFaces Community Forum

OpenFaces Community forum is mainly designed for sharing experiences, ideas, thoughts and similar OpenFaces-related discussions.

JIRA Issue Tracking System

If you want to submit a bug or request a feature, please use JIRA Issue Tracking System.

SVN Version Control System

You can check out the entire OpenFaces project including the library itself, the tests and the demos from our SVN. The current development version of the project is available at the following URL: http://svn.openfaces.org/trunk. This project can be built in three ways: using IntelliJ Idea IDE, Eclipse IDE, or Ant build tool. See the Building OpenFaces.html document in project's root directory for instructions.

Documentation

The OpenFaces developer's guide, the tag library documentation and the API reference are available online and are included in the OpenFaces binary distribution packages that can be found at the OpenFaces downloads page.

Forum

OpenFaces forum is available at the following address: http://support.teamdev.com/community/openfaces

Compatibility

Supported JSF implementations

OpenFaces was tested to work with the following JSF implementations:

Sun Reference Implementation (Mojarra) 1.2
Apache MyFaces Implementation 1.2

Supported application servers

OpenFaces was tested to work with the following application servers:

Apache Tomcat 6.0
IBM WebSphere 6.0 -6.1
Bea WebLogic 9.2
JBoss 4.0 - 4.2
Glassfish
Jetty 6.1.x

JSR-168 Portlets support

OpenFaces can be used to develop JSR-168 Portlets. The current version of OpenFaces has been tested to work with the following portal servers:

JBoss Portal 2.4.x and 2.6.x
Liferay Portal 4.2.1
JetSpeed 2.0 Portal

IDE support

There is no IDE support in the current version of OpenFaces. We are planning to add support for the popular IDEs in one of the future releases of OpenFaces. To know about our nearest plans, please see the Roadmap.

Compatibility with JBoss Seam

OpenFaces components are fully compatible with the JBoss Seam framework. The OpenFaces components have been tested to work with JBoss Seam version 2.0 and 2.1.

Compatibility with RichFaces

OpenFaces library is fully compatible with JBoss RichFaces library version 3.3.1 including its components and Ajax framework.

Compatibility with Tomahawk

OpenFaces and Tomahawk components can be used in the same application. However, there are some issues with some of the Tomahawk components. Most of the compatibility problems take place in cases when embedding Tomahawk components inside of OpenFaces components.

Compatibility with Trinidad

OpenFaces and Trinidad are not fully compatible yet. There are some issues when the OpenFaces and Trinidad components are used within one page.

Compatibility with ICEfaces

OpenFaces and ICEfaces components are not compatible currently.

Ajax

Some of the content disappears after performing an Ajax request

If some of the content of ajaxable OpenFaces components disappears after performing Ajax request, the reason might be that you use the <f:loadBundle> component within the OpenFaces Ajax-enabled components. The solution is to use the <o:loadBundle> component instead.

Showing Ajax progress message when Ajax4jsf request is in progress

When any OpenFaces Ajax request is in progress, the "Loading..." message appears in the upper-right corner of the screen. There is no possibility to display this message while Ajax4jsf's Ajax request is in progress. And there is no possibility to display the a4j:status component while an Ajax request in OpenFaces components is being executed. However, you can customize the Ajax progress message for the whole application by using the org.openfaces.ajaxMessageHTML application scope parameter in web.xml or for the particular page by using the <o:defaultProgressMessage> tag. For more details, please see the documentation.

Disabling OpenFaces Ajax progress message

There is no dedicated feature not to show OpenFaces Ajax progress message, however it is possible to utilize features of customizing its appearance for achieving this effect. The idea is to customize the progress message to be invisible using the "display: none" CSS declaration. You can either customize the Ajax progress message for the whole application by using the org.openfaces.ajaxMessageHTML application scope parameter in web.xml or for the particular page by using the <o:defaultProgressMessage> tag. For more details, please see the documentation.

Here's an example of disabling Ajax progress message using the <o:ajaxSettings> tag:

<o:ajaxSettings>
  <f:facet name="progressMessage">
    <o:defaultProgressMessage style="display: none;"/>
  </f:facet>
</o:ajaxSettings>

DataTable and TreeTable

Number of filtered rows in the DataTable

You can get the total number of filtered rows using the getTotalRowCount() method of the DataTable component. You should use the component binding to be able to use this method from your backing bean.

Number of filtered rows in the TreeTable

At the present, there is no public API to get the total number of filtered rows for the TreeTable component. However, you can use the getRowCount() method. This method returns the number of rows that are actually loaded to the client. If you have the preloadedNodes attribute set to "all", the getRowCount() method will return the number of filtered rows.

Placing one DataTable/TreeTable into another one

There is a known issue that the DataTable and TreeTable components cannot be used inside DataTable, TreeTable or any other JSF components that replicate their child components during rendering. We are going to add support for such configurations in one of the future releases.

The row where an event occurs for the server-side event handlers

Server-side event handlers can be aware of the row where an event occurs by checking the request-scope variables that refer to the current row data object and current row index. See the appropriate documentation section. You can use the org.openfaces.util.Faces.var utility method if you need to retrieve a request-scope variable from a backing bean.

Duplicate component IDs exception

In some situations in Facelets application with Sun reference implementation 1.2, you can get the "duplicate component IDs" exception in the pages with the DataTable or TreeTable. This is actually not OpenFaces related problem and it can be reproduced in the application without OpenFaces at all. You can work around this problem by setting the id attributes for the all child components of the DataTable or TreeTable.

The filter components in the DataTable/TreeTable header are too wide

This problem can only be seen for filters with the "searchField" filter type. The problem appears on the pages having the "standards" rendering mode, which is triggered by DOCTYPE specified on the first line of your page. The filter's text field in this case is slightly wider than it should be, which results in its right edge intersect its cell's boundaries. You can use on of the following workarounds:

Switch your page to use the "quirks" rendering mode. You can do this either by removing the DOCTYPE declaration from your page, or changing it appropriately, for example as follows:

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

Remain in the "standards" mode but specify the filterRowStyle="padding-right: 20px" for your table. Note that the actual amount of padding required to fix this might depend on the actual configuration of your table.

Use objects of different types to specify tree structure for the TreeTable component

You can specify the objects of different types for different TreeTable levels. First you should define a dynamic tree structure by specifying the <o:dynamicTreeStructure> tag and the nodeChildren attribute. The attribute should be specified as a value-binding expression, which is calculated for each node to retrieve the node's children. You can use the org.openfaces.util.Faces.var method to get the current node. Then you should return the node children depending on the current node type.

Expanding only one particular node programmatically

You can programmatically specify whether a particular node is collapsed or expanded with its nodeKey. To do so, you should do the following:

1. Bind the expansionState attribute of the TreeTable tag to the variable of org.openfaces.component.table.ExpansionState type in the backing bean.

2. Initialize this variable as follows:

private ExpansionState myTreeTableExpansionState = new DynamicNodeExpansionState(new AllNodesCollapsed());

3. Use the setNodeExpanded(TreePath keyPath, boolean expanded) method to specify whether the node is expanded or collapced. As the first parameter of the TreePath class, you should use nodeKey of the required node. The second parameter is the TreePath of its parent. For example:

myTreeTableExpansionState.setNodeExpanded(new TreePath("message10",null),true);

Here, "message10" is a nodeKey of the node that should be expanded and null means that it is a root node. Please also see the corresponding documentation section.

Note that if you want to expand the node, for example from the third level, you should expand all its parent nodes first. So you will need to make several setNodeExpanded method calls to expand nodes deep in a hierarchy of nodes.

Pagination in the TreeTable component

There is no built-in feature to add pagination to the TreeTable component. However, you can still implement similar behavior by implementing your backing bean to provide only the partial tree structure, and changing the provided data set when pressing "next" and "previous" buttons. To do so, you should display the "next" and "previous" buttons in one of the child nodes on the tree branch that you need to have the pagination functionality, for example in the last node of each tree branch. You can use the <o:row> and <o:cell> tags to do so (see the documentation). In the nodeChildren attribute you should provide only the required number of items for the current "page". When the user clicks the "next" or "previous" button, you should reload the TreeTable component by using O$.ajax.request JavaScript function (or the <o:ajax> component) and change the currently displayed page number so that your backing bean provide the new set of child nodes. See also the documentation for the O$.ajax.request function.

We are planning to implement a built-in TreeTable pagination feature in one of the future releases of OpenFaces.

Change the +/- sign in the TreeTable

To change the +/- sign of the TreeTable component, use the expandedToggleImageUrl and collapsedToggleImageUrl attributes of the <o:treeTable> tag. You can see the example in the "Preloading Nodes" TreeTable demo. The source code of the OpenFaces demo is available at the Download page.

TabbedPane and TabSet

The difference between TabSet and TabbedPane

The TabbedPane component represents a set of pages for containing other components and a set of tabs for switching between these pages. Given the fact that the TabbedPane is a container, a developer can use different loading modes for loading the pages' content. For example, you can use Ajax to load the content of a TabbedPane page when it is selected for the first time.

The TabSet component is just a set of tabs that look like the ones located inside of the TabbedPane, but without any containers. So the TabSet can be used like a switch enabling a developer to manually adjust the page contents depending on a selected tab.

Different <h:form> components in different TabbedPane's tabs

The TabbedPane component should be included in the <h:form> component to save its state between page submissions. And it's incorrect to create nested <h:form> components. Therefore it's not possible to include <h:form> component as a child tag for every TabbedPane's tab in the current version of OpenFaces.

Miscellaneous

Placing the OpenFaces components in the <h:form> tag

In order for OpenFaces components to work properly, they should be placed in the <h:form> or an analogous tag.

Dynamic creation of the OpenFaces components from Java code

The dynamic creation of the OpenFaces components from the Java code is the same as for the standard JSF components. However, there is the createSubComponents() method that should be called for the following components after the component is created and its properties are configured: FoldingPanel, TabbedPane, DropDownField, SuggestionField, TableColumn, TreeColumn. The typical creation of the OpenFaces components is shown in the following example:

FacesContext facesContext = FacesContext.getCurrentInstance();
Application application = facesContext.getApplication();
TabbedPane tabbedPane = (TabbedPane) application.createComponent(TabbedPane.COMPONENT_TYPE);
tabbedPane.setId("myTabbedPane");
tabbedPane.setStyleClass("tabbedPane");
...
tabbedPane.createSubComponents(facesContext);

Change the width of the DateChooser component

Currently, CSS width does not indeed affect the width of the DateChooser. The DateChooser was specifically designed to have the width equal to the pop-up Calendar's width.

However, you can declare the width for a DateChooser with the 'important' CSS modifier. For example:

<o:dateChooser style="width:70px!important;"></o:dateChooser>

Help Us Help You

forum-admin@teamdev.com — Thu, 23 Apr 2009 16:47:55 GMT

When you post any problem with OpenFaces, please provide us with the detailed information on your issue. This will let us reproduce the problem and help you fast and efficiently.

Here is a list of information that might be needed from you:

Your page (JSP or XHTML)
Whole CSS applied to the page (if the problem somehow related to CSS)
Backing bean
Scenario to reproduce the problem
Are there any JavaScript errors
Are there any exceptions in the server log
OpenFaces version
JSF implementation and version
Application server and version
Browser
Your web.xml file
Whether or not you are using Facelets, any other component libraries (such Richfaces, Tomahawk), JBoss Seam framework etc. Please also provide us with versions of used libraries
If you are using Portlets, provide us with a portlet.xml file

Alternatively you may provide us with a sample application, steps to reproduce the problem and the information on the application server used.

TeamDev Support : Document List - OpenFaces

What's New in Nightly Builds

New Components

Enhancements

Fixes

Roadmap

OpenFaces 3.0 Early Access 2 (released)

OpenFaces 3.0 (September)

OpenFaces 2.1/3.1

Future releases

Migrating from QuipuKit 1.6.2

General

Changes Dependent on the New Product Name

Library Changes

Removal of Deprecated API

Renamed, Moved API

Client-Side API Changes

The New O$(id) Function

Unified Client-Side API

Client-Side Validation Functions

Migrating to the New Filtering API

The q_refreshTable and q_refreshTreeTable Functions

API Changes

Other

What's New in OpenFaces 2.0

General Information

Ajax Framework

New Components

New Features

DataTable/TreeTable Filtering Enhancements

Extended Keyboard Support

Migrating from QuipuKit 1.6.2

Migrating from OpenFaces EAP2

Library Changes

API Changes

Migrating to the New Ajax API

OpenFaces FAQ

General

Roadmap

Quirks and Standards Compliance modes

Licensing

Open Source License Benefits

Open Source License Restrictions

Commercial License Benefits

Commercial License Restrictions

Support Policy

Free Support

Paid Support

Project Infrastructure

OpenFaces web site

OpenFaces Community Forum

JIRA Issue Tracking System

SVN Version Control System

Documentation

Forum

Compatibility

Supported JSF implementations

Supported application servers

JSR-168 Portlets support

IDE support

Compatibility with JBoss Seam

Compatibility with RichFaces

Compatibility with Tomahawk

Compatibility with Trinidad

Compatibility with ICEfaces

Ajax

Some of the content disappears after performing an Ajax request

Showing Ajax progress message when Ajax4jsf request is in progress

Disabling OpenFaces Ajax progress message

DataTable and TreeTable

Number of filtered rows in the DataTable

Number of filtered rows in the TreeTable

Placing one DataTable/TreeTable into another one

The row where an event occurs for the server-side event handlers

Duplicate component IDs exception

The filter components in the DataTable/TreeTable header are too wide

Use objects of different types to specify tree structure for the TreeTable component

Expanding only one particular node programmatically

Pagination in the TreeTable component

Change the +/- sign in the TreeTable

The New `O$(id)` Function

The `q_refreshTable` and `q_refreshTreeTable` Functions