Living on the edge.
Introduction
Since the dispatcher is in the whiteboard, we can afford to use the latest features available in forrest. This helps to test these new features and to be prepared for the future when this feature is standard.
forrest.properties.xml
We needed to prevent having references from the core to a plugin. This can be done with the new properties system. You can override any of the following values via a forrest.properties.xml in your project.
<property name="dispatcher.theme" value="pelt"/>
<property name="dispatcher.fallback.theme" value="common"/>
<property name="dispatcher.theme-ext" value=".fv"/>
<property name="dispatcher.fallback.theme-ext" value=".fv"/>
<property name="dispatcher.themer" value="org.apache.forrest.themes.core"/>
<property name="dispatcher.home" value="org.apache.forrest.plugin.internal.dispatcher"/>
Using properties in contracts
In the contract body you can access all forrest properties by
<xsl:param name="defaultVariables" select="'test.html'"/>
then extract the variable like:
<xsl:variable name="skin-img-dir" select="$defaultVariables/*/*[@name='THE_PROPERTY']/@value"/>
more information which variables are available can be found at http://localhost:8888/**.props which connects to the org.apache.forrest.plugin.output.inputModule plugin. A custom generator contacts the forrest properties input module to get all aviable key/values and outputs them to xml (dtd like forrest.properties.xml).
locationmap.xml
One of the main features of the dispatcher is its fallback mechanism. We are not only looking into one or two places but a sophisticated list of locations. These locations are defined in the locationmap.xml. Like with the forrest.properties.xml you can override any match in there by implementing it in your project locationmap.xml.
Hands on the lm
The resolving process of the structurer responsible for the URL has implemented a high amount of fallbacks. Let us have a look.
<match pattern="resolve.structurer.**">
<!--
FIXME - Problem with the pattern
********************************
We have encountered a strange problem with the pattern 'resolve.structurer.**'.
The {1} sometimes matches nothing, whereas {../1} is OK.
On the contrary, the {../1} sometimes matches nothing, whereas {1} is OK.
As a temporary workaround, we put {../1}{1} which covers all the cases.
CF. FOR-893
structurer templating
*********************
URL specific structurer templates (project-based) e.g. index.fv
* either in the structurer/url
* or in the xdocs dir [deprecated]
have priority *before*
a) sourcetype based e.g. document-v20.fv
b) resourceTypeAction based on meta data e.g. xhtml.fv
(demonstrates lenya meta data integration for DOCO)
c) RecursiveDirectoryTraversalAction e.g. samples/common.fv
c1) url dir
c2) xdocs dir [deprecated]
If no structurer template can be found in the project,
we use either the templates provided by the
a) custom implementation of the themes.core plugin
b) themes.core plugin
where we test for
1) {properties:dispatcher.theme}{properties:dispatcher.theme-ext}
2) {properties:dispatcher.fallback.theme}{properties:dispatcher.fallback.theme-ext}
-->
<select type="exists">
<!-- project-based
url-based (url location) -->
<location
src="{properties:resources}/structurer/url/{1}{properties:dispatcher.theme-ext}"
/>
<!-- project-based
url-based (xdocs location) [deprecated]-->
<location src="{properties:content.xdocs}{1}{properties:dispatcher.theme-ext}" />
<act type="sourcetype" src="{properties:content.xdocs}{1}.xml">
<!-- Sourcetype based
http://forrest.apache.org/docs/cap.html-->
<location src="lm://dispatcher.structurer.resourceType.{sourcetype}" />
</act>
<act type="resourceTypeAction">
<parameter value="{../1}{1}" name="request"/>
<parameter value="{properties:content.xdocs}" name="projectDir"/>
<parameter value="lm://dispatcher.structurer.resourceType."
name="resourceTypeBase"/>
<parameter value=".xml.meta" name="metaExtension"/>
<parameter value="resourceType" name="resourceTypeElement"/>
<parameter value="http://apache.org/cocoon/lenya/page-envelope/1.0"
name="resourceTypeElementNS"/>
<!-- Meta data based -->
<location src="{uri}" />
</act>
<act type="RecursiveDirectoryTraversalAction">
<parameter value="{../1}{1}" name="request"/>
<parameter value="{properties:dispatcher.theme}" name="projectFallback"/>
<parameter value="{properties:dispatcher.theme-ext}"
name="projectExtension"/>
<parameter value="{properties:resources}structurer/url/" name="projectDir"/>
<!-- url
project-based theme-based = directory-based / parent-directory based (recursively) -->
<location src="{uri}" />
</act>
<act type="RecursiveDirectoryTraversalAction">
<parameter value="{../1}{1}" name="request"/>
<parameter value="{properties:dispatcher.theme}" name="projectFallback"/>
<parameter value="{properties:dispatcher.theme-ext}"
name="projectExtension"/>
<parameter value="{properties:content.xdocs}" name="projectDir"/>
<!-- xdocs [deprecated]
project-based theme-based = directory-based / parent-directory based (recursively) -->
<location src="{uri}" />
</act>
<!-- themes-dir: project-application-based theme-dir-based -->
<location
src="{lm:themer.project.dir}/{properties:dispatcher.theme}{properties:dispatcher.theme-ext}"
/>
<!-- themes-dir: project-application-based default -->
<location
src="{lm:themer.project.dir}/{properties:dispatcher.fallback.theme}{properties:dispatcher.fallback.theme-ext}"
/>
<!-- themer: forrest-application-based theme-based -->
<location
src="{lm:dispatcher.themer}/themes/{properties:dispatcher.theme}{properties:dispatcher.theme-ext}"
/>
<!-- themer: forrest-application-based default -->
<location
src="{lm:dispatcher.themer}/themes/{properties:dispatcher.fallback.theme}{properties:dispatcher.fallback.theme-ext}"
/>
</select>
</match>
