The full Presenting XML distribution may be obtained from https://sourceforge.net/projects/presentingxml/. It includes the source code and build files as well as binary jar files, a sample web application, and run scripts. It includes api documentation and a user guide. It also includes a number of third party jar files.

The directory layout under the top level presentingxml directory is as follows:

The following software components are not included and must be downloaded and installed separately:

Presenting XML requires Java JDK 1.3 or later (it will not work with earlier versions.) It has been tested with Sun's Java JDK 1.3.1, on Windows 2000 and on Linux.

You will need to configure your web server to work with Presenting XML. This section describes how to do that for Jakarta Tomcat 4.0.

The distribution files for the Jakarta Tomcat 4.0 web server may be obtained from http://jakarta.apache.org/site/binindex.html.

The steps to configure Jakarta Tomcat to work with Presenting XML are as follows:

Presenting XML requires a WAP browser emulator for viewing the sample WML pages. A free WAP browser emulator may be obtained from OPENWAVE.

Set the environmental variable JAVA_HOME to a version of the jdk 1.3 or above, i.e.

set JAVA_HOME=C:\tools\java\jdk1.3.1

Build the sample web application by entering build at the command prompt in the webapps/bookstore directory.

If everything has gone correctly you should now be able to run the sample web application.

A simple example is shown below.

<px:resources xmlns:px="http://www.presentingxml.com/PresentingXML"
              xmlns:myapp="http://www.presentingxml.com/myapp"
              ns="http://www.presentingxml.com/myapp">
              
  <px:app>
    <px:mapRequest>
      <px:matchRequestURI match="/bookstore/pages/(.+)">$1</px:matchRequestURI>
    </px:mapRequest>
  </px:app>
              
  <px:page name="books">
    <px:parameter ns="" name="category"/>
    <px:show>
      <px:transform>
        <px:content ref="myapp:books"/>
        <px:style ref="myapp:books"/>
      </px:transform>
    </px:show>
  </px:page>
  
  <px:dynamicContent name="books" className="samples.books.BookCatalog">        
    <px:key>
      <px:field name="category"/>
    </px:key>
  </px:dynamicContent>

  <px:style name="books" href="html/books/books.xsl"/>

</px:resources>              

Each element in the resources script has a prefix px:. The resources element associates the px: prefix with the Presenting XML namespace in the declaration xmlns:px="http://www.presentingxml.com/PresentingXML". In this way, the page, content and style elements are identified as belonging to Presenting XML, not to the author of the books content and stylesheet.

Note the px:app element at the head of the books resources script. The app element optionally contains a px:mapRequest element that defines the mapping of request URIs into page names. If no request mapper element is specified, the default is to look for a page with whatever namespace happens to be in scope and a local name the same as the request URI. In the example, we see a single px:matchRequestURI element that maps a request URI like /bookstore/pages/welcome into a page with namespace "http://www.presentingxml.com/myapp" and local name "welcome".

The books resources script defines a number of resources: a page, a document, and a style. These names belong to the author of the books resources. Each resource is given a name. A name has two parts, a local name and a namespace URI. The local name is specified by a name attribute. The namespace URI is specified by a ns attribute. If the element defining the resource does not specify a ns attribute, the namespace URI defaults to that of the nearest ancestor element that does have a ns attribute, or the empty string if there is none. In the books example, therefore, the page takes a local name "books" and the namespace URI "http://www.presentingxml.com/myapp". The prefix myapp: is associated with that namespace.

Pages are defined with the page element. In the books page element above, we see a page element that defines a response, which consists of a transform instruction applied to a document and a stylesheet. The consequence of this definition is that if a browser sends a request to the web server for the page named books, the document named "books" will be styled with the stylesheet named "books", resulting in an HTML page being returned to the browser.

Documents are defined with a content element. In the books example above, we see a px:dynamicContent element with a className attribute, associating the document "books" with the Java class sample.books.BookCatalog.

public class BookCatalog implements SelectHandler {
  public void doRequest(PageContext context, Book parameters, 
  ContentWriter contentWriter) throws PresentingXMLException {
    // Implementation
  }

