File: guide.html

package info (click to toggle)
cocoon 1.8-1
links: PTS
area: contrib
in suites: woody
size: 12,016 kB
ctags: 3,793
sloc: xml: 16,682; java: 8,089; sh: 174; makefile: 61
file content (552 lines) | stat: -rw-r--r-- 22,303 bytes
<HTML><HEAD><TITLE>User Guide</TITLE><LINK href="resources/simple.css" rel="stylesheet" title="Simple Style" type="text/css"></HEAD><BODY><P class="legal">Cocoon Documentation</P><H1 class="title">User Guide</H1><DOCUMENT>
 

 <BODY>

<H1>Introduction</H1><DIV id="s1">
  <P>This document assumes the knowledge of the W3C recommendation
  or working drafts used in Cocoon (mainly <A href="http://www.w3.org/TR/REC-xml">XML</A>,
  <A href="http://www.w3.org/TR/WD-xsl">XSL</A> in both its <A href="http://www.w3.org/TR/WD-xslt">transformation</A>
  and <A href="http://www.w3.org/TR/WD-xsl">formatting</A> capabilities). This
  document is not intended to be an XML or XSL tutorial but just shows how these
  technologies may be used inside the Cocoon framework to create web content.</P>
</DIV>

<H1>General overview</H1><DIV id="s1">
  <P>Cocoon is a publishing system that allows you to separate web development into
  three different layers: content, style and logic.</P>

  <P>In a way, Cocoon does not aim to simplify the creation of web content:
  in fact, it is harder to create XML/XSL content than it is to use HTML from
  the beginning. So, if you
  are happy with the web technology you are using today, don't waste your time
  and stick with what you already have. Otherwise, if your troubles are site
  management, if your graphics people are always in the way, if your HTML authors
  always mess up your page logic, if your managers see no results in hiring new
  people to work on the site - go on and make your life easier!</P>

  <P>This comment posted on the Cocoon mailing list shows you what we mean:</P>

<PRE>
I've got a site up and running that uses Cocoon.
It rocks, the management loves me (they now treat
me like I walk on water), and a couple of summer
interns that I had helping me on the project are
suddenly getting massively head-hunted by companies
like AT&amp;T now that they can put XML and XSL on
their resumes.  In a word: Cocoon simply rocks!
</PRE>
</DIV>

