Forrest has many powerful techniques for linking between documents and for managing the site navigation. This document demonstrates those techniques. The document "Menus and Linking" has the full details.
When Forrest builds your site, it starts from the front page. Like a robot, it traverses all of the links that it finds in the documents and builds the corresponding pages. Any new links are further traversed.
Sometimes those links lead to documents that are generated directly from xml source files, sometimes they are generated from other source via an intermediate xml format. Other times the links lead to raw un-processed content.
The site navigation configuration file "site.xml" provides
a way to manage this URI space. In the future, when documents are
re-arranged and renamed, the site.xml configuration will enable this
smoothly.
For both generated and raw (un-processed) files, the top-level of the
URI space corresponds to the "content/xdocs/" directory,
i.e. the location of the "site.xml" configuration file.
content/" directory. In 0.7 onwards, raw
un-processed data is stored alongside the xdocs. In addition,
in 0.6 and earlier, HTML documents could be stored in the xdocs
directory and served without processing. If you
you wish to emulate the behaviour of 0.6 and earlier see the
next section.
A diagram will help.
By using Forrest Input Plugins
you can process some file formats, such as
OpenOffice.org documents and produce processed content from them. For example,
the file content/xdocs/hello.sxw can be used to produce a
skinned version of the document at with the name hello.html.
Similarly, you can use Forrest Output
Plugins to create different output formats such as PDF, in this
case content/xdocs/hello.sxw can produce
hello.pdf.
However, this does not affect the handling of raw content. That is, you
can still retrieve the raw un-processed version with, for example,
hello.sxw. If you want to prevent the user retrieving the
un-processed version you will have to create matchers that intercept
these requests within your project sitemap.
When this type of link is encountered, Forrest will look for a
corresponding xml file, relative to this document (i.e. in
content/xdocs/samples/).
A generated document in the current directory, which corresponds to
content/xdocs/samples/sample.html ...
In a sub-directory, which corresponds to
content/xdocs/samples/subdir/index.html ...
Raw content files are not intended for any processing, they are just
linked to (e.g. pre-prepared PDFs, zip archives).
These files are placed alongside your normal content in the
"content/xdocs" directory.
A raw document in the current directory, which corresponds to
content/xdocs/samples/helloAgain.pdf ...
A raw document in a sub-directory, which corresponds to
content/xdocs/samples/subdir/hello.zip ...
A raw document at the next level up, which corresponds to
content/hello.pdf ...
Prior to version 0.7, the raw un-processed content was stored in
the "content/" directory. In 0.7 onwards, raw
un-processed data is stored alongside the xdocs. In addition
in 0.6 and earlier, HTML files could be stored in the xdocs
directory and they would be served without further processing.
As described above, this is not the case in 0.7 where HTML files
are, by default, skinned by Forrest.
If you you wish to emulate the behaviour of 0.6 and earlier then you must add the following to your project sitemap.
The above allows us to create links to un-processed skinned files stored
in the {project:content} or {project:content.xdocs}
directory. For example:
<a href="/test1.html">HTML content</a>. However, it will
break the 0.7 behaviour of skinning HTML content. For this reason the old
".ehtml" extension can be used to embed HTML content in a Forrest skinned
site
Note that you can change the matchers above to selectively serve some content as raw un-processed content, whilst still serving other content as skinned documents. For example, the following snippet would allow you to serve the content of an old, deprecated site without processing from Forrest, whilst still allowing all other content to be processed by Forrest in the normal way:
For example, HTML content.
A full URL ...
A full URL with a fragment identifier ...
Note that Forrest does not traverse external links to look for other links.
As you will have discovered, using pathnames with ../../ etc. will get very nasty. Real problems occur when you use a smart text editor that tries to manage the links for you. For example, it will have trouble linking to the raw content files which are not yet in their final location.
Links and filenames are bound to change and re-arrange. It is essential to only change those links in one central place, not in every document.
The "site.xml" configuration file to the rescue. It maps
symbolic names to actual resources.
This single entry ...
enables a simple link to a generated document, which corresponds to
content/xdocs/index.xml ...
This compound entry ...
enables a link to a generated document, which corresponds to
content/xdocs/samples/index.xml ...
and a link to a generated document, which corresponds to
content/xdocs/samples/faq.xml ...
This compound entry ...
enables a link to a fragment identifier within the
samples/sample.html document ...
This entry ...
enables a link to a raw document, which corresponds to
content/hello.pdf ...
This compound entry ...
enables a link to an external URL ...
and a link to another external URL ...
and a link to another external URL with a fragment identifier ...