Author: bdelacretaz
Date: Fri Mar 25 13:26:13 2005
New Revision: 159066
URL: http://svn.apache.org/viewcvs?view=rev&rev=159066
Log:
add more content to the concepts page
Modified:
cocoon/trunk/src/documentation/src/content/xdocs/concepts/content_en.xml
Modified:
cocoon/trunk/src/documentation/src/content/xdocs/concepts/content_en.xml
URL:
http://svn.apache.org/viewcvs/cocoon/trunk/src/documentation/src/content/xdocs/concepts/content_en.xml?view=diff&r1=159065&r2=159066
==============================================================================
--- cocoon/trunk/src/documentation/src/content/xdocs/concepts/content_en.xml
(original)
+++ cocoon/trunk/src/documentation/src/content/xdocs/concepts/content_en.xml
Fri Mar 25 13:26:13 2005
@@ -4,6 +4,12 @@
<title>Cocoon concepts</title>
</head>
<body>
+ <h1>Overview</h1>
+ <p>
+ This document gives a brief overview of the most important
+ concepts used in Cocoon.
+ </p>
+
<h1>Separation of Concerns (SoC)</h1>
<p>We believe the single most important Cocoon innovation is SoC-based
design.</p>
@@ -16,8 +22,8 @@
operability and their concerns.</p>
<p>For a web publishing system, the Cocoon project uses what we call
the
- <em>pyramid of contracts</em> which outlines four major concern
areas and five
- contracts between them. Here is the picture:
+ <em>pyramid of contracts</em>, with four major concern areas and
five
+ contracts between them:
</p>
<img alt="The Cocoon Pyramid Model of Contracts"
src="files/pyramid-model.gif"/>
@@ -28,15 +34,6 @@
the beginning of the Web.
</p>
<p>
- Why? because programmers and graphic people have very different
skills
- and work habits... so, instead of creating GUIs to hide the things
that
- can be harmful (like graphic to programmers or logic to designers),
- Cocoon allows you to separate the things into different files,
allowing
- you to "seal" your working groups into separate virtual rooms
connected
- with the other rooms only by those "pipes" (the contracts), that
you
- give them from the management area.
- </p>
- <p>
Let's have an example:
</p>
<pre class="code">
@@ -84,5 +81,128 @@
With the Cocoon architecture all this is a couple of line changes
away.
</p>
+ <h1>Semantic markup</h1>
+ <p>
+ Although it is not a Cocoon invention, <em>semantic markup</em> is
+ very important to work efficently with Cocoon.
+ </p>
+ <p>
+ By <em>semantic markup</em> we mean a way of building XML documents
+ and models which preserves semantic information (metadata) as much
as possible,
+ by keeping the data in structured format and moving to presentation
+ formats as late as possible in the document transformation process.
+ </p>
+ <p>
+ This document, for example:
+ <pre class="code">
+<page>
+ <author id="3243">Will Coyote<author>
+ <created>2005-03-12</created>
+ <revision>1.42</revision>
+ <content>
+ Once upon a time, John made a <b>bold</b> move...
+ </content>
+</page>
+ </pre>
+ contains structured information, that can be filtered and selected
+ at Will to generate different presentations.
+ </p>
+ <p>
+ As you can see, there's nothing very sophisticated about semantic
+ markup: the basic idea is to keep <em>everything that is known</em>
+ about a given document or piece of information in a structured
format.
+ This makes it possible to precisely select the information elements
+ that must be published, and to format them in as many ways as
needed.
+ </p>
+
+ <h1>The sitemap</h1>
+ <p>
+ The <em>sitemap</em> is a central component of any Cocoon
application,
+ acting as a very powerful <em>request dispatcher</em>. It was the
single most
+ important innovation of Cocoon 2, and it is not going away soon:
we <em>love</em> its power!
+ </p>
+ <p>
+ The main role of the sitemap is to trigger the execution of
<em>pipelines</em>
+ to process client requests. The sitemap uses <em>matchers</em> to
select
+ which pipeline to execute, matching various attributes of the
incoming request
+ (often the request path, but many other attributes can be used) to
activate
+ the first pipeline which matches the incoming request.
+ </p>
+ <p>
+ Here are a few examples of matchers:
+ <pre class="code">
+<map:match pattern="*.html">
+ ...pipeline definition goes here
+ </pre>
+ This pipeline would be activated for any request for a filename
which
+ ends in <em>*.html</em>.
+
+ <pre class="code">
+<map:match pattern="**/resources/css/*.css">
+ ...pipeline definition goes here
+ </pre>
+ This pipeline would be activated for requests having paths like
+ <em>something/resources/css/mystyles.css</em>
+ or
+ <em>a/b/c/d/resources/css/mystyles.css</em>
+ </p>
+ <p>
+ Sitemap variables give access to the matched parts of the request,
+ for example to apply a common XSLT transform to all XML files found
+ in a given directory:
+ <pre class="code">
+<map:match pattern="**/*.html">
+ <map:generate src="content/{1}/{2}.xml"/>
+ <map:transform src="xslt/my-transform.xsl"/>
+ <map:serialize type="html"/>
+</map:match>
+ </pre>
+ For the request <em>docs/planets/mars.html</em>, this pipeline
would
+ use the XML file <em>content/docs/planets/mars.xml</em> for input,
+ process it with the <em>xslt/my-transform.xsl</em> XSLT transform,
+ and send the result as an HTML document to the client. The double
+ star (**) in the matcher pattern matches a path, while a single
star matches
+ a filename.
+ </p>
+ <p>
+ This last example also introduces the usual components of a
pipeline:
+ the <em>Generator</em> produces XML data, zero or more
<em>Transformers</em>
+ process the XML and at the end a <em>Serializer</em> converts the
XML
+ into the appropriate format and defines the <em>Content-Type</em>
of the
+ output.
+ </p>
+ <note>
+ The XML data passes as <em>SAX events</em> from one component to
the
+ next in the pipeline.
+ </note>
+ <p>
+ There's much more to the sitemap: it can contain component
definitions,
+ define <em>views</em> to make the various stages of the pipeline
available
+ for debugging, define <em>flowscripts</em> to act as the glue
between
+ pages, and several other things that we'll discuss at a later
point. Sitemaps
+ can also be "mounted" to create hierarchies of sitemaps and
modularize
+ applications.
+ </p>
+
+ <h1>Flow</h1>
+ <fixme author="BD">
+ TODO: a brief description of this might be good here to
+ have all the critical concepts in a single document.
+ </fixme>
+
+ <h1>Cocoon Forms</h1>
+ <fixme author="BD">
+ TODO: a brief description of this might be good here to
+ have all the critical concepts in a single document.
+ </fixme>
+
+ <h1>Business logic</h1>
+ <fixme author="BD">
+ TODO: a brief description of this might be good here to
+ have all the critical concepts in a single document.
+ <p>
+ Talk about the integration of Java code, REST backends, etc.
+ </p>
+ </fixme>
</body>
</html>