  public long getLastModified(RuntimeContext context, Book key, 
  long timestamp, long elapsed)  {
    // Indicate changed if older than 10 seconds
    return elapsed > 10000 ? timestamp : timestamp + elapsed;  
  }
}

Note that the doRequest method defined above takes a user defined interface Book as its second argument,

public interface Book {
  public String getCategory();
}

Stylesheets are defined with the style element. In the books example above, we see a px:style element with an href attribute, associating it with the relative url "html/books/books.xsl". By default this relative url is resolved relative to the location of the resources script. The base may be overriden with an xml:base attribute.

There are three kinds of elements that may appear in a resources script:

As the resources script becomes larger, it becomes desirable to reorganize it, splitting off document and style elements into separate files, in separate directories. For example, we may wish to have the directory tree:

<px:resources xmlns:px="http://www.presentingxml.com/PresentingXML"
              xmlns:myapp="http://www.presentingxml.com/myapp"
              ns="http://www.presentingxml.com/myapp">
  
  <px:include href="../documents/documents.xml"/>
  <px:include href="../styles/styles.xml"/>
              
  <px:app>
    <px:mapRequest>
      <px:matchRequestURI match="/bookstore/pages/(.+)">$1</px:matchRequestURI>
    </px:mapRequest>
  </px:app>
  
  <px:page name="books">
    <px:parameter ns="" name="category"/>
    <px:show>
      <px:transform>
        <px:content ref="myapp:books"/>
        <px:style ref="myapp:books"/>
      </px:transform>
    </px:show>
  </px:page>

</px:resources>              

A pipeline body defines the sequence of steps applied to content to transform it into an XML stream for the serializer. A pipeline starts with content, passes it through a number of stages where it gets filtered and transformed, and finally hands it off to a serializer.

The simplest possible pipeline is a single px:content instruction. Such a pipeline simply passes the content "as is" to the serializer.

Consider the following pipeline body.

    <px:transform>
      <px:transform>
        <px:systemContent href="documents/mixed-up.xml"/>
        <px:saxFilter className="PreFilter"/>
      </px:transform>  
      <px:style href="styles/filter.xsl"/>     
      <px:saxFilter className="PostFilter"/>     
    </px:transform>

This pipeline body may be thought of as a sequential process that executes from right to left. The inner transform is executed first. Here, the content mixed-up.xml is passed through the SAX filter PreFilter, and then streamed to the outer transform. In the outer transform, the result tree is first transformed with the XSLT stylesheet filter.xsl, and then passed through the SAX filter PostFilter, finally making its way to the serializer.

A pipeline body may have any number of nested transform stages. The innermost transform stage must contain a content instruction. Within a transform stage, there may be any number of filters and XSLT transformations that are executed in document order.

<px:resources xmlns:px="http://www.presentingxml.com/PresentingXML"
              xmlns:myapp="http://www.presentingxml.com/myapp"
              ns="http://www.presentingxml.com/myapp">
  
  <px:include href="../documents/documents.xml"/>
  <px:include href="../styles/styles.xml"/>
                
  <px:app>
    <px:mapRequest>
      <px:matchRequestURI match="/bookstore/pages/(.+)">$1</px:matchRequestURI>
    </px:mapRequest>
  </px:app>
  
  <px:page name="books">
    <px:parameter ns="" name="category"/>
  
    <px:show>
      <px:choose>
        <px:when test="$category">
          <!--  request has parameter category -->
          <px:transform>
            <px:style ref="myapp:books"/>
            <px:content ref="myapp:books"/>
          </px:transform>
        </px:when>
        <px:otherwise>
          <!--  request does not have parameter category -->
          <px:transform>
            <px:style ref="myapp:welcome"/>
            <px:content ref="myapp:request"/>
          </px:transform>
        </px:otherwise>
      </px:choose>
    </px:show>
  </px:page>
  
</px:resources>              

A serializer takes the output of a transformer - an XML or HTML tree - and serializes it to a byte stream before sending it back to the client device. The default serializer simply transforms the tree to text and sends that back as a byte stream.

