QuipuKit Developer’s Guide |
|||||||||||||||
Developer’s Guide Home
Installation and Configuration Components Index Calendar Chart Confirmation Data Table Date Chooser Drop Down Field Dynamic Image Folding Panel Hint Label Popup Layer Suggestion Field Tab Set Tabbed Pane Tree Table Two List Selection Utility Components Validation Framework Tag Reference |
The QuipuKit Developer's Guide consists of the following:
OverviewThe 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 EnvironmentsSupported BrowsersAll the QuipuKit components support the latest versions of the following browsers:
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 VersionsThe QuipuKit components require JDK 1.4 or later on the server. JSF VersionsThe 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 SupportThe 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 SupportThe 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:
Ajax4jsf Framework SupportThe 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 SupportThe 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 FeaturesCommon AttributesThe 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 StylesAll 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:
Handling Client-Side EventsAll 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 APISome 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:
Creating Components DynamicallyYou 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 SupportAjax 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:
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 ConventionsThe documentation on the QuipuKit components uses the following markup conventions:
Please also note that whenever "list" and "collection" terms are used, java.util.List and java.util.Collection are meant. Known IssuesGeneral
Ajax-related
Portlets-related
JBoss Seam-related
|
||||||||||||||
© 2007 TeamDev Ltd. | ![]() |