Defining your own workspace |
Everybody Needs his own Space
Before you start any new work it is always a good technique to modify existing stuff instead of creating from the scratch. Since you are still not as good as not to make any failures you should prevent all settings that are being changed.
Even though we are going to develop only the small application, it is useful to define your own workspace and keep other things working. The way to do this is to make your own directories for your web application and register the path to your application in Cocoon2 sitemap.
Create Directories for your Application
Your application will usually consist of many files of various types. These types usually reflect the decomposition of your application to contents, logic and presentation branches. You should separate your application according to this approach as much as possible, because it seriously simplifies further development and management of your application.
XML Documents
To keep the contents together means creating a directory for all your xml documents contained in your future web application. Usual doc is a good name for this directory and depending on the size of your application it contains other subdirectories grouping documents with similar meaning.
Application Logic
The logic layer serves all the dynamic data for your web application. Although Cocoon2 provides more than just one way how to write the code for your application (XSP, JSP, PHP), the native technology for Cocoon is XSP. There are basically two ways how to organize your logic. For simple application you can mix content with logic and put both to XSP document. Such a document contains besides the contents other XSP tags to include code for generating dynamic data for your XML document (Java code within <xsp:logic> tags). The more advanced technique is grouping the code from XSP pages to document called logicsheet.
Logicsheet is basically XSL file that contains rules for substituting user-defined tags to respective Java code snippets in your xml document. Applying such a transformation all logicsheet recognized xml tags are substituted to Java code thus the resulting xml document is ready for processing by XSP processor. This approach cleans your dynamic xml documents from any Java code, and thus it stays homogenous and better understood for non-programmers. Logicsheets are considered effective for all but small applications, however, for higher simplicity in my examples the logic is included directly in xsp documents. Placing your xsp files to the same directory as other xml documents - documents is not an unforgivable sin, but creating separate directory logic is probably better.
Stylesheets
The final phase of generating and transforming your xml documents is choosing how to present resulting document. The xslt transformation according to xsl stylesheets is used for this purpose. Sometimes you need to design your own stylesheet, sometimes you can find a good one from other projects. To keep your stylesheets organized, put them into directory called stylesheets.
DTD's
If you use standardized xml, you probably have dtd (or xml schema) attached to your xml document. DTD's are very useful, when authors create xml document according to some predefined template (set of tags). Place all dtd's you use in your xml documents to directory called dtd.
Conclusion
Your directory structure for your first applications should look like this:
documents/ dtd/ logic/ resources/ stylesheets/ sitemap.xmap
The sitemap - definition of rule for your URL space
The sitemap is the main improvement of Cocoon2 from versions 1.x. It is the main configuration center for Cocoon web applications. The main purpose of the sitemap is to install and configure executive components and to define the way and consequence, how your web pages will be generated.
Main Sitemap
As the sitemap is xml document, it has the clear and concise format. It is easy to read and it probably encourages you to make changes directly to this file. However, it is not reasonable to make too many changes to the main sitemap, because if you make any mistake you can alter the behavior of other Cocoon applications (as examples in Cocoon distribution).
Subsitemap
Cocoon2 provides the way how you can isolate settings applicable only for your web application. This feature is called subsitemap and it means that you make your own copy of sitemap which contains only settings applicable to your application. Then you "mount" your subsitemap to the main sitemap by simply adding the pipeline element which contains <map:mount> tag. Pipelines in general contain information about resolving your URL names to expected document (i.e. html). The pipeline for main sitemap for mounting your web application should look like this:
<map:pipeline>
<map:match pattern="xbank">
<map:redirect-to uri="xbank/login"/>
</map:match>
<map:match pattern="xbank/**">
<map:mount uri-prefix="xbank/"
src="projects/xBank/" check-reload="yes"/>
</map:match>
</map:pipeline>
The first <map:match> element is the rule for resolving URL http://{server}/cocoon/xbank. It simply redirects the processing to http://{server}/cocoon/xbank/login URL in this pipeline. The second <map:match> says that all URLs starting with xbank are processed by rules in other sitemap - subsitemap. The src attribute identifies the directory where to find sitemap.xmap for rules for your subsitemap and should always point to your web application root directory (in this case {wepappdir}/projects/xBank/).
Your Subsitemap^
The actual instructions for processing /login request are located in the subsitemap of your application. One can look like this:
<map:pipeline>
<map:match pattern="login">
<map:generate type="file" src="docs/login.xml"/>
<map:transform type="xslt"
src="stylesheets/simple-page2html.xsl"/>
<map:serialize type="html"/>
</map:match>
<map:pipeline>
In this case the /login document is generated from file docs/login.xml, then the resulted xml tree is transformed by xslt to another xml tree using simple-page2html.xsl stylesheet (now it contains correct HTML tags, but it is still an XML). Finally the XML is serialized (streamed out) as a regular HTML document.
Normally you do not have to specify the type attribute for default components (generators, transformers, serializers, ...). In previous example you might omit type attribute in all components, because "file" is the default generator, "xslt" is the default transformer and "html" is the default serializer.
Default Components
It is possible to change default components only for your subsitemap by defining something like this:
<map:components>
<map:generators default="file"/>
<map:transformers default="xslt"/>
<map:readers default="resource"/>
<map:serializers default="html"/>
<map:selectors default="browser"/>
<map:matchers default="wildcard"/>
</map:components>
The meaning of this is that the set of generators (defined in main sitemap) is left untouched, but the new default generator is of type file. For complete set of all components in your Cocoon2 distribution please check the <map:components> element in the main sitemap.