===========================================================================
  Copyright 2005 The Apache Software Foundation

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
===========================================================================
README.TXT for the bricks-cms app: how to configure, build and run it
$Id$
===========================================================================

This directory contains the source code of the bricks-cms application,
that will be presented at the GetTogether 2005.

See the STATUS.TXT for information about what to expect from the app, and
http://wiki.apache.org/cocoon/BricksCms page for the latest information.


SOME ASSEMBLY REQUIRED
The target audience for this example app is Java and/or XSLT developers
who want to create their own applications with Cocoon.

If you know nothing about Java and XSLT and have never used the command
line of your system, this example application is probably not for you,
don't waste your time!

There are other Cocoon tutorials (the Supersonic Tour for example) which
will be much easier to grasp for non-programmers.


REQUIREMENTS
The application and its build system have been successfully tested on
MacOSX, Linux and Windows, see http://wiki.apache.org/cocoon/BricksCms
for details.

You'll need:
 - JDK 1.4.x (tested with 1.4.2_05 on macosx).
 - ant 1.6.1, see below.
 - The bricks-cms code, obviously, which currently resides at
    http://svn.apache.org/repos/asf/cocoon/whiteboard/example-apps/bricks-cms/


CONFIGURING
Read user.properties and adjust settings by creating a local.user.properties 
if needed. All configurable properties are explained there, you'll need at
least to set the cocoon.distro.home property.

If you modify the application and need to activate more Cocoon blocks, see
the src/cocoon/config/cocoon.build.properties file, which has a slightly 
different syntax than the stock Cocoon build.properties file.


BUILDING
The build needs ant 1.6.1 or later, which must be correctly setup
in your environment. If you don't know how to do this, it might be good
to understand how environment variables work before going further, to
avoid frustration.

For some reason the version of ant which is included in the Cocoon 
repository does not work for the bricks-cms app (it gives a 
java.lang.ExceptionInInitializerError when attempting to start the 
app), for now you'll need to install your own version of ant 
(http://ant.apache.org/).

The JAVA_HOME environment variable must also be set correctly.

If you have the correct version of ant in your environment, typing "ant"
in the bricks-cms directory should say:

  Buildfile: build.xml

  explain:
       [echo] See README.TXT for how to setup and use this module

  BUILD SUCCESSFUL
  
If this works, type "ant run" and follow the on-screen instructions
(INCLUDING the one about ant derby:create ;-)


RUNNING
If the above ant test works, you'll need to run "ant cocoon:get" once
to compile Cocoon and put the result in the build/cocoon directory.

This requires the cocoon.distro.home property to be set correctly
in the (local.)user.properties file.

Also, the database must be created with "ant derby:clean derby:create",
which erases all the data in case the database was already present.

Then, "ant run" should start the application, which will be made
available at http://localhost:8888.

The application is started by the standard "cocoon.sh" script, so you
can use the environment variables that this script understands to
customize how the app is run (port, etc.).


TESTING
The current code can be tested as follows:

-Start with "ant run" as explained above

-Navigate to http://localhost:8888/

-Follow the links to the the main bricks-cms application and to
 the document editor (http://localhost:8888/bricks-cms/admin/document-editor/)

-Follow the links and instructions to create and view documents.

There are also some test links at http://localhost:8888/bricks-cms/test/, 
which can be helpful to diagnose problems.  


TIPS AND TRICKS:
Use rsync -r src/cocoon/webapp/* build/cocoon/webapp/ to update the 
running webapp without having to restart it. 

This allows you to activate any changes made to non-java code 
(sitemaps, XSLT, etc) in the src tree, by copying the changed files 
to the running webapp.

The "clean-classes" build target deletes all compiled classes from
the bricks-cms project, but keeps the contents of the build/cocoon
directory.