The example below illustrates the use of a serializer to produce a pdf document:

<px:resources xmlns:px="http://www.presentingxml.com/PresentingXML"
          xmlns:myapp="http://www.presentingxml.com/myapp"
          ns="http://www.presentingxml.com/myapp">
                
  <px:app>
    <px:mapRequest>
      <px:matchRequestURI match="/bookstore/pages/(.+)">$1</px:matchRequestURI>
    </px:mapRequest>
  </px:app>

  <px:page name="pulp">
    <px:clientOptions caching="yes"/>      
    <px:cachingOptions caching="yes" revalidate="synch"/>      
    <px:show>
      <px:fopSerializer/>
      <px:transform>
        <px:style ref="myapp:novel-fo"/>
        <px:content ref="myapp:pulp"/>
      </px:transform>
    </px:show>
  </px:page>
  
  <px:systemContent name="pulp" href="books/pulp.xml"/>        
  
  <px:style name="novel-fo" href="fo/books/novel.xsl"/>
</px:resources>

A serializer is defined with the serializer element. The example above uses the apache fop serializer.

The example below shows the "update-cart" page which updates a shopping cart in a Java UpdateCart object, adding a new book title, and then performs a client-side redirect to the "books" page. The URI of the "books" page is evaluated as an XPATH expression that can refer to any XML content generated in the pipeline that appears in its content, or to any parameters passed to the page.

  <px:page name="update-cart">   
    <px:parameter ns="" name="category"/>
    <px:parameter ns="" name="bookId"/>
    <px:parameter ns="" name="title"/>
    
    <px:show>
      <px:clientRedirect select="concat('/bookstore/pages/books?category=',$category)">
        <px:dynamicContent className="samples.books.UpdateCart"/>        
      </px:clientRedirect> 
    </px:show>
  </px:page>

Presenting XML uses the <xsl:output> element in the XSLT stylesheet to obtain information about the MIME type that the stylesheet produces. It is therefore important that the media-type attribute of the <xsl:output> element is assigned a value, for example "text/html" for HTML stylesheets and "text/vnd.wap.wml" for WML stylesheets.

The figure below shows the px:devices section in the system configuration file. It defines a number of known devices and the MIME-types they accept. It also defines maps from the HTTP User-Agent to the device. If the device can be identified, Presenting XML will use that information first. If the device cannot be identified, Presenting XML will use the HTTP accept header.

  <px:devices>
    <!-- Define devices and accepted MIME types -->
    <px:device name="explorer" 
               accept="text/html,application/pdf"/> 
    <px:device name="pocketexplorer"/>
    <px:device name="handweb"/>
    <px:device name="avantgo"/>
    <px:device name="imode"/>
    <px:device name="opera"/>
    <px:device name="lynx"/>
    <px:device name="java"/>
    <px:device name="wap" 
               accept="text/vnd.wap.wml"/>
    <px:device name="mozilla5" 
               accept="text/html"/>
    <px:device name="netscape" 
               accept="text/html,application/pdf"/>
    
    <!--
    Map a pattern in the User-Agent to a device name.
    A pattern may contain unix wildcards.
    -->
    <px:deviceMap search="MSIE" device="explorer"/> 
    <px:deviceMap search="MSPIE" device="pocketexplorer"/>
    <px:deviceMap search="HandHTTP" device="handweb"/>
    <px:deviceMap search="AvantGo" device="avantgo"/>
    <px:deviceMap search="DoCoMo" device="imode"/>
    <px:deviceMap search="Opera" device="opera"/>
    <px:deviceMap search="Lynx" device="lynx"/>
    <px:deviceMap search="Java" device="java"/>
    <px:deviceMap search="(Nokia)|(UP)|(Wapalizer)" device="wap"/>
    <px:deviceMap search="(Mozilla/5)|(Netscape6/)" device="mozilla5"/>
    <px:deviceMap search="Mozilla" device="netscape"/>
  </px:devices>

Note that the search attribute appearing in the px:deviceMap element can take regular expressions.

