QuipuKit Developer’s Guide

The QuipuKit Developer's Guide consists of the following:

  • Documentation Home (this document) providing the overview, supported environments and general characteristics of the QuipuKit components.
  • Installation and Configuration providing getting-started information, installation steps, usage and QuipuKit-specific application context parameters.
  • Components Index listing all the QuipuKit components with their short descriptions and screenshots.
  • Documentation on individual QuipuKit components describing their features, configuration, and code samples (see the sidebar for the components list).
  • Documentation on the QuipuKit validation framework providing the overview, features, configuration, detailed API description, and code samples.

Overview

The QuipuKit library includes an extended set of JSF components for building rich Web user interfaces and a validation framework that shifts the traditional JSF validation logic to the client side.

The standard JSF UI components are not enough to create a feature-rich and responsive Web application. The QuipuKit library extends this set with such advanced components as DataTable, TreeTable, Calendar, DateChooser, Chart, TwoListSelection (and many others) and provides richer client-side functionality for them. Thanks to such features as Ajax support and keyboard navigation, the QuipuKit library not only simplifies development of Web applications but as a result, makes them highly interactive and user-friendly.

With the QuipuKit validation framework, you can now use standard JSF validators on the client side by assigning them to any input component, both from JSF and QuipuKit library. Or, by the same token, use additionally provided QuipuKit validators that work equally well on the client and server side. The QuipuKit validation framework supports a variety of usage scenarios where data should be validated, ensuring that validation rules are met and data types are correct already on the client, promptly notifying the user of any possible errors. In addition, it provides a flexible mechanism to configure the default validation errors presentation in many different ways.

Supported Environments

Supported Browsers

All the QuipuKit components support the latest versions of the following browsers:

  • Microsoft Internet Explorer (6.0 and later)
  • Mozilla Firefox (1.5 and later)
  • Opera (8.50 and later)
  • Apple Safari (2.0.1 and later)

The QuipuKit components operate well in quirks and standards-compliant browser modes. Please also note that the QuipuKit library requires enabled JavaScript in the client browser.

JDK Versions

The QuipuKit components require JDK 1.4 or later on the server.

JSF Versions

The QuipuKit library requires the JavaServer Faces implementation conforming to the specification version 1.1 or 1.2. The current version of the QuipuKit components has been tested with the following JSF implementations: Apache MyFaces 1.1.1 - 1.1.4 and Sun JSF Reference Implementation version 1.1 and 1.2.

Facelets Framework Support

The QuipuKit components can be used not only with JSP, but also with the Facelets framework. Facelets is a view technology that can be used instead of JSP to build JSF applications. The way of defining a QuipuKit component's attributes for use in Facelets is the same as for JSP. All examples given in this documentation are applicable to both JSP and Facelets. QuipuKit components have been tested to work with Facelets version 1.0.2, 1.1.4 and 1.1.11.

JSR-168 Portlets Support

The QuipuKit library can be used to develop JSR-168 Portlets. Portlets are Web components designed to be managed and displayed in Web portals. The current version of the QuipuKit components has been tested to work with the following portal servers:

  • JBoss Portal 2.4.1
  • Liferay Portal 4.2.1
  • Jetspeed-2 Enterprise Portal

Ajax4jsf Framework Support

The QuipuKit components are now fully compatible with the Ajax4jsf framework. The QuipuKit components have been tested to work with Ajax4jsf version 1.1.

Note that the HintLabel component cannot be reloaded with Ajax4jsf via its ID. It's necessary to wrap the HintLabel into the <a4j:outputPanel> tag in order to reload it by using Ajax4jsf. For example,

<a4j:outputPanel id="tableWrapper">
<q:hintLabel value="#{request.summary}"/>
</a4j:outputPanel>

You should also wrap an input component with the Message component and Messages component into the <a4j:outputPanel> tag in order to make QuipuKit validation framework features work properly if you reload an input component with Ajax4jsf.

When reloading the DataTable or TreeTable components through Ajax4jsf, the contents of the "above" and "below" facets are not reloaded. In order to reload a DataTable or TreeTable with their "above" and "below" facets, it should be wrapped into the <a4j:outputPanel> tag, and that panel should be reloaded instead.

JBoss Seam Framework Support

The QuipuKit components are fully compatible with the JBoss Seam framework. The QuipuKit components have been tested to work with JBoss Seam version 1.2.1.

General Features

Common Attributes

The QuipuKit components have a set of common attributes. As standard JSF components, all the QuipuKit components support the id, rendered and binding attributes. Input components support the required, validator and converter attributes. Most attributes also support the JSF Expression Language for specifying values.

Customizing Styles

All QuipuKit components have a default style and allow flexible style customization through their attributes. These attributes usually define the component appearance in terms of Cascading Style Sheets (CSS) with the exception of some component-specific attributes whose usage depends on the component itself.

Every component has the style and styleClass attributes that control the style characteristics of the entire component. The style attribute is used to specify inline CSS declarations, and the styleClass attribute is used to reference CSS classes declared elsewhere on the page.

In case of composite components, you can customize styles for different parts of such a component. The attributes that control a particular part of the component are named *Style and *Class, where the asterisk is a placeholder for the part of a component being customized. There are also attributes that specify the style depending on the state of a particular part of the component. For example, rollover*Style, rollover*Class or pressed*Style, pressed*Class. When declaring *Class attributes, you can either specify the name of the appropriate CSS class as a value or space-separated multiple class names.

All styles that you specify for QuipuKit components merge with their default styles. Custom styles have higher priority over the default ones, so if some style definitions overlap, custom styles will take effect.

