Installation and Configuration

Installation

Provided that you already have a JSF application, the following steps will allow you to use QuipuKit components in your application:

  1. Add quipukit.jar to the application libraries.
  2. Add the following libraries found in the distribution under the lib folder to the application:
    Library Distribution file name Notes
    JDom jdom.jar Unmodified library, version 1.0. You can skip adding it if it's already available for the application.
    CSS Parser ss_css2.jar Unmodified library, version 0.9.4. You can skip adding it if it's already available for the application.
    JCommon jcommon.jar Unmodified library, version 1.0.0. You can skip adding it if it's already available for the application.
    JFreeChart jfreechart.jar Specifically modified version for QuipuKit components.
  3. Register the QuipuKit filter in your WEB-INF/web.xml file as follows:
    <!-- FILTER FOR PROCESSING INTERNAL QUIPUKIT RESOURCES -->
      <filter>
        <filter-name>ResourceFilter</filter-name>
        <filter-class>teamdev.jsf.util.ResourceFilter</filter-class>
      </filter>
    
      <!-- MAPPING FOR QUIPUKIT COMPONENTS FILTER -->
      <filter-mapping>
        <filter-name>ResourceFilter</filter-name>
        <url-pattern>/*</url-pattern>
      </filter-mapping>

    For more details, see the Resource Filter Optimization section.

  4. (Optional) If you want to turn on automatic client-side validation for all pages, add the following lines to the WEB-INF/web.xml file (see Validation Framework documentation for more information):
    <context-param>
        <param-name>teamdev.jsf.validation.clientValidation</param-name>
        <param-value>onSubmit</param-value>
      </context-param>

Installing License File

The QuipuKit library needs a valid license file for normal operation. You can request a fully-functional 30-day evaluation license and purchase a commercial license.

To install the license, place the received quipukit-license.jar file with the QuipuKit license to the application classpath (next to quipukit.jar).

The QuipuKit license is checked on the first request to a page with QuipuKit components. The following fields from the license file are checked:

  • Product name
  • Product version
  • Expiration date

The system also checks that there is only one license with "META-INF/quipukit.lic" name in the classpath. The license checking result is written to the log. In case no valid license is found, an error is reported.

Third-Party Libraries

The QuipuKit library uses software developed by the JDOM Project, JFreeChart library, JCommon class library, CSS Parser library and parts of code from Apache MyFaces Project, Apache Commons codec and JSON software.

Redistribution

When distributing your application, please make sure to:

  • Include the following libraries to your project:
    • quipukit.jar (QuipuKit library)
    • Third-party libraries used by the QuipuKit library: jcommon.jar, jdom.jar, jfreechart.jar, ss_css2.jar (for more details, see the section Third-Party Libraries)
  • Include a copy of the LGPL license.
  • Include a copy of the Apache License.

Using QuipuKit Library

To use components of the QuipuKit library, you should declare "http://teamdev.com/quipukit" namespace with "q" prefix. To do it, add the following piece of code to the JSP application:

<%@taglib uri="http://teamdev.com/quipukit" prefix="q" %>

Or add the following parameter to the <HTML> tag to the Facelets application:

xmlns:q="http://teamdev.com/quipukit"

Application Context Parameters

All application context parameters are summarized in the following table:

Parameter Description
teamdev.jsf.validation.clientValidation The application-wide settings of the QuipuKit validation framework. For more details see Validation Framework documentation.
teamdev.jsf.validation.disabled The flag that indicates whether or not the QuipuKit validation for all application is disabled. Default is "false". If teamdev.jsf.validation.disabled property is set to "true" all QuipuKit validation features are turned off. This property can be used for debugging purposes.
teamdev.jsf.validation.useDefaultClientPresentation The flag that indicates whether or not validatable components use the default presentation if no validation or conversion error presentation is set for these components. This property is relevant when client-side validation is turned on for the application. For more details see Validation Framework documentation.
teamdev.jsf.validation.useDefaultServerPresentation The flag that indicates whether or not validatable components use the default presentation if no validation or conversion error presentation is set for these components. This property is relevant when client-side validation is turned off for the application. For more details see Validation Framework documentation.
teamdev.jsf.validation.defaultPresentationClass The full class name of the component that will be used as a default validation presentation component. The component should extend the UIMessage class. If this parameter is omitted, the FloatingIconMessage component is used as a default validation presentation component. Parameters for the validation presentation component are specified as application-scope context parameters in the web.xml file, with the name that contains preceding validation presentation component's class name without package specification, following dot "." and component's attribute name. For more details see Validation Framework documentation.
teamdev.jsf.ajaxMessageHTML Specifies the message that appears when any Ajax request is in progress. This parameter should be specified as portion of HTML that will be shown in the upper-right corner upon an Ajax request. For more details see Ajax Support section in the QuipuKit Developers Guide.
teamdev.jsf.autoSaveFocus The flag that indicates whether or not focus is saved between form submissions for all application pages. For more details see Focus Component documentation.
teamdev.jsf.autoSaveScrollPos The flag that indicates whether or not the scroll position is tracked for all application pages. For more details see Scroll Position Component documentation.

Resource Filter Optimization

To improve performance, you can reduce the scope of requests that are handled by QuipuKit Resource Filter. For example, you can use the following ResourceFilter mappings in your web.xml:

<!-- MAPPING FOR QUIPUKIT COMPONENTS FILTER -->
  <filter-mapping>
    <filter-name>ResourceFilter</filter-name>
    <servlet-name>Faces Servlet</servlet-name>
    <dispatcher>REQUEST</dispatcher>
    <dispatcher>FORWARD</dispatcher>
  </filter-mapping>

  <filter-mapping>
    <filter-name>ResourceFilter</filter-name>
    <url-pattern>/qk_internalResource/*</url-pattern>
    <dispatcher>REQUEST</dispatcher>
    <dispatcher>FORWARD</dispatcher>
  </filter-mapping>
QuipuKit