JavaServer Faces (JSF) is a server-side GUI component framework developed through the Java Community Process under JSR-127. JSF is primarily designed to build Web applications.

This chapter explains how to integrate Orbeon Forms with JSF. Most of this documentation also applies to the standalone distribution of the XML RenderKit for JavaServer Faces. It may also be a good read for anyone interested in using XML technologies such as XSLT with JSP and JSF.

The JSF Standard HTML RenderKit outputs raw HTML. Using this RenderKit, the HTML output can be configured with:

• CSS classes assigned to the generated HTML tags by setting yyyClass attributes on the components, where yyy is the component name in lowercase without the "UI" prefix. For example, setting a commandClass attribute on a UICommand component generates a class attribute on the resulting HTML <input> element.

• A certain number of additional attributes on components are passed without modification to the resulting HTML element. Those attributes do not appear to be documented in the current JSF specification. Examples include size, cols, JavaScript event handlers, etc. They may modify the appearance and/or behavior of a component.

Often, CSS classes and other HTML attributes are not sufficient to completely customize the appearance of a component. For example:

• Support for multiple devices. Rendering a component differently depending on the targeted device. For example, a PDA browser typically needs to render a component in a much simpler way, due to the limited space on its small screen.

• Advanced internationalization. For example, implementing right-to-left layouts for languages such as Arabic or Hebrew. In such cases, component captions must be placed on the other side of components and a grid (table) must be rendered right-to-left.

• Advanced look and feels and support for older clients. For example, rendering an HTML table with a colored border in an old Web browser such as Netscape 4. This requires embedding two HTML tables within each other. You may decide that all your HTML dropdowns must be surrounded by an HTML table.

The classical solution to those problems is to:

• Write a new JSF RenderKit in Java
• Write one JSP page for each different layout

The Orbeon Forms approach allows you to address this problem elegantly:

• Write an XML RenderKit once and for all. Note that if you use only the JSF Standard User Interface Components, you don't have to write your own renderer: you can use the one that comes with Orbeon Forms. This means that you don't have to write a single line of Java to customize the appearance of JSF components.

• Minimize the number of JSP pages. Write one JSP page that generates XML, instead of duplicating JSP code and writing one page per device or language. This approach reduces the number of pages you need to write and maintain.

• Centralize your look and feel. Customize one or several XSLT stylesheets to change the appearance of components. This is a key advantage when requirements change: you go to one location to reflect you changes instead of having to go through an impact analysis and multiple changes.

The JSP technology is well-suited to generate well-formed XML, but it does not enforce well-formed XML output. To achieve this, the following conditions must be met:

1. JSP pages must contain only well-formed template text markup. It is recommended (but not mandatory) to write JSP documents instead of regular JSP pages. A JSP document is similar to a JSP page, but is a well-formed XML document. A JSP document in JSP 2.0 usually ends with the extension .jspx, since JSP 2.0 engines automatically recognize this extension. With JSP 1.2, they usually end with .jsp, like regular JSP pages.

   Note

   Some JSP engines have trouble generating XML documents with namespaces from JSP documents. Tomcat 4.1.x does not appear to exhibit such problems, but WebLogic does.

2. Tag libraries used in the JSP pages / documents must generate well-formed XML. The JSF Standard HTML RenderKit Tag Library generates output through the RenderKit associated with the components. Since the output of the standard RenderKit is HTML and not XML, it is necessary to fix it. One way of doing this is to switch to an XML RenderKit instead. Orbeon Forms comes with such an XML RenderKit implementation for the JSF Standard User Interface Components.

   NOTE: Another possibility is to use an HTML parser on the HTML output of the document. Using an XML RenderKit offers additional benefits, as explained below.

   NOTE: Not all tag libraries generate output directly. For example, JSTL iterators and conditionals do not generate any output of their own.

When the XML RenderKit is used standalone (without Orbeon Forms), the following control flow (compatible with the Model 2X architecture) occurs: a custom Servlet Filter implements a mini-controller, parses the JSP output and applies an XSLT transformation. Such a filter can be modified at will to provide more or less functionality.

1. HTTP Request
2. The filter dispatches the request to JSF
3. The JSF Controller processes the request and forwards it to a JSP page
4. If necessary using the JSF tag libraries and, indirectly, the XML RenderKit, the JSP page generates XML output
5. The output from the JSP page is parsed
6. Through an XSLT transformation, the response is sent to the client

The current version of Orbeon Forms supports rendering JSF components using XML pipelines. You can use XSLT or other transformation languages. The flow is very similar to the standalone flow, but dispatching the request to JSF and parsing the JSP output is implemented in a generic XML processor in Orbeon Forms called the Servlet Filter Generator. The generator can be connected to any other XML processors. A typical use is to connect its output to an XSLT Transformer.

The following figure illustrates the flow of the request, from the client to Orbeon Forms to JSF and back:

1. HTTP Request
2. The Orbeon Forms Controller dispatches the request to an XML pipeline
3. Using a Servlet Filter Generator, the pipeline calls a JSF tree
4. The JSF Controller processes the request and forwards it to a JSP page
5. If necessary using the JSF tag libraries and, indirectly, the XML RenderKit, the JSP page generates XML output
6. The resulting XML is generated within Orbeon Forms by the Servlet Filter Generator
7. Through an optional series of transformations, the response is sent to the client

Orbeon Forms comes with an XML RenderKit for the JSF Standard User Interface Components. The XML RenderKit can also be used independently from Presentation Server.

6.1. Differences with the HTML RenderKit

6.2. Differences with an XHTML RenderKit

6.3. Sample XSLT Stylesheet

6.4. XML Output Format