Reference Guide

Getting Started

 XTP (XML Template Pages)


  1. Style Example
  2. XTP Syntax
  3. Stylesheets
    1. Selecting in the XTP file
    2. Stylesheet Search Path
    3. Dynamic Stylesheets
  4. Servlet Parameters

Serif (XML Template Pages) enhances JSP pages with stylesheets. Sophisticated projects can split page formatting from the JSP-generated content. Splitting the graphic design from the JSP programming helps a web site in several ways:

  • Stylesheets automatically reformat the entire site, so the web site becomes more flexible.
  • Repetitive HTML formatting patterns are defined once, reducing formatting errors.
  • Multiple stylesheets can reformat the same content, displaying views for browsers, handheld devices, and syndication.
  • XTP pages are compiled to JSP, so they have the same performance as JSP.

Since XTP is standards-based, developers benefit from widely-available public documentation, tutorials and support. Stylesheets are written in the W3C standard XSL (XML Stylesheet Language) and produce JSP (Java Server Pages).

Style Example

The following shows a simple example of formatting JSP using stylesheets. The stylesheet formats a custom tag, <exclamation>. The exclamation translates into the HTML <h1> and can be easily changed to any desired format.

Except for the formatting tags, the *.xtp file is a normal *.jsp file describing an HTML page. Unlike JSP which copies its content as raw text, XTP parses the HTML contents into an internal tree (the XML DOM). A more aggressive *.xtp could use XML but most will use XML only where useful. Expressions, scriptlets, and declarations work just as JSP pages.

<?xml-stylesheet href="hello.xsl"?>
<title>Hello, world</title>

<% int count = 0; %>

<exclamation>Hi, World!</exclamation>

Count: <%= count++ %>

For everything but exclamation, the stylesheet copies its input directly to the output. Using this technique, you can add tags as you develop them. So a project can incrementally benefit from XTP; you don't need to entirely redesign your site.

<xsl:output disable-output-escaping="true"/>

<!-- copy everything not matching to the output -->
<xsl:template match="*|@*">
    <xsl:apply-templates select="node()|@*"/>

<!-- format the exclamation -->
<xsl:template match="exclamation">
    <xsl:apply-templates select="node()|@*"/>

The XTP engine produces a standard JSP file as an intermediate form. The generated JSP will process the request. Since it's standard JSP, you can use any JSP or Servlet feature, including using custom JSP tags (although XSL tags are generally more efficient.)

Unless the XTP source or the stylesheet changes, the XTP engine will continue to use the compiled JSP page without additional stylesheet processing. So the XTP has the same performance of a JSP page, with the flexibility of the stylesheet.

    <title>Hello, world</title>

    <% int count; %>

    <h1>Hi, World!</h1>

    Count: <%= count++ %>

XTP Syntax

By default, XTP pages are read in as HTML. Non-HTML tags are treated as XML, i.e. they're expected to have an end tag for every begin tag. By allowing HTML as a primary input format, XTP pages provide a smooth transition path. Sites don't need to transform every page to XML to take advantage of XTP's formatting.

Pages can also be written in strict XML. If the page begins with <?xml ... ?>, it will be read as strict XML. New sites may choose to design using a strict XML base.


XTP Stylesheets can either use the XSL or StyleScript syntax. Both have the same capabilities. StyleScript is more maintainable and readable, but XSL is a W3C standard.

Selecting in the XTP file

XTP pages generally select their stylesheet using the standard xml-stylesheet processing instruction. If no stylesheet is selected, the XTP page will use default.xsl.

<?xml version="1.0">
<?xml-stylesheet href="sample.xsl"?>

Stylesheet Search Path

  1. The directory of the XTP file.
  2. The application root.
  3. WEB-INF/xsl.
  4. The Java classpath.

When building libraries of stylesheets, using the Java classpath has several advantages. It's naturally arranged in a path, it's familiar, and it is well supported by the servlet engines.

Dynamic Stylesheets

The request parameter caucho.xsl.stylesheet selects the stylesheet for the XTP page. If set, it overrides the value specified in the XTP page. A filter servlet can set caucho.xsl.stylesheet to process the same page with different styles. For example, a User-Agent filter could select a different stylesheet for a Palm client or for a printable version of the page.

public void service(HttpServletRequest req,
                    HttpServletResponse res)
  throws IOException, ServletException
  String style = req.getParameter("style");

  if (style != null && style.equals("print"))
    request.setAttribute("caucho.xsl.stylesheet", "print.xsl");

  RequestDispatcher disp;
  disp = getServletContext().getNamedDispatcher("xtp");

  disp.forward(req, res);

Servlet Parameters

The XTP engine can set xsl:param variables taken from the servlet request. Stylesheets can use these variables, like xtp:path_info, to create several web pages out of a single source XTP. A section, for example, might only be displayed if it matches the request.getPathInfo().

Stylesheets must use xsl:param to use servlet parameters. Unless the stylesheet declares its parameters, XTP will not pass the values to the stylesheet.

xsl:paramServlet Value

<xsl:param name="xtp:path_info"/>

<!-- by default, section is not displayed -->
<xsl:template match="section"/>

<xsl:template match="section[$xtp:path_info=@name]">
  <h1><xsl:value-of select="@title"></h1>

A sample XTP file might look like:

<section title="Introduction">

This is the introduction.

<section title="Conclusion">

This is the conclusion.


Copyright © 1998-2002 Caucho Technology, Inc. All rights reserved.
Resin® is a registered trademark, and HardCoretm and Quercustm are trademarks of Caucho Technology, Inc.