# Locationmaps

# About Locationmaps

A locationmap defines a mapping from requests to location strings.

It was conceived to:

- Provide a more powerful means for semantic linking.
- Enable Forrest with a standard configuration override mechanism.
- decouple the conceptual source space used by Cocoon from the concrete source space, so that a change in the concrete sources does not impact on the sitemap

The syntax of a locationmap resembles that of the sitemap in that it also makes use of Matchers and Selectors to traverse a tree of nodes towards a leaf. In the case of the locationmap however the leaf does not identify a pipeline but instead identifies a location string.

# Locationmap Examples

## Retrieving an XDoc via HTTP

Normally files are generated from `{properties:content.xdocs}`. Using the Locationmap it is possible to make these files come from elsewhere. This is useful if you want to pull files from different directory structures, oe even remote repositories.

The target of "/remote.**.html" is generated from a source retrieved from the Forrest SVN.

Because the above URL retrieves the source file from SVN it will only work if you are online. For this reason we have not enabled this link as it would stop you building this site offline. However, if you are online you can enter the URL into the browser and it will work (however, note the issue described below, regarding the site: and ext: protocols).

Go to `http://localhost:8888/remote.index.html` which will virtually re-load this page. However, rather than use the local xml source, the locationamp has retrieved the up-to-date source directly from the svn server. Similarly `http://localhost:8888/remote.samples/index.html`

The match in src/documentation/content/locationmap.xml for this demo is ...

     <match pattern="project.remote.**.xml">
       <location src="http://svn.apache.org/repos/asf/forrest/trunk/main/fresh-site/src/documentation/content/xdocs/{1}.xml" />
     </match>

Since we are using the locationmap naming convention, our new match get resolved via the core forrest.xmap and we do not have to change any other files.

    <map:match pattern="**.xml">
      <map:generate src="{lm:project.{0}}"/>
      <map:serialize type="xml"/>
    </map:match>

Note that because this is a wildcard matcher you can request any page from SVN simply by requesting `/remote.PATH/TO/FILE/FILENAME.html`. In addition, we can request any other output format available via Forrest plugins.

When including resources from remote repositories one has to be careful about things like `site:` and `ext:` linking. If the targets are not defined in the local `site.xml` file then these links will be broken, which is the normal situation.

## Link Rewriting

The locationmap can be used to rewrite URLs when the page is generated. For example, when the locationmap has:

     <match pattern="project.rewrite.**">
       <location src="http://cocoon.apache.org/{1}.html" />
     </match>

This link is rewritten to an offsite address not specified in the link, which has `href="lm:rewrite.index"`.