| <?xml version="1.0" encoding="ISO-8859-1"?> |
| <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../dtd/document-v10.dtd"> |
| |
| <document> |
| <header> |
| <title>How to run and explore the Cocoon samples</title> |
| <authors> |
| <person name="Bertrand Delacrétaz" email="bdelacretaz@codeconsult.ch"/> |
| </authors> |
| </header> |
| |
| <body> |
| |
| <s1 title="Overview"> |
| <p> |
| This How-To shows you how to run and explore the Cocoon samples. It requires no |
| prior knowledge of Cocoon. |
| </p> |
| </s1> |
| |
| <s1 title="Purpose"> |
| <p> |
| 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. |
| </p> |
| </s1> |
| |
| <s1 title="Intended Audience"> |
| <p> |
| Beginning Cocoon users or people evaluating Cocoon for the first time. |
| </p> |
| </s1> |
| |
| <s1 title="Prerequisites"> |
| <p>You only need a JDK (1.3 or later) installed on your computer, and an Internet connection |
| to download Cocoon.</p> |
| |
| </s1> |
| |
| <s1 title="Steps"> |
| <p> |
| Here's how to proceed. |
| </p> |
| |
| <s2 title="1. Get Cocoon"> |
| <p> |
| Download Cocoon from the location listed on the |
| <link href="http://cocoon.apache.org">cocoon.apache.org</link> |
| web site. |
| </p> |
| <note> |
| If you want the latest bleeding edge version, you can get it from CVS, this is described on |
| the site as well, but more complicated if you're not familiar with CVS. |
| </note> |
| </s2> |
| |
| <s2 title="2. Build and start Cocoon"> |
| <p> |
| Unpack the Cocoon distribution and follow the instructions found in the |
| <em>INSTALL.txt</em> file to build |
| Cocoon. |
| </p> |
| <note> |
| If you have done this previously, make sure to remove any local.* configuration files that you |
| might have created. You usually want to activate all Cocoon components to look at the samples, |
| and local.* files might disable some components or even disable the samples. |
| </note> |
| <note> |
| Also, if you have already built Cocoon with a different configuration before, you might need to |
| do a "build clean" first, to prevent any conflicts between different configurations. |
| |
| </note> |
| <p> |
| The INSTALL.txt file also contains instructions for starting Cocoon with the <em>cocoon.sh</em> or |
| <em>cocoon.bat</em> script, which is the simplest way and is sufficient to explore the samples. |
| </p> |
| |
| </s2> |
| |
| <s2 title="3. Access the samples"> |
| <p> |
| 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 |
| <em>samples</em> link. |
| </p> |
| <p> |
| You should now see a page with links to many samples ( |
| <em>Hello World!</em>, etc.), which show you what Cocoon is about. |
| Note that there are several categories of samples: do not forget to look at the |
| <em>blocks |
| with samples</em> page, which contains samples based on components which are not part of the Cocoon core. |
| </p> |
| <p> |
| Another category is the |
| <em>scratchpad</em> samples , these are based on experimental |
| components that might or might not be included later in the Cocoon core or in a Cocoon block. |
| </p> |
| </s2> |
| |
| <s2 title="4. Study the samples"> |
| <p> |
| Now comes the interesting part: looking at the samples innards to find out how they are built. |
| </p> |
| <p> |
| 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: |
| </p> |
| <ul> |
| <li>If using the standard build configuration, samples are found under the |
| <em>build/webapp/samples</em> directory. That's where you want to look |
| to find out how a particular sample works. |
| </li> |
| <li>Under this directory, the pathnames are the same than after the |
| <em>http://localhost:8888/samples</em> base URL. The |
| midi block samples, for example, are accessed from |
| <em>http://localhost:8888/samples/midi</em> |
| and the corresponding files are found under |
| <em>build/webapp/samples/midi</em>. |
| </li> |
| <li> |
| When studying how a sample is built, it is recommended to first study its <em>sitemap.xmap</em> |
| files, which map incoming requests to pipelines. |
| </li> |
| </ul> |
| </s2> |
| </s1> |
| |
| <s1 title="Conclusion"> |
| <p> |
| We hope that this How-To will help you explore the samples yourself, as this |
| is probably the best way of learning about Cocoon. |
| </p> |
| <p> |
| Do not forget to look at the reference documentation though, once you have found |
| out which Cocoon components you need for your application. |
| </p> |
| </s1> |
| |
| <s1 title="Comments"> |
| <p> |
| Care to comment on this How-To? |
| Help keep this document relevant by passing along any constructive feedback to the |
| <link href="mailto:docs@cocoon.apache.org?subject=howto-explore-samples:">cocoon-docs</link> |
| mailing list. |
| </p> |
| </s1> |
| |
| </body> |
| </document> |