Return-Path: 
 <cocoon-docs-return-428-apmail-xml-cocoon-docs-archive=xml.apache.org@xml.apache.org>
Delivered-To: apmail-xml-cocoon-docs-archive@xml.apache.org
Received: (qmail 69327 invoked by uid 500); 4 Feb 2003 21:59:58 -0000
Mailing-List: contact cocoon-docs-help@xml.apache.org; run by ezmlm
Precedence: bulk
list-help: <mailto:cocoon-docs-help@xml.apache.org>
list-unsubscribe: <mailto:cocoon-docs-unsubscribe@xml.apache.org>
list-post: <mailto:cocoon-docs@xml.apache.org>
Reply-To: cocoon-docs@xml.apache.org
Delivered-To: mailing list cocoon-docs@xml.apache.org
Received: (qmail 69245 invoked from network); 4 Feb 2003 21:59:57 -0000
Received: from otsrv1.iic.rug.ac.be (157.193.121.51)
  by daedalus.apache.org with SMTP; 4 Feb 2003 21:59:57 -0000
Received: from otsrv1.iic.rug.ac.be (localhost [127.0.0.1])
	by otsrv1.iic.rug.ac.be (8.11.6/8.11.6) with ESMTP id h14M02t00376
	for <cocoon-docs@xml.apache.org>; Tue, 4 Feb 2003 23:00:02 +0100
Date: Tue, 4 Feb 2003 23:00:02 +0100
Message-Id: <200302042200.h14M02t00376@otsrv1.iic.rug.ac.be>
From: stevenn@outerthought.org
To: cocoon-docs@xml.apache.org
Subject: [WIKI-UPDATE] BeginnerSimpleWebappOrganisation Tue Feb  4 23:00:02
 2003
X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N

Page: http://wiki.cocoondev.org/Wiki.jsp?page=BeginnerSimpleWebappOrganisation, version: 1 on Tue Feb  4 21:32:15 2003 by Dabbous

