cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Diana Shannon <>
Subject FAQ and snippet, document() function
Date Tue, 09 Jul 2002 15:14:41 GMT
Appropriate use of the document() function in Cocoon represents one of 
major conceptual FAQs among XSLT users migrating to Cocoon. Recent 
on cocoon-dev and cocoon-users have shed a lot of light on the subject.

Below is a draft FAQ, based on Stefano and Jan's recent dicussions on 
Within it you will also find a pointer to a proposed snippet ( Conal 
Tuohy's recent
post on cocoon-users) which provides an xinclude-based alternative to 
the document() function.

Please help to review both and comment here (or cocoon-users) as 

-- Diana

Q. What's "wrong" with use of the document() function in Cocoon?

A. Using the document() function for aggregation in Cocoon breaks
Separation of Concerns (SoC). That is, the designers of Cocoon
view inclusion and transformation as different functions, best
handled by separate Cocoon components. Treating them
separately allows you to achieve performance gains and increases
the resusability of your pipelines.

Alternatives to the document() in the Cocoon environment include
aggregation or the use of a multi-stage transformation using the
XInclude Transformer. This involves transforming a list of documents
(generated dynamically or statically) by adding xinclude elements which
reference (via xpointer) specific document content, and then transforming
again via the XInclude Transformer, to obtain the desired result.

For an example of this, see:
  (Proposed Snippet)

You'll achieve better performance if you aggregate content prior to 
This allows you to take full advantage of Cocoon's pipeline caching. In 
making dynamic document() calls inside an XSLT within a cached pipeline 
is problematic.
At this time, Cocoon does not recognize changes in documents (called by 
the document() function)
until the requested page expires from cache.

Understand that the document() function was designed *before* xinclude
with xpointer facilities existed. Had such capabilities been available,
perhaps the document() function, which essentially mimics xinclude and 
would have never been added to XSLT.

Please note that if you must work with your XML files outside of the
Cocoon environment as well, you may need to use the document() function
in order to utilize the limited capabilities of other pipeline engines.
This includes engines which are not xinclude-capable or which
lack a predefined way to indicate document processing steps.

View raw message