| <?xml version="1.0"?> |
| <html> |
| <head> |
| <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> |
| |
| <p>SoC is something that you've always been aware of: not everybody is equal, |
| not everybody performs the same job with the same ability.</p> |
| |
| <p>It can be observed that separating people with common skills in different |
| working groups increases productivity and reduces management costs, but only |
| if the groups do not overlap and have clear "contracts" that define their |
| operability and their concerns.</p> |
| |
| <p>For a web publishing system, the Cocoon project uses what we call the |
| <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"/> |
| <p> |
| Cocoon is <em>engineered</em> to provide you a way to isolate these four |
| concern areas using just those 5 contracts, removing the contract |
| between style and logic that has been bugging web site development since |
| the beginning of the Web. |
| </p> |
| <p> |
| Let's have an example: |
| </p> |
| <pre class="code"> |
| <page> |
| <content> |
| <para>Today is <dynamic:today/></para> |
| </content> |
| </page> |
| </pre> |
| <p> |
| Such a page is written by the content writers and you give them the |
| "contract" that states that the tag <dynamic:today/> prints out the time of the day |
| when included in the page. Content writers don't care (nor |
| should) about what language has been used for that, nor they |
| can mess up with the programming logic that generates the |
| content since it's stored in another part of the system they |
| don't have access to. |
| </p> |
| <p> |
| So <dynamic:today/> is the "logic - content" contract. |
| </p> |
| <p> |
| At the same time, the structure of the page is given as a contract to |
| the graphic designers who have to come up with the transformation rules |
| that transform this structure in a language that the browser can |
| understand (HTML, for example). |
| </p> |
| <p> |
| So, the page structure is the "content - style" contract. |
| </p> |
| <p> |
| As long as these contracts don't change, the three areas can work in a |
| completely parallel way without overwhelming the human resources used to |
| manage them: costs decrease because time to market is reduced and |
| maintenance costs is decreased because errors do not propagate out of |
| the concern areas. |
| </p> |
| <p> |
| For example, you can tell your designers to come up with a "Xmas look" |
| for your web site, without even telling the other people: just switch to |
| the Xmas transformation rules on Xmas morning and you're done.... just |
| imagine how painful it would be to do this on your web site today. |
| </p> |
| <p> |
| 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> |