New page created:
+ !! Organising your development (cookbook)
+ - TARGET-AUDIENCE: __*beginner*__ advanced expert\\
+ - COCOON-RELEASES: 2.0.3, 2.0.4\\
+ - DOCUMENT-STATUS: __*draft*__ reviewed released\\
+ ----
+ 
+ !What you will get from this page
+ I will show you , how you can setup a cleanly separated development
+ environment with minimal modifications of the existing Cocoon infrastructure.
+ You will end up with a hierarchy of folders all completely under your
+ control with only one modification in the Cocoon standard distribution.
+ 
+ !Your basic skills
+ *You have basic knowledge about XML
+ *You know how to move within a command line shell to your OS
+ 
+ !Technical prerequisites
+ *You need a cleanly installed version of Cocoon.
+ If you don't have access to Cocoon right now, you can just
+ install it on your local computer. Please refer to [BeginnerInstallation] 
+ for further infos.
+ 
+ !Links to other information sources
+ ...
+ 
+ !The organisational problem
+ Once you have installed Cocoon you will want to start doing something
+ valuable with the system. The very first encounter with Cocoon will
+ take place on the Cocoon sitemap, which happens to be a file right
+ in the root directory of the Cocoon webapplication: sitemap.xmap. 
+ 
+ You are told, sitemap.xmap is the heart of Cocoon and in order to get
+ Cocoon doing something for you, you shall modify this file in first place. 
+ Then you open the file and first get overwhelmed with a rather complex
+ XML-structure. There is a clear need to keep this as untouched as possible.
+ Not only you want to keep the Cocoon infrastructure intact and
+ operating, you also have the feeling, you want to keep your work
+ cleanly separated from the Cocoon distribution. 
+ 
+ !Separating your work by use of subsitemaps
+ Because Cocoon is designed for high scalability,
+ there is a concept of "divide and conquer" just built
+ into the sitemap concept. The concept of ''submounting'' is well 
+ described in the Cocoon documentation. See chapter ["the sitemap"|http://xml.apache.org/cocoon/userdocs/concepts/sitemap.html]
+ 
+ We will use subsitemaps in order to get our work separated out
+ into a hierarchy of subfolders. And here is how it's done:
+ 
+ !Part I: setting up a generic mountpoint
+ * Move to the main folder of the Cocoon webapplication. I will name this folder ''$cocoon_root''.
+ * edit the original sitemap.xmap in $cocoon_root:
+ ** Search for the line with </map:pipelines> . This is the end tag of the pipelines bracket (near the end of the file).
+ ** Add following code snippet right BEFORE the endtag </pipelines> and save your modifications:{{{
+ 
+      <map:pipeline>
+        <map:match pattern="*/**">
+          <map:mount check-reload="yes"
+                     reload-method="synchron"
+                     src="{1}/sitemap.xmap"
+                     uri-prefix="{1}"/>
+       </map:match>
+      </map:pipeline>
+ }}}
+ * create a new folder for your own work. The folder name is arbitrary. I will use the name "work" as a placeholder.
+ 
+ SO what effect has this slight modification of sitemap.xmap on the system ? 
+ Now Cocoon will look into your personal working folder when you issue a 
+ command like {{http://localhost:8080/cocoon/work/mypage}} on your browser. 
+ 
+ Once you have modified Cocoon in the described way, you can place subfolders of 
+ arbitrary names into $cocoon_root and you will never again need to modify the 
+ root sitemap. The trick is the match pattern "*/**" which triggers on:
+ 
+ 1 - an URL, that points to the Cocoon webapp\\
+ 2 - followed by a '/'\\
+ 3 - followed by an arbitrary foldername   (the first "*" in the pattern)\\
+ 4 - followed by a '/'                     (the "/" in the pattern)\\
+ 5 - followed by a path of arbitrary depth ("**" in the pattern). 
+ 
+ i.e. in the above example:
+ {{{
+ http://localhost:8080/cocoon/work/mypage   <-- URL
+ ~~~~~~~~~~~1~~~~~~~~~~~~~~~~2~~3~4~~5~~~ 
+                                 */**       <-- pattern
+ }}}
+ 
+ When triggered, Cocoon tries to open a subsitemap within the subfolder matching the
+ first "*" of the pattern. And now we are ready for the secnd part of our setup.
+ 
+ !Part II connecting your work folder with Cocoon
+ As you may already know from the documentation, Cocoon looks for a subsitemap in the
+ location specified by the src attribute of the <map:mount> tag. This means, we need to
+ place another sitemap.xmap into our "work" folder. This sitemap.xmap file now contains
+ only the bare necessities for your work. At the beginning this file may be very short.
+ 
+ Assume, you want to serve an XML-content that is serialized into an HTML-output by
+ use of an XSL-transformation. I think, this is the "simplest use case" for Cocoon.
+ I assume, the XSLT transformation is kept in the file "mytransform.xsl" and all
+ files, you want to serve have the ending ".xml" . The ongoing setup is straight
+ forward:
+ 
+ * Enter your work folder
+ * Create a new sitemap.xmap within your work folder and place following content into the newly created file:{{{
+ <?xml version="1.0"?>
+ <map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
+ 
+   <map:components>
+     <map:generators   default="file"/>
+     <map:transformers default="xslt"/>
+     <map:readers      default="resource"/>
+     <map:serializers  default="html"/>
+     <map:matchers default="wildcard"/>
+   </map:components>
+ 
+   <map:pipelines>
+     <map:pipeline>
+       <!-- xml files -->
+       <map:match pattern="*.html">
+         <map:generate src="{1}.xml"/>
+         <map:transform src="mytransform.xsl"/>
+         <map:serialize type="html"/>
+       </map:match>
+     </map:pipeline>
+   </map:pipelines>
+ </map:sitemap>
+ }}}
+ 
+ What did we achieve by now?
+ First we told cocoon to start a xslt transformation whenever we try to retrieve
+ an html file from the work folder. I.e. the follwing URL 
+ {{http://localhost:8080/cocoon/work/index.html}}
+ gets Cocoon to look for a file named "index.xml" within your work folder. Then the
+ file "index.xml" is transformed by use of the xslt transformation stored in
+ "mytransform.xsl".Finally the result is serialised by use of the html-serialiser.
+ The final result is snt to the browser as standard html-file.
+ 
+ Of course you may want to name your xsl transform differently, or you
+ may choose not to use the pattern "*.html" to trigger this pipeline.
+ From here it's up to you, how you proceed.
+ 
+ Please note only one crucial point: the match patterns are completely decoupled
+ from the true names of files in your folder. e.g. you may choose the pattern
+ 
+ "*.xml" instead of "*.html" and keep the rest of the pipeline as is. Then
+ Cocoon would send back your html-result, if it encounters the URL 
+ {{http://localhost:8080/cocoon/work/index.xml}} (see: Although you
+ ask for "index.xml", you get back a html result!)
+ 
+ !some slightly more advanced issues
+ 
+ * Now you have managed to separate your work from the Cocoon distribution. If you want to go one step further and even take out the whole work folder from the $cocoon-root, this can't be done in the first place. But i can tell you a trick, that would work on unix based OS's:
+ 
+ * You may use a softlink to point to your workfile and place this softlink right into your Cocoon webapp folder. By this you may reinstall Cocoon and the only thing you have to do afterwards is modify the root sitemap.xmap again as described above and place the softlink again into the root folder.
+ 
+ ----
+ ! page metadata
+ - AUTHOR:\\
+ - AUTHOR-CONTACT: [author|mailto:author@site.com]\\
+ - REVIEWED-BY:\\
+ - REVIEWER-CONTACT:\\
+