The following example shows how the same request URI may be mapped into different pages depending on the device and on the mime types that the device accepts.

<px:resources xmlns:px="http://www.presentingxml.com/PresentingXML"
              xmlns:myapp="http://www.presentingxml.com/myapp"
              ns="http://www.presentingxml.com/myapp">
  
  <px:include href="../styles/styles.xml"/>
  <px:include href="../documents/documents.xml"/>
  
  <px:app>
    <px:mapRequest>
      <px:matchDevice device="explorer">
        <px:matchRequestURI match="/bookstore/pages/(.+)">$1/explorer</px:matchRequestURI>
      </px:matchDevice>
      <px:matchDevice accept="text/html">
        <px:matchRequestURI match="/bookstore/pages/(.+)">$1/html</px:matchRequestURI>
      </px:matchDevice>
      <px:matchDevice accept="text/vnd.wap.wml">
        <px:matchRequestURI match="/bookstore/pages/(.+)">$1/wml</px:matchRequestURI>
      </px:matchDevice>
    </px:mapRequest>  
  </px:app>
  
  <px:page name ="books/wml">
    <px:parameter ns="" name="category"/>
    <px:show>
      <px:transform>
        <px:style ref="myapp:books/wml"/>
        <px:content ref="myapp:books"/>
      </px:transform>
    </px:show>
  </px:page>
  
  <px:page name ="books/html">
    <px:parameter ns="" name="category"/>
    <px:show>
      <px:transform>
        <px:style ref="myapp:books/html"/>
        <px:content ref="myapp:books"/>
      </px:transform>
    </px:show>
  </px:page>
  
</px:resources>

Suppose in this example we receive the request URI "/bookstore/pages/books".

If the sending device is recognized to be "explorer" according to the rules defined in the presentingxml.xml configuration file, the first request matcher attempts to resolve the request to a page with namespace "http://www.presentingxml.com/myapp" and local name "books/explorer". This fails, since there is no such page, The second request matcher then checks that the device accepts the mine type "text/html" (which it does) and also that there is a page having namespace "http://www.presentingxml.com/myapp" and local name "books/html", which there is.

If the sending device is unrecognized, and the HTTP accept header indicates that the device does not accept mime type "text/html", but does accept mime type "text/vnd.wap.wml", then the third request matcher will attempt to find a page having namespace "http://www.presentingxml.com/myapp" and local name "books/wml".

None.

None.

Optionally, a pipeline body.

Performs a client-side redirect to the URI that results from evaluating the xpath expression in the select attribute.

A client-side redirect sends a URI back to the client, in the expectation that the client will resubmit the request with the new URI. If you want to have state sent with the new URI, you have two options:

None.

None.

None.

One or more action elements from the following list.

None.

See px:dynamicContent.

None.

Optionally, a px:fieldAttributeMap element.

None.

See px:dynamicContent.

Optionally, a pipeline body.

Allows a resources script to pass control locally to another page.

A local redirect computes a new request URI in its select attribute, transfers the request back to the app, skips the validation steps defined in the px:validateRequest element (since its already inside the gate), and attempts to match the new request URI with a page using the rules defined in the px:mapRequest element.

None

Matches a request to a page.

One or more elements derived from px:mapRequest, including px:matchDevice and px:matchRequestURI elements.

The mapRequest element supports matching a request URI to a page.

Text.

Optionally, one or more px:mapRequest type elements, including px:matchDevice and px:matchRequestURI elements.

Matches a device to a page.

Text that may include regular expression wildcard characters.

Optionally, one or more px:mapRequest type elements, including px:matchDevice and px:matchRequestURI elements.

Matches a request URI to a page.

None.

A pipeline body.

Optionally, one or more px:parameter elements.

One or more action elements from the following list.

Optionally, text. If the content contains text, it is evaluated as the value of the parameter.

Used to define the parameters of a px:page element.

A document root element, which in turn may contain other elements and a px:recordMapping element.

The list of elements that may be defined with a qualified name at the top level of the resources script includes all the elements that are defined in the px:instructions section of the presentingxml.xml configuration file. These include

None.

None.