How to run and explore the Cocoon samples
This How-To shows you how to run and explore the Cocoon samples. It requires no prior knowledge of Cocoon.
You will learn how install and run Cocoon in the simplest way, in order to run the Cocoon samples, and also how to study the samples from the inside to see how their are built.
Beginning Cocoon users or people evaluating Cocoon for the first time.
You only need a JDK (1.3 or later) installed on your computer, and an Internet connection to download Cocoon.
Here's how to proceed.
1. Get Cocoon
Download Cocoon from the location listed on the cocoon.apache.org web site.
2. Build and start Cocoon
Unpack the Cocoon distribution and follow the instructions found in the INSTALL.txt file to build Cocoon.
The INSTALL.txt file also contains instructions for starting Cocoon with the cocoon.sh or cocoon.bat script, which is the simplest way and is sufficient to explore the samples.
3. Access the samples
Once Cocoon starts (and assuming you have kept the standard configuration), point your browser at http://localhost:8888, this should show the "Welcome to Apache Cocoon" page. On this page, click the samples link.
You should now see a page with links to many samples ( Hello World!, etc.), which show you what Cocoon is about. Note that there are several categories of samples: do not forget to look at the blocks with samples page, which contains samples based on components which are not part of the Cocoon core.
Another category is the scratchpad samples , these are based on experimental components that might or might not be included later in the Cocoon core or in a Cocoon block.
4. Study the samples
Now comes the interesting part: looking at the samples innards to find out how they are built.
This is fairly simple as the directory structure of the samples is similar to the URLs used to access the samples. These simple rules should help you find out much more about the samples:
- If using the standard build configuration, samples are found under the build/webapp/samples directory. That's where you want to look to find out how a particular sample works.
- Under this directory, the pathnames are the same then after the http://localhost:8888/samples base URL. The midi block samples, for example, are accessed from http://localhost:8888/samples/midi/ (note: the trailing slash is required) and the corresponding files are found under build/webapp/samples/midi.
- When studying how a sample is built, it is recommended to first study its sitemap.xmap files, which map incoming requests to pipelines.
We hope that this How-To will help you explore the samples yourself, as this is probably the best way of learning about Cocoon.
Do not forget to look at the reference documentation though, once you have found out which Cocoon components you need for your application.
Care to comment on this How-To? Help keep this document relevant by passing along any constructive feedback to the cocoon-docs mailing list.