Custom blocks in Forrest

This how-to is useful for all those that wish to build Forrest version 0.5+ with blocks that are not part of the default Forrest build. For example XSP, XMLDB or CocoonForms etc... In this how-to we will show how to build XSP into Forrest (n.b. as of 0.6-dev XSP is included with Forrest, however, this is still a useful How-To).

Why do this? Well Forrest has a lot of features that are great, it is a fantastic way to quickly create and manage a project. It would be nice though to able to extend Forrest.


So let's start:

Firstly make sure that you have at least Forrest 0.5 distribution, and the CVS distribution of Cocoon-2.1, and Nekodtd, and Nekopull. If you're unsure about CVS go here and you can get Nekodtd and Nekopull from here:

http://www.apache.org/~andyc/neko/nekodtd-latest.tar.gz
http://www.apache.org/~andyc/neko/nekopull-latest.tar.gz

Having downloaded and extracted everything, you should now have a folder with all these distributions in it. It is important that these live on the same level or there be more editing to do.


local.blocks.properties

Now we need to copy the local.blocks.properties file from Forrest to Cocoon. In a terminal window, do:

g4% sudo cp  xml-forrest/etc/cocoon_upgrade/local.blocks.properties  ../cocoon-2.1/local.blocks.properties

Next edit this file to include all the blocks that you want to build into Forrest. This is done by un-commenting all the required blocks.

Next we build Cocoon:

g4% cocoon-2.1/build.sh


upgrade_cocoon_jars.sh

Once Cocoon has been built we can edit xml-forrest/etc/cocoon_upgrade/upgrade_cocoon_jars.sh. Open this file in your editor. Firstly make sure that your paths to Cocoon, Forrest and Neko* are right, if they all live on the same directory level you should be fine. Make sure that NEKODTD_VERSION and NEKOPULL_VERSION are reflecting the version you downloaded.

{{{BASE=$PWD/dirname $0

COCOON=$BASE/../../../cocoon-2.1 FORREST=$BASE/../.. NEKODTD_VERSION=0.1.6 NEKODTD_HOME=$BASE/../../../nekodtd-$NEKODTD_VERSION NEKOPULL_VERSION=0.2.3 NEKOPULL_HOME=$BASE/../../../nekopull-$NEKOPULL_VERSION}}}

Next we have to tell Forrest what kind of build we are performing. Performing a "real_with_cvs" build copies upgraded jars to their official lib/* locations, and 'cvs add's them, if you are not a commiter to Forrest you will not be able to CVS add them. If you are a commiter you best be very sure that you actually want to upgrade the version of Cocoon in Forrest's CVS. In most cases you will only want to upgrade your local copy. To do this, we want to do a "testing" or "real" build. The problem with "testing" is that the upgrade is only done in your build directory and so each time you rebuild forrest your upgrade will be blown away - consider copying your custom build of Cocoon somewhere safe so you can easily copy it back into place if you rebuild Forrest. You will probably want to use "real", this updates your local official libs so that they will not be blown away when rebuilding Forrest. Uncomment the line you want as follows:

{{{#UPGRADE_TYPE=testing UPGRADE_TYPE=real #UPGRADE_TYPE=real_with_cvs}}}

Finally we want to tell Forrest what blocks we want, remember you have to have built them in Cocoon first or they won't be there. For example if we want to include the Sessions block we include it like so:

{{{bzcopy session-fw #cocoon-session-fw-block.jar}}}

Importantly, for XSP to work in Forrest we must also include

{{{copy jdtcore #jdtcore-2.1.0jar}}}

Next in a terminal window, run xml-forrest/etc/cocoon_upgrade/upgrade_cocoon_jars.sh. This can take a while.

g4% xml-forrest/etc/cocoon_upgrade/upgrade_cocoon_jars.sh

Now you are ready to build Forrest:

g4% xml-forrest/build.sh

You can now create a Forrest project with 'forrest seed' and it will now have the blocks that you've requested. With this method you should be able to build any block into Forrest. Ensure that the block you require does not have additional dependencies.

Lastly to make XSP available to the sitemap, in my-project/sitemap.xmap add the following generator

<map:generator name="serverpages" pool-grow="2" pool-max="32" pool-min="4" src="org.apache.cocoon.generation.ServerPagesGenerator"/>

n.b. Sometimes Forrest will not build because it loses the forrest.build.xml (xml-forrest/build.dist/shbat/forrest.build.xml) If you already have a copy of this save it so you can use it later if needed. Also the same seems to happen sometimes with jing-*.jar (xml-forrest/lib/core/jing-*.jar), if this happens you can grab this jar from the Forrest CVS site.

AddingCocoonBlocksToForrest (last edited 2009-09-20 23:40:38 by localhost)