shannon 2002/06/27 08:52:50
Added: src/documentation/xdocs/howto
howto-paginator-transformer.xml
Log:
New How-To for the Paginator
Transformer based on content
originally posted by Stefano
to cocoon-dev on 06/06/2002.
I expanded it a bit to make it
more practically useful for newbies.
There remain issues with the
samples also created, so this
is a low-profile commit. I.e.
please don't announce its
availability. I need some
feedback from Stefano before
announcing...
Revision Changes Path
1.1
xml-cocoon2/src/documentation/xdocs/howto/howto-paginator-transformer.xml
Index: howto-paginator-transformer.xml
===================================================================
<?xml version='1.0' encoding='ISO-8859-1'?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
"../dtd/document-v10.dtd">
<document>
<header>
<title>How to use the Paginator Transformer</title>
<authors>
<person name="Stefano Mazzocchi" email="[EMAIL PROTECTED]" />
</authors>
</header>
<body>
<s1 title="Overview">
<p>
This How-To describes the how to use Cocoon's Paginator Transformer component. You
can consider it a 'FilterTransformer' on pagination steroids. The Paginator
Transformer filters specific data and counts pages as it transforms SAX events. It
implements pagination rules based on easy-to-configure pagesheet documents.
</p>
</s1>
<s1 title="Purpose">
<p>
XSLT-based approaches to pagination are problematic. First of all, it's somewhat
complex to define the necessary declarative logic in XSLT. Additionally, an XSLT
solution is rarely reusable across different pagination use cases. These problems
spurred the creation of the Paginator Transformer. You can quickly add pagination
capabilities to your webapp once you have configured a simple few rules within a
single configuration file, the pagesheet.
</p>
<p>
The Paginator Transformer works quite nicely for use cases involving a few tens of
pages and, of course, for static generation of any number of pages. However, the
Transformer must process an entire file before it can extract even a single page.
Therefore, you are <strong>strongly</strong> advised against using it for books or
other large documents on dynamic sites. Nevertheless, its output is cacheable. Thus,
if the same page is requested, then the document will be reprocessed by the
Transformer only when it has changed.
</p>
</s1>
<s1 title="Intended Audience">
<p>
Cocoon users who need pagination capabilities for their web documents. This includes
frustrated users who are tired of implementing complex, XSLT-based approaches to
pagination.
</p>
</s1>
<s1 title="Prerequisites">
<p>
Make sure you have the version 2.0.3 or greater of Cocoon. The PaginatorTransformer
component source is located in the scratchpad area. Therefore, you need to use the
following command to build a deployable cocoon.war which includes the scratchpad
libraries.
</p>
<source>
./build.sh -Dinclude.webapp.libs=yes -Dinclude.scratchpad.libs=yes webapp
</source>
<p>
During the build process, the necessary configuration details for the
PaginatorTransformer component are automatically copied to cocoon.xconf of cocoon.war.
This means that you don't need to manually configure cocoon.xconf. However, if you are
adding the paginator samples to Cocoon webapp that was <strong>not</strong> generated
by the above build command, add the following snippet to your cocoon.xconf file,
located in the WEB-INF directory of your deployed webapp.
</p>
<source><![CDATA[
<component
class="org.apache.cocoon.transformation.pagination.Paginator"
role="org.apache.cocoon.transformation.pagination.Paginator"
/>]]></source>
<p>
Sample files related to this How-To are also copied during the build process to
Cocoon webapp at webapp/samples/mount/paignator.
</p>
</s1>
<s1 title="Steps">
<p>
Let's start with a simple example.
</p>
<s2 title="Simple Example">
<p>
Suppose you have an XML file, document.xml, as follows.
</p>
<source><![CDATA[
<?xml version="1.0"?>
<images>
<image />
<image />
<image />
<image />
<image />
<image />
<image />
</images>
]]></source>
<fixme author="DS">
Perhaps we need a DTD for the pagesheet to help readers visualize the pagesheet.
</fixme>
<p>
First, you need to write a <strong>pagesheet.</strong> Just as a stylesheet contains
instructions for an xslt processor, a pagesheet contains instructions for the
paginator filter. Here is the pagesheet dtd.
</p>
<source><![CDATA[
<!ELEMENT pagesheet (items?, rules)*>
<!ATTLIST pagesheet xmlns CDATA #IMPLIED>
<!ELEMENT items (group)>
<!ELEMENT group EMPTY >
<!ATTLIST group
name CDATA #IMPLIED
element CDATA #IMPLIED >
<!ELEMENT rules (link?, count?)*>
<!ELEMENT count EMPTY >
<!ATTLIST count
type ( element | char ) #REQUIRED
num CDATA #REQUIRED
name CDATA #IMPLIED
namespace CDATA #IMPLIED
>
]]></source>
<p>
Let's say you want to paginate document.xml content based on a rule of three
<image> elements per page. Here's a sample pagesheet, images.xml, which does
just that.
</p>
<source><![CDATA[
<?xml version="1.0"?>
<pagesheet xmlns="http://apache.org/cocoon/paginate/1.0";>
<rules>
<count type="element" name="image" num="3" />
</rules>
</pagesheet>
]]></source>
<p>
You process a source file through a pagesheet filter in a sitemap snippet like this:
</p>
<source><![CDATA[
<map:match pattern="page(*)">
<map:generate src="document.xml"/>
<map:transform src="pagesheets/images.xml" type="paginator">
<map:parameter name="page" value="{1}"/>
</map:transform>
<map:serialize type="xml"/>
</map:match>
]]></source>
<p>
Accessing the URI for page one, page(1) ( e.g.
http://localhost:8080/cocoon/mount/paginator/page(1) ) yields:
</p>
<source><![CDATA[
<?xml version="1.0" encoding="UTF-8" ?>
<images xmlns:page="http://apache.org/cocoon/paginate/1.0";>
<image />
<image />
<image />
<page:page
current="1"
total="3"
current-uri="/cocoon/mount/paginator/page(1)"
clean-uri="/cocoon/mount/paginator/page" />
</images>
]]></source>
<p>
Clearly the above XML could have been transformed into something more meaningful.
Note that the transformer must process all pages to obtain the value of
<code>total</code>. Currently, there is no way to avoid this.
</p>
</s2>
<s2 title="Adding Navigation">
<p>
Given the Paginator's a full-blown pagesheet language, there's even more we can
accomplish, most importantly, navigation.
</p>
<p>
As an example, consider the following pagesheet, images2.xml.
</p>
<source><![CDATA[
<?xml version="1.0"?>
<pagesheet xmlns="http://apache.org/cocoon/paginate/1.0";>
<items>
<group name="item" element="images" />
</items>
<rules>
<rules>
<count type="element" name="image" num="3"/>
<link type="unit" num="1"/>
</rules>
</rules>
</pagesheet>
]]></source>
<p>
The pagesheet rules demonstrate that the transformer understands how the page was
encoded in the given URI request, i.e., that parentheses surround the value of page.
They also reveal that the transformer can provide navigation links to available pages,
in this case, plus or minus one position.
</p>
<fixme author="DS">
In the above paragraph, you say the transformer understand how the page was encoded.
How? I don't see the evidence until the snippet produced below.
</fixme>
<p>
In your sitemap.xmap file, if you change the pagesheet source to images2.xml as
follows:
</p>
<source><![CDATA[
<map:match pattern="page(*)">
<map:generate src="document.xml" />
<map:transform src="pagesheets/images2.xml" type="paginator">
<map:parameter name="page" value="{1}" />
</map:transform>
<map:serialize type="xml" />
</map:match>
]]></source>
<p>
Processing the same page(1) request yields the following (pretty-printed for this
document):
</p>
<source><![CDATA[
<?xml version="1.0"?>
<images xmlns:page="http://apache.org/cocoon/paginate/1.0";>
<image />
<image />
<image />
<page:page
current="1"
total="3"
current-uri="/cocoon/mount/paginator/page(1)"
clean-uri="/cocoon/mount/paginator/page">
<page:link
type="next"
uri="/cocoon/mount/paginator/page(2)"
page="2" />
</page:page>
</images>
]]></source>
<p>
This result demonstrates:
</p>
<ul>
<li>
Page 0 does not exist, so no <page:link> is created for a previous page.
</li>
<li>
Page 2 exists, so <page:link> is created, along with
<ul>
<li>
a value of "next" for its type attribute (useful for visualization), and
</li>
<li>
a value of page(2) for its URI attribute (useful for linking without XSLT-specific
logic)
</li>
</ul>
</li>
</ul>
<p>
Note that the URI is re-encoded using the same parentheses pattern, page(2).
</p>
<p>
Now, without changing anything, requesting page(2) yields the following.
</p>
<source><![CDATA[
<?xml version="1.0"?>
<images xmlns:page="http://apache.org/cocoon/paginate/1.0";>
<image />
<image />
<image />
<page:page
current="2"
total="3"
current-uri="/cocoon/mount/paginator/page(2)"
clean-uri="/cocoon/mount/paginator/page">
<page:link type="prev" uri="/cocoon/mount/paginator/page(1)" page="1" />
<page:link type="next" uri="/cocoon/mount/paginator/page(3)" page="3" />
</page:page>
</images>
]]></source>
<p>
And requesting page(3) yields the following.
</p>
<source><![CDATA[
<?xml version="1.0"?>
<images xmlns:page="http://apache.org/cocoon/paginate/1.0";>
<image />
<page:page
current="3"
total="3"
current-uri="/cocoon/mount/paginator/page(3)"
clean-uri="/cocoon/mount/paginator/page">
<page:link
type="prev"
uri="/cocoon/mount/paginator/page(2)"
page="2" />
</page:page>
</images>]]></source>
<p>
Note only one <image>. The original document, images.xml, only contained seven
<image> elements: three for page one, three for page two, but only one for page
three. Thus, the result here is the modulo (or remainder) of the division.
</p>
</s2>
<s2 title="Real-Life Examples">
<p>
Here are a few pagesheets examples which are a bit more complex.
</p>
<s3 title="DirectoryGenerator Pagination">
<p>
Here's an example of paginating the contents of a directory using the
DirectoryGenerator.
</p>
<source><![CDATA[
<?xml version="1.0"?>
<pagesheet xmlns="http://apache.org/cocoon/paginate/1.0";>
<rules>
<count type="element" name="file"
namespace="http://apache.org/cocoon/directory/2.0";
num="16" />
<link type="unit" num="2" />
<link type="range" value="5" />
</rules>
</pagesheet>
]]></source>
<p>
The rules state:
</p>
<ol>
<li>
paginate 16 files per page
</li>
<li>
provide links to +/- 1 and +/- 2 pages (when available)
</li>
<li>
provide links to +/- 5 (when available)
</li>
</ol>
<p>
So, suppose we have a directory with 300 files. If we request page 10, the generated
page will be:
</p>
<source><![CDATA[
<?xml version="1.0"?>
<dir:directory>
<dir:file ... />
[other 15 dir:file]
<page:page
xmlns:page="http://apache.org/cocoon/paginate/1.0";
current="10"
total="19"
current-uri="dir(10)"
clean-uri="dir" >
<page:range-link page="5" type="prev" uri="page(5)" />
<page:link page="8" type="prev" uri="page(8)" />
<page:link page="9" type="prev" uri="page(9)" />
<page:link page="11" type="next" uri="page(11)" />
<page:link page="12" type="next" uri="page(12)" />
<page:range-link page="15" type="next" uri="page(15)" />
</page:page>
</dir:directory>
]]></source>
</s3>
<s3 title="Asymmetric pagination">
<p>
We also have the ability to indicate different rules for each page, for example:
</p>
<source><![CDATA[
<?xml version="1.0"?>
<pagesheet xmlns="http://apache.org/cocoon/paginate/1.0";>
<rules page="1">
<count type="element" name="b" num="5" />
<link type="unit" num="1" />
</rules>
<rules>
<count type="element" name="b" num="10" />
<link type="unit" num="2" />
</rules>
</pagesheet>
]]></source>
</s3>
<s3 title="Count types">
<p>
The Paginator Transformer was designed to count. However, it's up to you to define
what needs to be counted, either XML elements or characters (not yet implemented). By
supplying values to the attributes of <count> in the pagesheet, you can specify
exactly what needs to be counted.
</p>
<p>
The <count> element has two required and two optional attributes. The required
attributes are:
</p>
<ul>
<li>
<strong>type</strong> the method of counting the paginator should perform, either
elements or characters.
When element is specified, the transformer counts startElement() SAX events. When
chars is specified (currently not implemented), the transformer counts the primitive
data type char.
</li>
<li>
<strong>num</strong> a number which how many times counted item (element or chars)
must be present within the transformed page.
</li>
</ul>
<p>
Optional attributes (when type="element" is specified) are:
</p>
<ul>
<li>
<strong>name</strong> the name of the element, without any namespace prefix
</li>
<li>
<strong>namespace</strong> the URI of the namespace. If not specified, the default
namespace is used.
</li>
</ul>
</s3>
</s2>
</s1>
<s1 title="Improving the Paginator Transformer" >
<p>
The PaginatorTransformer was developed, initially, to paginate a directory listing.
It
works great when it paginates by counting elements, particularly elements which
contain similar amounts of content to be displayed on pages. With documents, for
example, it could paginate by counting sections or subsections. However, bear in mind
that this approach does not always guarantee visually-balanced web pages.
</p>
<s2 title="Nested Pagination" >
<p>
Furthermore, simply counting elements is not always simple. Consider the following:
</p>
<source><![CDATA[
<?xml version="1.0"?>
<a>
<b>
<a>
<b>
<a>
<b/>
</a>
</b>
</a>
</b>
</a>
]]></source>
<p>
Let's say you want to paginate using one <b> per page. What should the
transformed pages look like? Here's a few possible outcomes. Which one is the best?
</p>
<s3 title="Page 1" >
<source><![CDATA[
<?xml version="1.0"?>
<a>
<b>
<a>
<a/>
</a>
</b>
</a>
]]></source>
</s3>
<s3 title="Page 2" >
<source><![CDATA[
<?xml version="1.0"?>
<a>
<a>
<b>
<a/>
</b>
</a>
</a>
]]></source>
</s3>
<s3 title="Page 3" >
<source><![CDATA[
<?xml version="1.0"?>
<a>
<a>
<a>
<b/>
</a>
</a>
</a>
]]></source>
</s3>
<p>
It appears the current code is buggy somewhere. With deep
nesting as in this example, some SAX events are lost. This
creates a non-well-formed SAX stream which chokes subsequent
transformers, such as XSLT, which may be sensitive to well-formedness.
</p>
<p>
Does the above might look like a mental exercise to you? Perhaps, but consider
the structure of Cocoon Project's Document DTD 1.1. which includes nested
<section> elements. Similar problems will emerge when paginating these documents
based on this dtd.
It's isn't clear whether the solution adopted above is meaningful or not for a
real-world pagination. Suggestions on this are welcome.
</p>
</s2>
<s2 title="Character-based Pagination" >
<p>
Given the need to visually balance pages, a counting method for characters was
added, even though it isn't implemented yet. Counting by characters is especially
difficult when you think about the algorithms that perform chunking.
</p>
<p>
Assume you have a document like this:
</p>
<source><![CDATA[
<p>this is some <strong>text</strong> that happens
to be <em>chuncked</em></p>
^
]]></source>
<p>
Suppose that paginating by counting the chars results in a chunking point
indicated by the caret above (between the letters u and n).
Ending a page at that position results in XML that is not well-formed as well as
truncated words. Even if you find a way to provide well-formed XML,
you still must deal with word-break issues. Therefore, we need a way to
produce well-formed XML by continuing until the first 'block-level' element is
encountered, for example,
<p> in this case. However, this means that the pagesheet must contain a list of
such 'block-delimiting' elements. Currently, the Pagesheet parser and
object model does <strong>not</strong> support this notion.
</p>
<p>
Conclusion? Pagination at the char level is not trivial and will require a
little bit of additional work on the transformer.
</p>
</s2>
<s2 title="Other Improvements" >
<p>
One possible way to improve the concept is to count by XPath results. For example,
you may want to count <section> elements included in other <section>
elements. Another way to improve the design is to allow booleans to be used within
counting
rules. For example, you could count <session> AND <chapter> elements.
Most likely, XPath will help here as well.
</p>
</s2>
</s1>
<s1 title="Comments">
<p>
Care to comment on this How-To? Got ideas on how to improve the Paginator
Transformer? Help keep this How-To and the Paginator Transformer relevant by passing
along any useful feedback to the author, <link
href="mailto:[EMAIL PROTECTED]";>Stefano Mazzocchi</link>.
</p>
</s1>
<s1 title="Revisions">
<p>
06-06-02: Content originally posted to cocoon-dev by Stefano Mazzocchi.
</p>
<p>
06-26-02: Edited and structured by Diana Shannon. Scratchpad samples also added.
</p>
</s1>
</body>
</document>
----------------------------------------------------------------------
In case of troubles, e-mail: [EMAIL PROTECTED]
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