<H1>Hello World</H1><DIV id="s1">
  <P>Every good user guide starts with a <CODE>Hello World</CODE> example,
  and since we hope to write good documentation (even if it's as hard as hell!),
  we'll start from there too. Here is a well-formed XML file that uses a custom
  and simple set of tags:</P>

<PRE>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;page&gt;
 &lt;title&gt;Hello World!&lt;/title&gt;
 &lt;content&gt;
  &lt;paragraph&gt;This is my first Cocoon page!&lt;/paragraph&gt;
 &lt;/content&gt;
&lt;/page&gt;
</PRE>

  <P>Even if this page mimics HTML (in a sense, HTML was born as a simple DTD
  for homepages), it is helpful to note that there is no style information
  and all the styling and graphic part is missing. Where do I put the title? How
  do I format the paragraph? How do I separated the content from the other
  elements? All these questions do not have answers because in this context they
  don't need one: this file should be created and maintained by people that
  don't need to be aware of how this content if further processed to become a
  served web document.</P>

  <P>On the other hand, we need to indicate how the presentation questions will
  be answered. To do this, we must indicate a <EM>stylesheet</EM> that is able to
  indicate how to interpret the elements found in this document. Thus, we
  follow a <A href="http://www.w3.org/TR/WD-xml-stylesheet">W3C recommendation</A>
  and add the XML processing instruction to map a stylesheet to a document:</P>

  <PRE>&lt;?xml-stylesheet href=&quot;hello.xsl&quot; type=&quot;text/xsl&quot;?&gt;</PRE>

  <P>Now that our content layer is done, we need to create a stylesheet to
  convert it to a format readable by our web clients. Since most available web
  clients use HTML as their <EM>lingua franca</EM>, we'll write a stylesheet to
  convert our XML in HTML (More precisely, we convert to XHTML which is the XML
  form of HTML, but we don't need to be that precise at this point).</P>

  <P>Every valid stylesheet must start with the root element <EM>stylesheet</EM>
  and define its own namespace according to the W3C directions. So the
  skeleton of your stylesheet is:</P>

<PRE>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;xsl:stylesheet xmlns:xsl=&quot;http://www.w3.org/1999/XSL/Transform&quot;&gt;
&lt;/xsl:stylesheet&gt;
</PRE>

  <P>Once the skeleton is done, you must include your <CODE>template</CODE> elements,
  which are the basic units of operation for the XSLT language. Each template is
  matched against the occurence of some elements in the original document and
  the element is replaced with the child elements of the template,
  if they belong to other namespaces, or, if they belong to the XSLT namespace,
  they are further processed in a recursive way.</P>

  <P>Let's see an example: in our <CODE>HelloWorld.xml</CODE> document
  <CODE>page</CODE> is the root element. This must be transformed into all those tags
  that identify a good HTML page. Your template becomes:</P>

<PRE>
&lt;xsl:template match=&quot;page&quot;&gt;
 &lt;html&gt;
  &lt;head&gt;
   &lt;title&gt;&lt;xsl:value-of select=&quot;title&quot;/&gt;&lt;/title&gt;
  &lt;/head&gt;
  &lt;body bgcolor=&quot;#ffffff&quot;&gt;
   &lt;xsl:apply-templates/&gt;
  &lt;/body&gt;
 &lt;/html&gt;
&lt;/xsl:template&gt;
</PRE>

  <P>where some elements belong to the standard namespace (which we mentally
  associate with HTML) and some others to the <EM>xsl:</EM> namespace.
  Here we find two of those
  XSLT elements: <CODE>value-of</CODE> and <CODE>apply-templates</CODE>. While
  the first <EM>searches</EM> the <CODE>page</CODE> element's direct children for the
  <CODE>title</CODE> element and
  replaces it with the content of the retrieved element, the second indicates
  to the processor that it should continue the processing of the other templates
  described in the stylesheet from that point on in the input document
  (known as the <EM>context node</EM>).</P>

  <P>Some other possible templates are:</P>

<PRE>
&lt;xsl:template match=&quot;title&quot;&gt;
 &lt;h1 align=&quot;center&quot;&gt;
  &lt;xsl:apply-templates/&gt;
 &lt;/h1&gt;
&lt;/xsl:template&gt;

&lt;xsl:template match=&quot;paragraph&quot;&gt;
 &lt;p align=&quot;center&quot;&gt;
  &lt;i&gt;&lt;xsl:apply-templates/&gt;&lt;/i&gt;
 &lt;/p&gt;
&lt;/xsl:template&gt;
</PRE>

  <P>After the XSLT processing, the original document is transformed to</P>

<PRE>
&lt;html&gt;
 &lt;head&gt;
  &lt;title&gt;Hello&lt;/title&gt;
 &lt;/head&gt;
 &lt;body bgcolor=&quot;#ffffff&quot;&gt;
  &lt;h1 align=&quot;center&quot;&gt;Hello&lt;/h1&gt;
  &lt;p align=&quot;center&quot;&gt;
   &lt;i&gt;This is my first Cocoon page!&lt;/i&gt;
  &lt;/p&gt;
 &lt;/body&gt;
&lt;/html&gt;
</PRE>

</DIV>

<H1>Browser Dependent Styling</H1><DIV id="s1">
  <P>When a document is processed by an XSLT processor, its output is exactly the same for every browser that requested
  the page. Sometimes it's very helpful to be able to discover the client's
  capabilities and transform content layer into different views/formats. This is
  extremely useful when we want to serve content do very different types of
  clients (fat clients like desktop workstations and thin clients like wireless
  PDAs), but we want to use the same information source and create the smallest
  possible impact on the site management costs.</P>

  <P>Cocoon is able to discriminate between browsers, allowing the different stylesheets to
  be applied. This is done by indicating in the stylesheet linking PI the <EM>media</EM>
  type. For example, continuing with the HelloWorld.xml document, these PIs</P>

<PRE>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;?xml-stylesheet href=&quot;hello.xsl&quot; type=&quot;text/xsl&quot;?&gt;
&lt;?xml-stylesheet href=&quot;hello-text.xsl&quot; type=&quot;text/xsl&quot; media=&quot;lynx&quot;?&gt;

...

</PRE>

  <P>would tell Cocoon to apply the <CODE>hello-text.xsl</CODE> stylesheet if the Lynx browser
  is requesting the page. This powerful feature allows you to design your content
  independently and to choose its presentation depending on the capabilities of the browser
  agent.</P>

  <P>The media type of each browser is evaluated by Cocoon at request time,
  based on their <CODE>User-Agent</CODE> http header information.
  Cocoon is preconfigured to handle these browsers:</P>

  <DL>
    <LI><STRONG>explorer</STRONG> - 
      any Microsoft Internet Explorer, searches for MSIE (before
      searching for Mozilla, since IE pretends to be Mozilla too)
    </LI>
    
    <LI><STRONG>opera</STRONG> - 
      the Opera browser (before searching for Mozilla, since
      Opera pretends to be Mozilla too)
    </LI>
    
    <LI><STRONG>lynx</STRONG> - the text-only Lynx browser</LI>
    
    <LI><STRONG>java</STRONG> - any Java code using standard URL classes</LI>
    
    <LI><STRONG>wap</STRONG> - the Nokia WAP Toolkit browser</LI>
    
    <LI><STRONG>netscape</STRONG> - any Netscape Navigator or Mozilla, searches for Mozilla</LI>
    
  </DL>

  <P>but you can add your own by personalizing the
  <CODE>cocoon.properties</CODE> file, modifying the <CODE>browser</CODE>
  properties. For example:</P>

<PRE>
browser.0=explorer=MSIE
browser.1=opera=Opera
browser.2=lynx=Lynx
browser.3=java=Java
browser.4=wap=Nokia-WAP-Toolkit
browser.5=netscape=Mozilla
</PRE>

  <P>indicates that Cocoon should look for the token <EM>MSIE</EM> inside the
  User-Agent HTTP request header first, then <EM>Opera</EM>
  and so on, until <EM>Mozilla</EM>.
  If you want to recognize different generations of the same browser you should
  find the specific string you should look for, and
  - this is very important - indicate the order of matching, since
  other browsers' User Agent strings may contain the same string
  (see examples above).</P>
</DIV>

<H1>Using query parameters during XSL transformation</H1><DIV id="s1">

   <P>Quite often you want to create pages that depend on some
   user-supplied data. One way to do this is using HTML forms.
   Cocoon provides you with a simple way to use this data. Let's
   assume you've got the following list and you want the user
   to choose a country code and be shown the name of the corresponding
   country.
   </P>

 <PRE>
 &lt;?xml version=&quot;1.0&quot;?&gt;
 &lt;?cocoon-process type=&quot;xslt&quot;?&gt;
 &lt;?xml-stylesheet href=&quot;page.xsl&quot; type=&quot;text/xsl&quot;?&gt;
 &lt;page&gt;
   &lt;country code=&quot;ca&quot;&gt;Canada&lt;/country&gt;
   &lt;country code=&quot;de&quot;&gt;Germany&lt;/country&gt;
   &lt;country code=&quot;fr&quot;&gt;France&lt;/country&gt;
   &lt;country code=&quot;uk&quot;&gt;United Kingdom&lt;/country&gt;
   &lt;country code=&quot;us&quot;&gt;United States&lt;/country&gt;
   &lt;country code=&quot;es&quot;&gt;Spain&lt;/country&gt;
 &lt;/page&gt;
 </PRE>

   <P>You now use the following XSL stylesheet with it</P>

 <PRE>
 &lt;?xml version=&quot;1.0&quot;?&gt;
 &lt;xsl:stylesheet xmlns:xsl=&quot;http://www.w3.org/1999/XSL/Transform&quot;
                 version=&quot;1.0&quot;&gt;

   &lt;xsl:param name=&quot;countrycode&quot;/&gt;

   &lt;xsl:template match=&quot;page&quot;&gt;
     &lt;html&gt;
       &lt;body&gt;
         &lt;xsl:choose&gt;

           &lt;xsl:when test=&quot;not($countrycode)&quot;&gt;
             &lt;p&gt;Choose a country:&lt;/p&gt;
             &lt;form action=&quot;countries.xml&quot; method=&quot;get&quot;&gt;
               &lt;select name=&quot;countrycode&quot; size=&quot;1&quot;&gt;
                 &lt;xsl:apply-templates select=&quot;country&quot; mode=&quot;form&quot;/&gt;
               &lt;/select&gt;
               &lt;input type=&quot;submit&quot;/&gt;
             &lt;/form&gt;
           &lt;/xsl:when&gt;

           &lt;xsl:when test=&quot;country[@code=$countrycode]&quot;&gt;
             &lt;xsl:apply-templates select=&quot;country[@code=$countrycode]&quot;
               mode=&quot;selected&quot;/&gt;
           &lt;/xsl:when&gt;

           &lt;xsl:otherwise&gt;
             &lt;p&gt;Unknown country code
                &lt;em&gt;&lt;xsl:value-of select=&quot;$countrycode&quot;/&gt;&lt;/em&gt;.
             &lt;/p&gt;
           &lt;/xsl:otherwise&gt;

         &lt;/xsl:choose&gt;
       &lt;/body&gt;
     &lt;/html&gt;
   &lt;/xsl:template&gt;

   &lt;xsl:template match=&quot;country&quot; mode=&quot;form&quot;&gt;
     &lt;option&gt;&lt;xsl:value-of select=&quot;@code&quot;/&gt;&lt;/option&gt;
   &lt;/xsl:template&gt;

   &lt;xsl:template match=&quot;country&quot; mode=&quot;selected&quot;&gt;
     &lt;p&gt;&lt;em&gt;&lt;xsl:value-of select=&quot;@code&quot;/&gt;&lt;/em&gt; stands for
        &lt;xsl:value-of select=&quot;text()&quot;/&gt;&lt;/p&gt;
   &lt;/xsl:template&gt;

 &lt;/xsl:stylesheet&gt;
 </PRE>
 
   <P>Viewing <CODE>countries.xml</CODE> now will yield different
   results. When no parameter is given (i.e. using the URL 
   <CODE>countries.xml</CODE>) the browser will receive the following page:
   </P>
   
 <PRE>
 &lt;html&gt;
   &lt;body&gt;
     &lt;p&gt;Choose a country:&lt;/p&gt;
     &lt;form action=&quot;countries.xml&quot; method=&quot;get&quot;&gt;
       &lt;select name=&quot;countrycode&quot; size=&quot;1&quot;&gt;
         &lt;option&gt;ca&lt;/option&gt;
         &lt;option&gt;de&lt;/option&gt;
         &lt;option&gt;fr&lt;/option&gt;
         &lt;option&gt;uk&lt;/option&gt;
         &lt;option&gt;us&lt;/option&gt;
         &lt;option&gt;es&lt;/option&gt;
       &lt;/select&gt;
       &lt;input type=&quot;submit&quot;&gt;
     &lt;/form&gt;
   &lt;/body&gt;
 &lt;/html&gt;
 </PRE>

   <P>Choosing one of the options in the list will result in a request
   for a URL like <CODE>countries.xml?countrycode=fr</CODE> and this page
   will look like:
   </P>

 <PRE>
 &lt;html&gt;
   &lt;body&gt;
     &lt;p&gt;&lt;em&gt;fr&lt;/em&gt; stands for France&lt;/p&gt;
   &lt;/body&gt;
 &lt;/html&gt;
 </PRE>

   <P>If for some reason no country element matching the
   <CODE>countrycode</CODE> parameter is found (e.g.
   <CODE>countries.xml?countrycode=foo</CODE>, you will get the following
   page:</P>

 <PRE>
 &lt;html&gt;
   &lt;body&gt;
     &lt;p&gt;Unknown country code &lt;em&gt;foo&lt;/em&gt;.&lt;/p&gt;
   &lt;/body&gt;
 &lt;/html&gt;
 </PRE>

 </DIV>

 <H1>Cocoon Internals</H1><DIV id="s1">
  <P>The Cocoon publishing system has an engine based on the <EM>reactor</EM> design
  pattern which is described in the picture below:</P>

  <IMG alt="Cocoon Schema" class="figure" src="images/schema.jpg">

  <P>Let's describe the components that appear on the schema:</P>

  <DL>
   <LI><STRONG>Request</STRONG> - 
     Wraps around the client's request and
     contains all the information needed by the processing engine. The request
     must indicate which client generated the request, which URI is being
     requested and which producer should handle the request.
   </LI>
   
   <LI><STRONG>Producer</STRONG> - 
     Handles the requested URI and produces an
     XML document. Since producers are pluggable, they work like subservlets
     for this framework, allowing users to define and implement their own
     producers. A producer is responsible for creating the XML document which is
     fed into the processing reactor. It's up to the producer implementation to
     define the function that produces the document from the request object.
   </LI>
   
   <LI><STRONG>Reactor</STRONG> - 
     Responsible for evaluating which processor should work on the document by
     reacting on XML processing
     instructions. The reactor pattern is different from a processing pipeline
     since it allows the processing path to be dynamically configurable and it
     increases performance since only those required processors are called to
     handle the document. The reactor is also responsible for forwarding the
     document to the appropriate formatter.
   </LI>
   
   <LI><STRONG>Formatter</STRONG> - 
     Transforms the memory representation of
     the XML document into a stream that may be interpreted by the requesting
     client. Depending on other processing instructions, the document leaves
     the reactor and gets formatted for its consumer. The output MIME type of
     the generated document depends on the formatter implementation.
   </LI>
   
   <LI><STRONG>Response</STRONG> - 
     Encapsulates the formatted document along
     with its properties (such as length, MIME type, etc..)
   </LI>
   
   <LI><STRONG>Loader</STRONG> - 
     Responsible for loading the formatted
     document when this is executable code. This part is used for compiled
     server pages (principally XSP) where the separation of content and logic
     is merged and
     compiled into a Producer. When the formatter output is executable code, it
     is not sent back to the client directly, but it gets loaded and executed
     as a document producer. This guarantees both performance improvement
     (since the producers are cached) as well as easier producer development,
     following the common compiled server pages model.
   </LI>
   
  </DL>
 </DIV>

<H1>Cocoon Processing Instructions</H1><DIV id="s1">
  <P>The Cocoon reactor uses XML processing instructions to forward the document
  to the right processor or formatter. These processing instructions are:</P>

<PRE>
&lt;?cocoon-process type=&quot;xxx&quot;?&gt; for processing

      and

&lt;?cocoon-format type=&quot;yyy&quot;?&gt; for formatting
</PRE>

  <P>These PIs are used to indicate the processing and formatting path that the
  document should follow to be served. In the example above, we didn't use them
  and Cocoon wouldn't know (despite the presence of the XSL PIs) that the
  document should be processed by the XSLT processor. To do this, the HelloWorld.xml
  document should be modified like this:</P>

<PRE>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;?cocoon-process type=&quot;xslt&quot;?&gt;
&lt;?xml-stylesheet href=&quot;hello.xsl&quot; type=&quot;text/xsl&quot;?&gt;
&lt;page&gt;
 &lt;title&gt;Hello World!&lt;/title&gt;
 &lt;content&gt;
  &lt;paragraph&gt;This is my first Cocoon page!&lt;/paragraph&gt;
 &lt;/content&gt;
&lt;/page&gt;
</PRE>

  <P>The other processing instruction is used to indicate what formatter should
  be used to transform the document tree into a suitable form for the requesting
  client. For example, in the document below that uses the XSL formatting object
  namespace, the Cocoon PI indicates that this document should be formatted using the
  formatter associated to the <CODE>text/xslfo</CODE> document type.</P>

<PRE>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;?cocoon-format type=&quot;text/xslfo&quot;?&gt;

&lt;fo:root xmlns:fo=&quot;http://www.w3.org/1999/XSL/Format&quot;&gt;
 &lt;fo:layout-master-set&gt;
  &lt;fo:simple-page-master
      page-master-name=&quot;one&quot;
      margin-left=&quot;100pt&quot;
      margin-right=&quot;100pt&quot;&gt;
   &lt;fo:region-body margin-top=&quot;50pt&quot;
       margin-bottom=&quot;50pt&quot;/&gt;
  &lt;/fo:simple-page-master&gt;
 &lt;/fo:layout-master-set&gt;

 &lt;fo:page-sequence&gt;
  &lt;fo:sequence-specification&gt;
   &lt;fo:sequence-specifier-repeating
       page-master-first=&quot;one&quot;
       page-master-repeating=&quot;one&quot;/&gt;
  &lt;/fo:sequence-specification&gt;

  &lt;fo:flow font-size=&quot;14pt&quot; line-height=&quot;14pt&quot;&gt;
   &lt;fo:block&gt;Welcome to Cocoon&lt;/fo:block&gt;  
  &lt;/fo:flow&gt;  
 &lt;/fo:page-sequence&gt; 
&lt;/fo:root&gt;
</PRE>  

</DIV>

<H1>Cocoon Cache System</H1><DIV id="s1">
  <P>In a complex server environment like Cocoon, performance and
  memory usage are critical issues. Moreover, the processing requirement for
  both XML parsing, XSLT transformations, document processing and formatting are
  too heavy even for the lightest serving environment based on the fastest
  virtual machine. For this reason, a special cache system was designed underneath the Cocoon
  engine and its able to cache both static and dynamically created pages.</P>

  <P>Its operation is simple but rather powerful:</P>

  <UL>
   <LI>when the request comes, the cache is searched.</LI>
   <UL>
    <LI>if the request is found;</LI>
    <UL>
     <LI>its <EM>changeable</EM> points are evaluated</LI>
     <LI>if all changeable points are unchanged</LI>
     <UL>
      <LI>the page is served directly from the cache</LI>
     </UL>
     <LI>if a single point has changed and requires reprocessing</LI>
     <UL>
      <LI>the page is invalidated and continues as if it wasn't found</LI>
     </UL>
    </UL>
    <LI>if the request is not found:</LI>
    <UL>
     <LI>the page is normally processed</LI>
     <LI>it's sent to the client</LI>
     <LI>it's stored into the cache</LI>
    </UL>
   </UL>
  </UL>

  <P>This special cache system is required since the page is
  processed with the help of many components which, independently, may change
  over time. For example, a stylesheet or a file template may be updated on
  disk. Every processing logic that may change its behavior over time it's
  considered <EM>changeable</EM> and checked at request time for change.</P>

  <P>Each changeable point is queried at request time and it's up
  to the implementation to provide a fast method to check if the stored page is
  still valid. This allows even dynamically generated pages (for example,
  an XML template page created by querying a database) to be cached and,
  assuming that request frequency is higher than the resource changes, it
  greatly reduces the total server load.</P>

  <P>Moreover, the cache system includes a persistent object
  storage system which is able to save stored objects in a persistent state that
  outlives the JVM execution. This is mainly used for pages that are very
  expensive to generate and last very long without changes, such as compiled
  server pages.</P>

  <P>The store system is responsible for handling the cached pages
  as well as the pre-parsed XML documents. This is mostly used by XSLT
  processors which store their stylesheets in a pre-parsed form to speed up
  execution in those cases where the original file has changed, but the
  stylesheet has not (which is a rather frequent case).</P>
</DIV>
</BODY>
</DOCUMENT><P class="legal">Copyright &copy; 1999-2000 The Apache Software Foundation.<BR>All rights reserved.</P></BODY></HTML>