8 simple rules for building a manageable Cocoon application

A few notes to self to learn from my own mistakes and avoid spending endless hours next time trying to clean things up when you’re close to production. Some of these rules are of course already part of our internal Cocoon development process, but I thought I could share them online and see if someone has better approaches to suggest to a few simple but cumbersome issues when starting a Cocoon-based project:

  • Don’t even start any development before customizing the Cocoon environment for the project needs. This boils down to “cut the crap”: be ruthless in excluding blocks, don’t enable any of them “just in case”. Unnecessary stuff will clutter at best and bite you at random times in most cases. Do version-control your local.build.properties and local.blocks.properties.
  • Using Cocoon’s xconf tool, have a set of files ready to further edit the Cocoon configurations, cutting even more crap. The block system still has some quirks, and you end up with unnecessary stuff such as JMS or XSP when you don’t need it and really don’t want it around.
  • Always take relocability of your Cocoon application into account, from the very beginning of your project. Your application should work from the webapp root (mounted as /), under a context path (/whatever) or as a sub-sitemap (/whatever/the/user/wants). This means that you should always pass a “mount-point” attribute within your rendering pipelines and components, calculating where your application has been mounted, and building paths accordingly. Unfortunately the current Cocoon API will only tell you the full request path and the URI handled by the sitemap, so you need to mangle those data by substracting (string-wise) the sitemap URI from the request URI in order to obtain the path you’re looking for. That is, if your sitemap is mounted on /context/foo and your request is for /context/foo/bar/baz, the sitemap URI will be bar/baz, while the data you need is actually /context/foo to build your links properly: yeah, that gives me headaches as well, and I have an overdue patch to provide this location in an easier way. But please tell me if I’m just missing an obvious solution.
  • Don’t ever rely on Cocoon samples for functionality. If you need any feature such as XSLTs, JS files or sitemaps, import it into your project right away. Do it now, or you will regret it in the future. A lot.
  • The above note has a special meaning for form handling. The impressive and powerful Cocoon Forms resources are part of the samples. Since you probably want to reuse them, to avoid any temptation, just package everything up in a JAR file and use resource://whatever as your $resources-uri parameter in your forms stylesheets. the following Ant task might come handy:
   <target name="pack-cforms-resources" depends="jar" 
      description="package all the CForms resources">
      <jar jarfile="${dist.dir}/cocoon-forms-block-resources.jar"
          <include name="resources/**"/>
          <exclude name="**/.svn"/>

and, later on:

      <map:transform type="forms"/>
        <map: parameter name="resources-uri" 
  • Keep a very strict separation between application files and resources that a user might want to customize. This is expecially true for stylesheets and client-side javascripts/images/icons. Consider using the xsl:import feature in your stylesheets, providing an empty user-oriented version of your stylesheets, where templates can be overridden. Might hurt performance a bit, but sure helps tremendously for real life scenarios, where your customer is supposed to customise files and you’re supposed to provide updated versions of your applications. If you don’t, every deployment after the first one becomes an incredibly painful process.
  • Ideally, package the whole application as a jar file: remember that Cocoon can easily access jar-packaged resources with the resource: protocol, and this holds true even for that overrideable XSLT who can import from your jar files. You can even package your root sitemap inside a jar and reference it with the resource:// protocol.
  • Don’t forget error and logging management. There is nothing worse that the default Cocoon error page popping up in front of your customers, so plan for a sensible handle-errors section right from the beginning of your project. Also, don’t forget to customise your logkit.xconf file. These resources can be easily part of a shared project codebase, so there is no excuse for preparing them in advance.



1 thought on “8 simple rules for building a manageable Cocoon application”

  1. A while ago, I made an input module that addresses your third point. I have put it on a new page in the Cocoon wiki: http://wiki.apache.org/cocoon/SitemapURIModule

    It has saved me many headaches already.
    If you think it is useful, please add it to the next release of Cocoon (I can’t do that as I am not a committer).

Comments are closed.