All styles are broken down into four groups (see below). You can define styles from these groups for one and the same part of the component. As a result, the styles will merge and get applied according to their priority in ascending order as shown below, where regular styles have the lowest priority:

  • Regular styles
  • Rollover styles (rollover*Style and rollover*Class attributes)
  • Selected and pressed styles depending of the component (selected*Style and selected*Class / pressed*Style and pressed*Class attributes)
  • Disabled styles (disabled*Style and disabled*Class attributes)

Handling Client-Side Events

All the QuipuKit components have a set of standard client-side events, such as onclick, ondblclick, onfocus. In addition, some components provide non-standard client-side events whose functionality depends on a particular component.

Client-Side API

Some QuipuKit components provide client-side methods to control the state or behavior of a component on the client side. Each of these methods is accessible in two ways:

  • As a method of an appropriate component. This way is good when you need to invoke repeatedly several methods on the same component. Here is an example:
    var table = document.getElementById('form1:table1');
    if (table.isSelectionEmtpy()) table.setSelectedRowIndex(0);
  • As a global method receiving the component's id. This way is suitable for cases where you need to invoke just one method and avoid the document.getElementById('xxx') call. These global methods have the "q_" prefix and accept the component's client id as the first parameter. For example, the following calls are identical:
    q_showPopupLayer('form1:popup1')
    document.getElementById('form1:popup1').show();

Creating Components Dynamically

You can create and manipulate QuipuKit components programmatically the same way as standard JSF components. However, there is one requirement: You should call the createSubComponents method for some of the QuipuKit components after you create a component and assign an ID for it. This method should be called when dynamically creating the following QuipuKit components: FoldingPanel, TabbedPane, DropDownField, TableColumn, TreeColumn. Note that ID assignment is optional, but you should not change it after the createSubComponents invocation.

Here is an example of creating the TabbedPane component:

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

Ajax Support

Ajax is a technique providing the ability to exchange data with the server without reloading a Web page. As a result, Web applications provide smoother user interaction, better responsiveness and take less network traffic. The QuipuKit components use Ajax in cases where data should be dynamically loaded from the server after a page is loaded. The following components support Ajax-based dynamic data loading: DataTable, TreeTable, FoldingPanel, TabbedPane.

Note that QuipuKit components use Ajax only for those updates that are triggered by the components themselves (like paging and sorting in a DataTable or tab switching in a TabbedPane).

When any Ajax request is in progress, the "Loading..." message appears in the upper-right corner of the screen. This message is displayed by default. You can change it by specifying the teamdev.jsf.ajaxMessageHTML parameter in web.xml. This parameter should be specified as portion of HTML that will be shown in the upper-right corner on an Ajax request.

For example you can add the following code to web.xml:

<context-param>
  <param-name>teamdev.jsf.ajaxMessageHTML</param-name>
  <param-value><![CDATA[
    <div style="background: white;
                font: Tahoma 15pt normal;
                border: 1px solid black;">
      <img src="/testapp/images/progress.gif"/>
      Ajax request is currently in progress!
    </div>
  ]]></param-value>
</context-param>

The QuipuKit components use Ajax by default. However, there are cases where Ajax cannot be used:

  • Some browsers do not support all Ajax usage scenarios. This mainly concerns Opera and Safari browsers that don't support dynamic stylesheet manipulation.
  • Some third-party components do not work correctly inside the components using Ajax.

To avoid these problems, you can disable Ajax support for any component. For more details on how to do it, read documentation on a respective component. When Ajax support is turned off, the page is submitted whenever data update is needed, instead of making an Ajax request.

For information about possible issues with Ajax support, see the section Known Issues.

Documentation Conventions

The documentation on the QuipuKit components uses the following markup conventions:

Element name Example
Class names java.util.Date
Attribute and property names onclick
Value constants ajax
UI elements Add All
Component names TreeTable
Tag names <q:dynamicImage>

Please also note that whenever "list" and "collection" terms are used, java.util.List and java.util.Collection are meant.

Known Issues

General

  • The DataTable and TreeTable components cannot be used inside DataTable, TreeTable or any other JSF components that replicate their child components during rendering.

Ajax-related

  • Resources from the <f:loadBundle> tag cannot be used inside Ajax-enabled components.
  • If you use Ajax in Facelets, you should not use inline text within the components that support Ajax. The reason is that inline text cannot be made non-transient, so the appropriate text will just disappear after an Ajax request. As a solution, you can use the <h:outputText> tag to output text.
  • Ajax loading modes don't work for MyFaces 1.1.3 when server-side state saving method is used.
  • TreeTable with editable components within its cells cannot be used in the TreeTable configured to expand its nodes with Ajax. As a workaround, you can either set preloadedNoes="all" , or useAjax="false" for your TreeTable.

Portlets-related

  • When you use JBoss Portal and "client" state saving method, Ajax does not work properly after page reload.
  • Ajax does not work on Jetspeed-2 Enterprise Portal server with Apache Portals JSF Bridge if you use the "server" state saving method and MyFaces 1.1.3 or 1.1.4 . Using MyFaces 1.1.1 or switching to Apache MyFaces Portlet bridge fixes this problem.
  • The Chart and DynamicImage components do not work on Jetspeed-2 Enterprise Portal server.

JBoss Seam-related

  • JBoss Seam's link and button components don't propagate a selected row of <q:dataTable>.
  • JBoss Seam's validation presentation components (s:decorate and s:message) don't work on the client side.
  • JBoss Seam's validate and validateAll components don't work on the client side.
QuipuKit