Apache Forrest
spacer

Dispatcher quickstart

Intended Audience

People who are helping to develop the Dispatcher.

Warning
The "Dispatcher" (previously known as "Views") is new functionality which is still in development phase. That is why it is in the "whiteboard" section of Forrest. This document will also need to change to keep pace. We are working at the moment on moving this plugin from the whiteboard into the core plugins. See Status of Themes: Skins and Dispatcher.

Purpose

This document will get you started. We will Dispatcher-enable an existing site and show how to add/remove ready-made contacts. Then we will discuss how add your own new contracts.

This document encourages developers to get involved with fine-tuning and testing the dispatcher. Please help to enhance the current core contracts so that people do not need to re-invent the wheel.

Prerequisites

  • Using Forrest trunk of SVN (i.e. head of development).
  • Followed the installation instructions below.
  • You have an existing forrest site and want to try the new Dispatcher. Otherwise create a 'forrest seed-sample' site.

Steps

Note
When developing with the dispatcher we assume you are using 'forrest run' and the following workflow "change files -> refresh browser".
Installing a mozilla browser and the Forrestbar helps a lot with developing, but is not necessary.

Get ready

  • Do 'svn update' on forrest/trunk
  • Do the 'cd main; build clean; build' (necessary because the Dispatcher is changing rapidly and uses some Java)

Dispatcher-enable the existing site

  • Add the new plugins to forrest.properties ... ,org.apache.forrest.plugin.internal.dispatcher,org.apache.forrest.themes.core,org.apache.forrest.plugin.output.inputModule
  • localhost:8888/index.html ... fantastic. See the pelt view.

Use another theme

  • Add <property name="dispatcher.theme" value="common"/> to your forrest.properties.xml
  • Re-start 'forrest run'
  • localhost:8888/index.html ... See the new view.

Create our own structurer by copy-and-customise

Copy the default structurer for the pelt theme and make local changes.

Note
At this stage of rapid development of the Dispatcher, be sure to keep your copy synchronised. Use 'diff' against the known svn version of the core pelt.fv to track your local changes. Also please consider contributing new contracts and changes to the default structurers to the Forrest projects. That eases your local version management and everyone will benefit.
Note
We use ${themer.project.dir} for PROJECT_HOME/src/documentation/resources/themes (create the new directory folder first). You can change this location by adding <match pattern="themer.project.dir"> <location src="{properties:resources}/themes" /> </match> to your locationmap and point to another directory.
  • Copy THEMER_PLUGIN/themes/pelt.fv into your project at ${themer.project.dir}/pelt.fv
  • Copy THEMER_PLUGIN/themes/pelt/panels/pelt-html.panel.xml into your project at ${themer.project.dir}/pelt/panels/pelt-html.panel.xml
  • Re-start 'forrest run'
  • localhost:8888/index.html ... See the same view, now structured by us.

From here on there is no need to re-start 'forrest run'. Just edit the structurer and see the effect.

Remove a default contract

  • Remove the top breadcrumb trail. Edit your pelt-html.panel.xml and find the "branding-breadcrumbs" contract and comment it out.

Add a default contract

Forrest provides many default contracts. If you are using the Forrestbar then choose "Devs => ls.contracts". Otherwise visit localhost:8888/ls.contracts.html

  • See the usage detail for your chosen contract via the above mentioned list. e.g. "siteinfo-current-time"
  • Insert it at the appropriate point in your structurer. Note that it will need to go inside the appropriate CSS hook, e.g. 
      ...
  <forrest:hook name="footer">
    <forrest:contract name="siteinfo-current-time"/>
    ...

Notice that you did not need to copy any other code to your project space. Forrest finds the default contract in its core (the themes.core plugin).

You will find some commonly used contracts in place but commented out in both the common and the pelt structurer files. Feel free to uncomment them to activate them, move them around into other hooks or create new hooks for them.

Note
Work is currently under way for implementing Panels (was tiles). Currently we now have a 'panels' sub-dir for each 'theme'. This panels sub-dir currently contains a main html panel '%themename%-html.panel.xml' and a CSS panel '%themename%-css.panel.xml'. So you can change a collection of HTML and CSS outputs from these two XML files.

Add a new project contract

Warning
Carefully consider the purpose of your contracts. If they are useful in a wider context, then they belong in plugins or the core of Forrest. See below for further discussion on this important topic.

Project-based contracts are defined in theme-specific and output-format-specific directory structure, e.g. ${themer.project.dir}/THEME_NAME/OUTPUT_FORMAT/

Project-based contracts common to all themes go in ${themer.project.dir}/common/OUTPUT_FORMAT/

To get started quickly (it is not a project-based contract but a demo), copy one of the default contracts. e.g. copy siteinfo-current-time.ft to become siteinfo-doodad.ft ...

  • Copy THEMER_PLUGIN/themes/common/html/siteinfo-current-time.ft into your project at ${themer.project.dir}/common/html/siteinfo-doodad.ft (create the new directory folders first).
  • Edit it to suit. Replace all occurrences of "siteinfo-current-time" with "siteinfo-doodad" and make your other changes (e.g. the text and the javascript function).
  • Declare your new contract in your structurer as done above for adding a default contract.

See a list of your project-based contracts and their usage notes via Forrestbar "Devs => ls.contracts.project". Otherwise visit localhost:8888/ls.contracts.project.html

Decide how to manage your contracts

Fixme (open)
Glean content from Ross' discussion: Re: Dispatcher quickstart.

Further Reading

Congratulations you are now able to work with the Dispatcher. From here we recommend to read the following How-Tos:

Feedback

Please provide feedback about this document via the mailing lists.