abstract: cocoon is a free open source product for XML based content creation. This video tutorial shows, how to install the software and it shows some first easy to understand steps to configure it to your needs.

Please note, that cocoon has nothing to do with 3D content creation (although it could… be used also in that context). So this trail is completely unrelated to the blender trail, which is also published on this blog.
cocoon can be found at http://cocoon.apache.org

Watch the video here: [blip.tv ?posts_id=1186308&dest=-1] If you prefer to get a better quality .wmv-version, you can download it from blip.tv

Or read the text:

hello everybody! this is our first tutorial about cocoon 2.2 . This tutorial mostly complements the beginners tutorial of the cocoon documentation, which is titled :

“Your first cocoon application using Maven 2” .

As cocoon provides a tight integration with maven 2, we can make our life very easy, by installing maven beforehand. The major benefit of this decision will be, that the entire cocoon installation will be done automatically for you. Maven is your friend in this case. All you have to do, is to provide some information about dependencies of software modules. So, installing cocoon on your computer, is basically reduced to one single command in your command-line shell.
well, you still have to instal maven first. If you don’t have it yet, just go to the maven site, and get the maven version 2 dot 0 dot 9, or newer. That should work for you. Once you have installed it, come back here and proceed .

are you still there?! cool! then lets proceed now. so, open your command line shell, and navigate to your preferred installation folder. Take care, that you have modification permissions here.
Then tell Maven to create the initial directory structure for your first cocoon-block:

We are using the built-in archetype generator now. so, please Type in the following command:

mvn archetype:generate -DarchetypeCatalog=http://cocoon.apache.org

This will start an interactive process, where you are going to tell maven some basic informations about what exactly you want to get. But first, maven will probably start downloading a huge bunch of software modules, which it needs for its own operation. Eventually you get a prompt, where you have to tell maven, exactly which archetype you want to install. We will select option number 2 here .

This will install a minimal cocoon-block, containing some example files. This choice has the benefit that we will already get a very minimal, but ready to use cocoon-application.
Now you have to provide some formal information about your new cocoon-block.

– The group-ID, defines a unique software identifier. Think of this as your company’s web-domain. We will enter: com, dot my-company, here. Please note, that You will definitely have to provide your own ID.

– Now, enter the artifact-eyedie , set(s–) or in simple words, the name of your block. We choose: “ical” here, but you can name your block however you like.

– Then add a version information. Just use the default.

– Next, specify your java-root package. In our case we are going to use: com.mycompany.ical

– Finally confirm all entries.

your first cocoon block is created inside a sub-directory, which is named exactly as your block. So, navigate to this sub-directory now. If you are curious, then flip through the directory structure and see, where which files have been placed.

We will get back to this in full detail within our next tutorial. For now, just keep it simple and trust us. This is a ready made cocoon block and it will come to life within the next 10 minutes. And 100% of the work will be done by maven. You are the king (or queen) And maven is your servant:

double-check, that you have navigated to the root of your cocoon-block. Then type the command:

mvn jetty:run

And sit back and watch how your computer is now collecting your runtime en-vironment. In fact, maven is creating a web-application, places your cocoon block into this application, and finally builds a web-application-server, based on jetty in our case.

At the very end, maven starts the application server, so that you can open the application on your browser. And you ? You did not have much work until here, didn’t you ?. That’s amazing! isn’t it ?

Ok. Jetty has been started in the final step, and it runs now. So, go to your browser on your local machine, and call the localhost on the port 8888 … and? done!

The initial cocoon-block is life. Of course, the real work will start now. But at least you got the basics up and working. We will go through all steps for building a full web-application within our follow-up tutorials,
including, authentication, interactive pages, and database access.

We will choose the learning-by-doing-approach, so we will directly jump into the doing. But for now take a break, get some coffee, and then let us continue by examining the real heart of your application, the sitemap.

Now, lets move to the sitemap. You find it in the source folder at main/resources/COB-INF/sitemap.xmap

This file contains almost every information, that cocoon must know about your application-data. The information is provided as an xml-tree. There is much to say about this file. But let us focus
on the pipelines section first.

The most basic principle of cocoon is, that data is always processed inside a pipeline. processing always starts with a data source, a so called generator and it ends with a data sink, a serializer. The data walks along the pipeline, where it will be modified by transformers. While the data is passing the pipeline, it is transported as an XML data stream. And the transformers are in most cases simple xslt-processors.

For the beginning, we only need to understand, how we can start a pipeline-process from our browser. This is easy. Just call the application and provide an URL-path. For instance, in our very first call, we provided the empty string, in other words we adressed the application root. Inside the sitemap, we define, what shall happen, when a specific path is provided.

For this purpose, we use the match-tag. And we provide a match-pattern. So if a pattern matches, whatever is declared inside the match-tag, will be processed. Lets look at the matcher for the empty string. As expected, the pattern is the empty string. And it is not very astonishing, that we find a generator,

a transformer, and a serializer here. Each of these constructs provide its own set of parameters. The generator is configured to lookup an xml file on the file system. The source is specified relative to the directory, where the site-map resides. so in our case, the source file is welcome.xml and it is found in the demo sub-folder.

The transformer is a simple xslt processor. It gets the output of the generator, namely the content of the welcome-file, and it forwards the data to the transformer as xml-stream. In the configuration, we also see, that the xsl-transformation-rule-set is stored in the file welcome.xslt . The transformer passes the transformed xml-stream to the serializer, which happens to be an xhtml-serializer. Hence we expect to see an html-output. And indeed, the browser gets an xhtml-data stream as the result of the request.

it is important to understand, that the names of the files on the file system, are fully decoupled from the URL-pathes provided on the browser side. so neither demo/welcome.xml, nor demo/welcome.xslt, will be displayed, when we specify these pathes on the browser command line. if you want to see the content of a file, you must create a new matching rule for it. Translated to cocoon notation this means:

add a new match-tag to the site-map.

So, let us proceed by adding a new matcher for our home-page. The match-pattern shall be : “home”…

– As we have just learned, everything starts with a generator. And in our case, the generator gets its content from the file system. The location of the data file shall be: demo/home.xml and we set the generator source accordingly.

– Let us reuse the xslt transformation rules of the welcome page. So we specify a transformer, and tell it to us demo/welcome.xslt as transformation rule-set.

– Finally we specify a serializer, which creates xhtml code.

Now we examine, what happens, when we call our home page. well, on the browser side, nothing happens. but on the command line, we see immediatley, that cocoon complains about missing files.

oh sure! Yes, we did not yet create the home.xml file, so lets do this now. for simplicity i will copy welcome.xml and modify the copy….

so, after we created home.xml, a new browser call, returns the expected data.

ok, We are finished for now. We have shown, how to install cocoon from the internet by using maven 2. We also have shown how to start the minimal cocoon-application. And finally we have shown, how to add new web-pages to the application by modifying the sitemap.
There is very much more to say. But this has to wait for the next tutorial, where we are also introducing a way to authenticate your web-application with cocoon-native methods.

until then,

have a nice day!