Upgrading to Apache Forrest 0.8

This page describes some changes to Apache Forrest that affect people who are upgrading to the 0.8 version. If you have other issues, then please discuss on either the dev or user mailing lists. As more experience is gained, this document will be updated.

(If you are upgrading from a version prior to 0.7 then you will need to see the notes for the previous upgrade.)

The following list shows some of the key new features. For the full list of changes, see the main change log and also for each plugin.

• Locationmaps.

Many new initial plugins are in the "whiteboard". See the entries in the change log and see each plugin's documentation and changes log. This includes the new Dispatcher. See Status of Themes: Skins and Dispatcher.

The Locationmaps define the mapping from requests to locations which enables content and resources to be located at various different sources.

Adding a default locationmap to your project is not required, but is advisable. Sooner or later you will use it. Having a default one also reduces the verbosity of the log files. Copy one from a fresh 'forrest seed' to PROJECT_HOME/src/documentation/content/locationmap.xml

Prototype of new xml-based properties system. Projects and plugins can use a forrest.properties.xml file. At this stage, it supplements the existing forrest.properties file. See the projectInfo plugin for an example of its use. Search the dev mailing list for more information.

FOR-920 Merging the defaults and project modules to the new properties module. You can use it like {properties:forrest.home}

In all custom code (e.g. project sitemap or plugins sitemaps) you need to do the following:

• find: {defaults: and replace with {properties:forrest.
• find: {forrest: and replace with {forrest:forrest. or {properties:forrest. (if you do not need the ChainMetaModule)
• find: {project: and replace with {properties:

The consequence of not making such corrections is an error message similar to the following:

Could not find component for role:
[org.apache.cocoon.components.modules.input.InputModule/project]

The most likely cuplrit is forgetting to edit your "project sitemap" explained below. See the glossary if you are confused by terminology.

Do 'forrest clean-work' in each of your projects. This also removes the old Cocoon disk cache.

There is now a filenaming convention for stylesheets (e.g. document-to-html.xsl). This assists with automating the location of such resources. See Locationmap.

For the default use of Forrest, this makes no difference. However, if you have developed your own skin then you will need to do some filename changes, e.g. 'cd skins/my-skin/xslt/html; mv tab2menu.xsl tab-to-menu.xsl' (do each of book2menu.xsl document2html.xsl site2xhtml.xsl tab2menu.xsl). It is advisable to follow this naming convention for your other resources, which will mean that you can utilise the locationmap.

After each release, the "Versioned Docs" are copied to form the new "dev" set. Ideally the docs are then upgraded in readiness for the new release. This has not been completed for the 0.8 release. In particular there are example snippets of sitemaps which have not yet been upgraded to reflect the changes to the sitemaps and the separation of some core stuff into plugins. See issues FOR-546 and FOR-922 and others.

The last time that we upgraded our packaged version of Cocoon trunk was using their SVN r351990 on 2005-12-08. Since then a number of things have happened to cause us to fall out of synchronisation with Cocoon. There is various discussion about this in the Forrest and Cocoon dev mail archives.

If you use your own version of Cocoon, then you will know about the upgrade notes in the $FORREST_HOME/etc/cocoon_upgrade directory. You might be able to advance a bit beyond the SVN revision, but not much. Please help to rectify this situation. See FOR-1015.

See notes in the FAQ about "wholesite".

All xml type files have been formatted using xmlformat. You can apply this to your own work if necessary by using the same configuration as the Forrest project. See notes at FOR-644.

Synchronise your project's skinconf.xml and forrest.properties files.

Take advantage of the separation of concerns. In a new workspace, create a fresh 'forrest seed' site, then tweak its forrest.properties and skinconf.xml until it reflects your old site. When it is ready, replace your project's skinconf.xml and forrest.properties files. Any remaining issues would concern other aspects of your configuration, such as site.xml and your actual content.

It has come to our attention that some people have a project sitemap even though they are not using it. Such un-necessary sitemaps should be removed to avoid maintenance issues.

If you do use a project sitemap, then pay attention to the upgrade instructions "Forrest configuration simplification" above.

...as more issues are discovered/remembered :) Please send feedback to the mailing list.