Added: forrest/site/docs_0_100/linking.html URL: http://svn.apache.org/viewvc/forrest/site/docs_0_100/linking.html?rev=1068306&view=auto ============================================================================== --- forrest/site/docs_0_100/linking.html (added) +++ forrest/site/docs_0_100/linking.html Tue Feb 8 09:44:46 2011 @@ -0,0 +1,1128 @@ + + + + + + + +Menus and Linking (v0.10-dev) + + + + + + + + + +
+ +
+Apache Software Foundation > Apache Forrest +
+ +
+ + + + + + + + + + + + +
+
+
+
+ + + + +
+ +
+ +   +
+ + + + + +
+
Font size: +   +   +   +
+

Menus and Linking

+ + + +

Introduction

+
+

+ This document describes Forrest's internal URI space; how it is managed + with the "site.xml" configuration file, how menus are generated, and how + various link schemes (site: and ext:) operate. An overview of the + implementation is also provided. +

+

+ While reading this document, bear in mind that the Cocoon + Sitemap is handling the processing. + The sitemaps are resolving the site: URIs and then matching them to + determine how to process each. In general, you can use the power of the + Cocoon Sitemap to handle certain difficult linking and menu situations + (for example see this FAQ). +

+
+ + +

site.xml

+
+

+ The "site.xml" configuration file is what we would call a "site map" if + Cocoon hadn't already claimed that term. The "site.xml" is a loosely + structured XML file, acting as a map of the site's contents. It provides + a unique identifier (an XPath address) for "nodes" of information in the + website. A "node" of site information can be: +

+
    + +
  • A category of information, like "the user guide". A category may + correspond to a directory, but that is not required.
  • + +
  • A specific page, e.g. "the FAQ page"
  • + +
  • A specific section in a page, e.g. the "general" section of the FAQ + page (identified by id="general" attribute)
  • + +
+

+ In addition to providing fine-grained addressing of site info, the site.xml + allows metadata to be associated with each node, using + attributes or child elements. Most commonly, a label + attribute is used to provide a text description of the node. +

+

+ There are currently two applications of site.xml + +

+
+ +
+Menu generation +
+ +
+site.xml is used to generate the menus for the HTML website.
+ +
+Indirect linking +
+ +
+site.xml provides a basic aliasing mechanism for linking, e.g. one + can write <link href="site:changes"> from anywhere in the site, and + link to the "changes" information node (translated to changes.html). + More on this below.
+ +
+

+ Here is a sample site.xml ... +

+
+
+<?xml version="1.0"?>
+<site label="Forrest" href="" tab="home"
+  xmlns="http://apache.org/forrest/linkmap/1.0">
+
+  <about label="About">
+    <index label="Index" href="index.html"/>
+    <license label="License" href="license.html"/>
+    <your-project label="Using Forrest" href="your-project.html">
+      <new_content_type href="#adding_new_content_type"/>
+    </your-project>
+    <linking label="Linking" href="linking.html"/>
+    <changes label="Changes" href="changes.html"/>
+    <todo label="Todo" href="todo.html"/>
+    <live-sites label="Live sites" href="live-sites.html"/>
+  </about>
+
+  <community label="Community" href="community/" tab="community">
+    <index label="About" href="index.html"/>
+    <howto-samples label="How-To Samples" href="howto/" tab="howto">
+      <overview label="Overview" href="index.html"/>
+      <single-page label="Single Page" href="v10/howto-v10.html"/>
+      <multi-page label="Multi-Page" href="multi/">
+        <intro label="Intro" href="howto-multi.html"/>
+        <step1 label="Step 1" href="step1.html"/>
+        <step2 label="Step 2" href="step2.html"/>
+      </multi-page>
+    </howto-samples>
+  </community>
+
+  <references label="References">
+    <gump label="Apache Gump" href="http://gump.apache.org/"/>
+    <cocoon label="Apache Cocoon" href="http://cocoon.apache.org/"/>
+  </references>
+
+  <external-refs>
+    <mail-archive href="http://marc.theaimsgroup.com"/>
+    <xml.apache.org href="http://xml.apache.org/">
+      <commons href="commons/">
+        <resolver href="components/resolver/"/>
+      </commons>
+      <fop href="fop/"/>
+      <batik href="batik/"/>
+    </xml.apache.org>
+
+    <mail>
+      <semantic-linking href="http://marc.theaimsgroup.com/?l=forrest-dev
+        &amp;m=103097808318773&amp;w=2"/>
+    </mail>
+    <cool-uris href="www.w3.org/Provider/Style/URI.html"/>
+    <uri-rfc href="http://zvon.org/tmRFC/RFC2396/Output/index.html"/>
+
+  </external-refs>
+</site>
+        
+      
+

+ As you can see, things are quite free-form. The rules are as follows: +

+
    + +
  • The root element must be "site", and normal content should be in the + namespace http://apache.org/forrest/linkmap/1.0 (Feel + free to mix in your own content (RDF, dublin core, etc) under new + namespaces)
  • + +
  • Element names are used as identifiers. The "foo" in + "site:foo" must therefore be a valid NMTOKEN.
  • + +
  • Elements with href attributes can be used as identifiers + in "site:" URIs
  • + +
  • Relative href attribute contents are "accumulated" by prepending hrefs + from ancestor nodes
  • + +
  • Elements without label attributes (and their children) + are not displayed in the menu.
  • + +
  • Elements below external-refs are mapped to the + "ext:" scheme. So "ext:commons/resolver/" becomes + "http://xml.apache.org/commons/resolver/"
  • + +
+

+ See another explained example. + Also remember to look at the comprehensive example with Forrest's own + documentation. +

+
+ + +

Generating Menus

+
+

+ Two files are used to define a site's tabs and menu (site.xml and + tabs.xml). Both files are located in + src/documentation/content/xdocs/ + +

+

+ Assume that our tabs.xml looks like this: +

+
+
+<tabs ...>
+    <tab id="home" label="Home" dir=""/>
+    <tab id="community" label="Community" dir="community" indexfile="mailLists.html"/>
+    <tab id="howto" label="How-Tos" dir="community/howto"/>
+</tabs>
+      
+      
+

+ Using the "site.xml" listed above, we would get these menus: +

+

+ +Menu generated from site.xml +     + Community menu generated from site.xml +     + Howto menu generated from site.xml +

+

+ When using the "dir" attribute as above the value of the + "indexfile" parameter is appended to the value of the + "dir" attribute (together with a preceding '/'). For + example, the link for the community tab above is + community/mailLists.html. Note that + "indexfile" defaults to "index.html" if no + value is supplied. Therefore the link for the howto tab is + community/howto/index.html + +

+ +

Tabs for External Resources

+

+ A tab can refer to an external resource by using the + "href" attribute instead of the "dir" + attribute. The value of "href" should be the URI of the + resource you wish to link to. For example: +

+
+
+<tab id="apache" label="XML Apache" href="http://xml.apache.org/"/>
+        
+        
+

+ Unlike the "dir" attribute, the value of + "href" is left unmodified by Forrest unless it is + root-relative and obviously specifies a directory (ends in '/'). In + which case /index.html will be added. +

+ +

Selecting menu entries

+

+ Forrest decides which menu entries to display, by examining the + "tab" attributes in the site.xml file. The children of all site.xml + entries with a "tab" which is equal to that of the + current page, are added to the menu, whilst the element itself forms + the root of that part of the menu (see the "community" + element in the example below). Child elements that have a different + "tab" attribute value will appear in the menu for their + parents, and will also form the root of a new menu for a tab with the + appropriate name (see the "howto-samples" element below). +

+

+ Consider our site.xml example: +

+
+<site label="Forrest" href="" tab="home"
+  xmlns="http://apache.org/forrest/linkmap/1.0">
+
+  <about label="About">
+    <index label="Index" href="index.html"/>
+    <license label="License" href="license.html"/>
+    <your-project label="Using Forrest" href="your-project.html">
+      <new_content_type href="#adding_new_content_type"/>
+    </your-project>
+    <linking label="Linking" href="linking.html"/>
+    ....
+  </about>
+
+  <community label="Community" href="community/" tab="community">
+    <index label="About" href="index.html"/>
+    <howto-samples label="How-To Samples" href="howto/" tab="howto">
+      <overview label="Overview" href="index.html"/>
+      <single-page label="Single Page" href="v10/howto-v10.html"/>
+      <multi label="Multi-Page" href="multi/">
+        <intro label="Intro" href="howto-multi.html"/>
+        <step1 label="Step 1" href="step1.html"/>
+      ...
+

+ Every site.xml node can potentially have a "tab" attribute. If + unspecified, nodes inherit the "tab" of their parent. + Thus everything in the <about> section has an + implicit tab="home" attribute. +

+
+
Note
+
+ You can see this by viewing your site's + abs-menulinks pipeline in a + browser. +
+
+

+ Say that the user is viewing the linking.html page. The + <linking> node has an implicit tab value of + "home". Forrest will select all nodes with + tab="home" and put them in the menu. +

+ +

Alternative menu selection mechanisms.

+

+ The "tab" attribute-based scheme for selecting a menu's + entries is not the only one, although it is the most flexible. Here we + describe a few alternatives. +

+ +

Directory-based selection

+

+ In this scheme, each tab corresponds to a directory within the site. + All content below that directory is included in the menu. +

+

+ +Directory-based site menu +     + community/ directory menu +     + community/howto/ directory menu +

+

+ To use this scheme: +

+
    + +
  • Edit forrest.properties and set + project.menu-scheme=directories +
  • + +
  • Remove the "id" attributes from tabs.xml + entries.
  • + +
+ +

Specifying menus with book.xml

+

+ Historically, menus in Forrest have been generated from a + book.xml file, one per directory. This mechanism is + still available, and if a book.xml is found, it will be + used in preference to the menu generated by the site.xml file. The + book.xml files can use "site:" URIs to + ease the maintenance burden that led to obsolescence of book.xml + files. In general, however, we recommend that users avoid + book.xml files. +

+ +

Selecting the current tab

+

+ The tab selection algorithm is quite simple: the tab with the + "id" which matches that of the current site.xml node is + "selected". However the interaction of tabs.xml and site.xml while powerful, can + be complex to establish. +

+ +

Configuring the interaction between tabs.xml and site.xml

+

+ This is a collection of tips to assist with getting your menus and + tabs to properly display. +

+
    + +
  • + See the various notes above, not repeated in this list of tips. +
  • + +
  • + View your site's + abs-menulinks pipeline in a + browser. This is part of the internal Cocoon machinery, but like + other sitemap resources, it is useful to view them to assist with + debugging. +
  • + +
  • + The Forrest website also accompanies your software release + in the site-author directory, so + inspect its tabs.xml and site.xml to see how it is done. Also see the + 'forrest seed site' example. It is not as complex as the Forrest website. +
  • + +
  • + When you are fiddling with your attributes, change one thing at a time + and document what you have changed.
  • + +
  • + The value of the tab @id attribute cannot begin with a digit. + Likewise, element names in tabs.xml and site.xml cannot begin with a digit. +
  • + +
  • + Add label attributes to site.xml elements to make the menus show. + With nested elements in site.xml if the outer element does not have a label + attribute then the inner elements will not be displayed. +
  • + +
  • + To cause tabs and menu items to be highlighted, there need to be + corresponding elements in site.xml that have href attributes which match + the relevant path. + See + email explanation. +
  • + +
  • + When the tab points to a directory, then to make the tab highlighted + when selected, you need an element which matches index.html within the + group of elements that define the menus for this tab in the site.xml + file. That element can be without a label attribute, so that it doesn't + display as a menu item. However doing that causes that tab's menus + to be collapsed. +
  • + +
  • + Q: The tab link in my site assumes that 'index.html' + is present in the linked-to directory. How do I fix this? + A: In tabs.xml use @href instead of @dir attribute and omit the trailing '/'. + Which file to serve is then a concern of the sitemap. + See more at the FAQ. +
  • + +
+
+ + +

Table of Contents Generation

+
+

+ Each page can have an automatically generated table of contents. This is + created from the titles of each section in your xdoc. By default only + sections up to two levels deep are included and the table of contents is + displayed at the top of the page. However, you can configure this + behaviour in src/documentation/skinconf.xml using the + "toc" element. +

+
+
+<toc level="2" location="page"/>
+      
+      
+
    + +
  • +level - is the depth to which you + want your table of contents to go. Setting it to "3" will therefore + include sections nested to 3 levels. Setting this to "0" will result in + no table of contents being generated.
  • + +
  • +location - indicates where you + want the table of contents to be rendered. It can be set to one of + three values: +
      + +
    • +page - the table of contents will be rendered + at the top of the body of your page
    • + +
    • +menu - the table of contents will be rendered + in the menu to the left of the body of the page
    • + +
    • +menu, page - table of contents will be rendered + in both the page and the menu positions
    • + +
    +
  • + +
+
+ + +

Linking systems

+
+ +

Direct linking

+

+ In earlier versions of Forrest (and in similar systems), there has + been only one URI space: that of the generated site. If index.xml wants to + link to todo.xml then index.xml would use +

+
+          <a href="todo.html">to-do list<a>
+        
+

+ The theoretical problem with this is that the content producer should + not know or care how Forrest is going to render the source. A URI + should only identify a resource, not specify it's type + [mail ref] and + [cool URIs]. In fact, as Forrest + typically renders to multiple output formats (HTML and PDF), links in + one of them (here, the PDF) are likely to break. +

+ +

Indirect linking

+

+ Forrest's solution is simple: instead of <a href="todo.html">, + write <a href="site:todo"> where: +

+
+ +
site
+ +
is a URI "scheme"; a namespace that restricts + the syntax and semantics of the rest of the URI + [rfc2396]. The semantics of "site" are + "this identifier locates something in the site's XML sources".
+ +
todo
+ +
identifies the content in todo.xml by reference to a + "node" of content declared in site.xml +
+ +
+

+ We call this indirect, or semantic linking because instead of + linking to a physical representation (todo.html), we've linked to the + "idea" of "the todo file". It doesn't matter where it physically + lives; that will be sorted out by Forrest. +

+ +

Resolving site: URIs

+

+ So how does "site:todo" get resolved? A full answer is + provided in the implementation + section. Essentially, the "todo" part has + "/site//" prepended, and "/@href" + appended, to form the string "/site//todo/@href". This + is then used as an XPath expression in site.xml to identify the string + replacement, in this case "todo.html" +

+

+ Thus by modifying the XPath prefix and suffix, almost any XML format + can be accommodated. +

+
+
Note
+
+ Actually, the XPath is applied to XML generated dynamically from + site.xml. The generated XML has each "@href" fully expanded + ("absolutized") and dot-dots (..) added as needed ("relativized"). +
+
+

+ Notice that the "//" allows us any degree of specificity when + linking. In the sample site.xml above, both + "site:new_content_type" and + "site:about/your-project/new_content_type" identify the + same node. It is up to you to decide how specific to make links. One + nice benefit of link "ambiguity" is that site.xml can be reorganized + without breaking links. For example, "new_content_type" currently + identifies a node in "your-project". By leaving that fact + unspecified in "site:new_content_type" we are free to + make "new_content_type" its own XML file, or a node in another file, + in another category. +

+ +

ext: URIs: linking to external URLs

+

+ The "ext:" scheme was created partly to demonstrate the + ease with which new schemes can be defined, and partly for practical + use. The "ext:" URIs identify nodes in site.xml below the + <external-refs> node. By convention, nodes here link to URLs + outside the website, and are not listed in the menu generated from + the site.xml file. +

+

+ Here is a site.xml snippet illustrating "external-refs": +

+
+
+<site>
+  ...
+  <external-refs>
+    <mail-archive href="http://marc.theaimsgroup.com"/>
+    <xml.apache.org href="http://xml.apache.org/">
+      <commons href="commons/">
+        <resolver href="components/resolver/"/>
+      </commons>
+    </xml.apache.org>
+    ...
+  </external-refs>
+</site>
+          
+

+ As an example, <a href="ext:commons/resolver"> generates the + link + http://xml.apache.org/commons/components/resolver/ + +

+

+ The general rules of site.xml and "site:" linking apply. + Specifically, the "@href" aggregation makes defining large numbers + of related URLs easy. +

+ +

Theory: source URIs

+

+ The "site:" URIs like "site:todo" are + examples of "source" URIs, in contrast to the more usual + foo.html style URIs, which we here call + "destination" URIs. This introduces an important concept: + that the "source" URI space exists and is independent of + that of the generated site. Furthermore, URIs (i.e. links) are + first-class objects, on par with XML documents, in that just as XML + content is transformed, so are the links. Within the source URI + space, we can have all sorts of interesting schemes (person: mail: + google: java: etc). These will all be translated into plain old + "http:" or relative URIs in the destination URI space, + just like exotic XML source formats are translated into plain old + HTML in the output. +

+ +

Future schemes

+

+ So far, the "site:" and "ext:" schemes are + defined. To give you some ideas on other things we'd like to + implement (and wouldd welcome help to implement) here are a few + possibilities. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SchemeExample "From"Example "To"Description
javajava:org.apache.proj.Some../../apidocs/org/apache/proj/Some.html + + Links to documentation for a Java class (typically generated by + javadoc). +
mailmail::<Message-Id>http://marc.info?t=12345678 + + Links to an email, identified by its Message-Id + header. Any mail archive website could be used. +
searchsearch:<searchterm>http://www.google.com/search?q=searchterm + Link to set of results from a search engine
personperson:JT, person:JT/blog etcmailto:jefft <at> apache.org, + http://www.example.org/jefft/weblog/ + + A "person:" scheme could be used, say, to insert an + automatically obfuscated email address, or link to a URI in some + way associated with that person. +
+

+ There are even more possibilities in specific environments. In an + intranet, a "project:XYZ" scheme could identify company + project pages. In a project like Apache + Ant, each Task could be identified with + task:<taskname>, e.g. + task:pathconvert. +

+
+ + +

Concept

+
+

+ The "site:" scheme and associated ideas for site.xml were + originally described in the 'linkmap' RT + email to the forrest-dev list (RT means 'random thought'; a + Cocoon invention). Only section 2 has been implemented, and there is + still significant work required to implement the full system described. + In particular, there is much scope for automating the creation of site.xml + (section 4). However, what is currently implemented gains most of the + advantages of the system. +

+
+ + +

Implementation

+
+

+ Full details on the implementation of + link rewriting and + menu generation are + available in the Sitemap Reference + +

+
+ +
+ +
 
+
+ + + Propchange: forrest/site/docs_0_100/linking.html ------------------------------------------------------------------------------ svn:eol-style = native Added: forrest/site/docs_0_100/locationmap.html URL: http://svn.apache.org/viewvc/forrest/site/docs_0_100/locationmap.html?rev=1068306&view=auto ============================================================================== --- forrest/site/docs_0_100/locationmap.html (added) +++ forrest/site/docs_0_100/locationmap.html Tue Feb 8 09:44:46 2011 @@ -0,0 +1,887 @@ + + + + + + + +Locationmaps (v0.10-dev) + + + + + + + + + +
+ +
+Apache Software Foundation > Apache Forrest +
+ +
+ + + + + + + + + + + + +
+
+
+
+ + + + +
+ +
+ +   +
+ + + + + +
+
Font size: +   +   +   +
+

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.
  • + +
+

+ In other words, the locationmap enables content to be retrieved from a + location that is defined in a locationmap file (located at + PROJECT_HOME/src/documentation/content/locationmap.xml + file. The advantage of this is that the URL seen by the user need bear + no relation to the location of the source document, thus Forrest can + separate the client URL space from the source document URL space. Thus, + using the locationmap it is possible to pull together documents from + many different locations into a single uniform site. +

+

+ In addition, since the user URL space is now not connected to the source + URL space it is possible to move source documents without breaking any + existing user links. +

+

+ 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. +

+

+ Apache Forrest looks in the standard location for the source file first + (by default PROJECT_HOME/src/documentation/content/...), if + a file is found in this location then the locationmap is not consulted. + However, if one is not found then the locationmap is used to resolve the + source file. The locationmap is resolved via the core sitemap, this + means that you can generate it dynamically if you so wish. Simply add a + match that looks something like this to your projects sitemap: +

+
+
+   <map:match pattern="locationmap-project.xml">
+     <map:generate src="..."/>
+     <map:transform src="..."/>
+     <map:serialize type="xml"/>
+   </map:match>
+      
+      
+
+ + +

Naming Convention

+
+

+ For those that are familiar with name resolution servers or the Handles + Service, it might be easier to think of the locationmap as a name + resolution module or sort of a handle resolution module that it accepts + "names" or whatever you desire to call these "hints" and returns the + location. +

+

+ The thought is that by using hints that look a little like a file name + it disguises what locationmaps are really doing for us. By using + URN-style names, we are truly disassociating the name/hint from the + physical location. +

+

+ For example, here is a locationmap entry based purely on filename: +

+
+
+<map:transform src="{lm:html-to-document.xsl}"/>
+      
+      
+

+ and here is that same entry using a "name" style. One implies a certain + physical location, whereas the one below is truly a name that needs to + be resolved to a physical location. +

+
+
+<map:transform src="{lm:transform.html.document}"/>
+      
+      
+

+ Locationmaps are also used by plugins, and your project can also have + its own locationmap. +

+

+ Where the resource is provided by a plugin rather than Forrest itself, + this is prefixed with the last part of the plugin name. For example: +

+
+
+<map:transform src="{lm:projectInfo.transform.changes.document}"/>
+      
+      
+

+ The above match means look in the projectInfo plugin for a transformer + stylesheet with filename changes-to-document.xsl +

+

+ The naming convention is essentially one of: +

+
+[PLUGIN_NAME.]resource-type(dot)from-format(dot)to-format
+      
+

+ or +

+
+[PLUGIN_NAME.]resource-type(dot)type(dot)name
+      
+

+ Examples of these: +

+
+transform.xthml2.html
+graphic.png.project-logo
+projectInfo.transform.changes.rss
+      
+
+ + +

Explanation of Locationmap processing

+
+

+ Some specific examples will explain. Please follow the relevant source + files. +

+

+ The document Cocoon sitemaps + explained (better understand that document before trying to + understand locationmaps) has two specific transformers which use + locationmap references. The first one is: +<map:transform src="{lm:transform.linkmap.document}"/> + + +

+

+ The Locationmap component first consults the primary locationmap + $FORREST_HOME/main/webapp/locationmap.xml file. This first + mounts any project locationmap if available, then the locationmaps from + plugins, then the rest of the core locationmaps in the + $FORREST_HOME/main/webapp/ directory. As with sitemaps, the + first match wins. So matches in your project locationmap have + precedence, then plugins, then core. +

+

+ So let us get back to our specific example, + "lm:transform.linkmap.document". The "lm:" part means use + the locationmap protocol. There is no specific match for this in your + project locationmap, nor in any of the plugin locationmaps, so this + falls through to the core locationmaps. However, you will not find any + specific match for this in the core locationmaps, so what is happening? +

+

+ See the last match in + $FORREST_HOME/main/webapp/locationmap-transforms.xml file. + This a catchall matcher for any reference starting with + "transform." +

+
+
+    <match pattern="transform.*.*">
+      <select>
+        ...
+        ...
+        <location src="{forrest:forrest.stylesheets}/{1}-to-{2}.xsl"/>
+      </select>
+    </match>
+      
+

+ As you know from your understanding of Cocoon sitemaps, the first + asterisk yields "linkmap" and the second asterisk yields "document". So, + ignoring the other possible locations in this group which look in the + various skins stylesheet directories (see locationmap-transforms.xml + source), it will finally resolve to that last possible location to look + for a stylesheet called linkmap-to-document.xsl in the core + stylesheets directory + $FORREST_HOME/main/webapp/resources/stylesheets/ + +

+

+ That explains the magic of the locationmap naming convention. +

+
+ + +

Multiple Location Selectors

+
+

+ You can define multiple possible locations for a file in the locationmap + with the following code: +

+
+
+<match pattern="tabs.xml">
+  <select type="exists">      
+    <location src="{properties:content.xdocs}tabs1.xml"/>
+    <location src="{properties:content.xdocs}tabs2.xml"/>
+  </select>   
+</match>
+    
+      
+

+ Each location will be tested in turn, if the file exists then it will be + returned as a match, otherwise testing will continue. +

+
+ + +

Other 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, or even + remote repositories. For example, the following location match will + match any request for a document below "remote." and will retrieve the + source file from the Apache Forrest SVN repository (directly from the + ASF's SVN webserver). This is an ideal way to ensure that your + published docs are always up-to-date. +

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

+ Note that because this is a wildcard matcher you can request any page + from the svn server 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. +

+
+
Warning
+
+ Because of the above limitation many of the links in the page + generated from the above example are broken. +
+
+ +

Retrieving HTML from a CMS

+

+ Using the locationmap you can use Forrest to retrieve data from a + Content Management System (CMS), wither local or remote. As an example + we will consider Apache Lenya. +

+

+ +Apache Lenya is a Java + Open-Source Content Management System based on open standards such as + XML and XSLT and the Apache Software Stack, in particular the XML + publishing framework Apache Cocoon. +

+

+ The following locationmap matcher will instruct Forrest to retrieve + content from + http://lenya.zones.apache.org:8888/default/live/*.html?raw=true, + whenever a local URL of lenya/** is encountered. +

+
+ <match pattern="lenya/**.xml">
+   <location src="http://lenya.zones.apache.org:8888/default/live/{1}.html?raw=true" />
+ </match>
+        
+

+ However, since the source returned by this match is HTML and not XDoc + we must convert this to our internal XDoc format before we can use it. + We do this by adding the match below to our project's + sitemap.xmap file. +

+
+<map:match pattern="lenya/**.xml">
+  <map:generate type="html" src="{lm:{0}}" />
+  <map:transform src="{forrest:forrest.stylesheets}/html-to-document.xsl" />
+  <map:serialize type="xml"/>
+</map:match>
+        
+

+ Since this snippet uses the HTML generator you must also ensure that + your sitemap has the HTML generator component defined. That is, your + sitemap must also include: +

+
+<map:components>
+  <map:generators default="file">
+    <map:generator name="html"
+      src="org.apache.cocoon.generation.HTMLGenerator">
+      <jtidy-config>WEB-INF/jtidy.properties</jtidy-config>
+    </map:generator>
+  </map:generators>
+</map:components>
+        
+

+ Since the HTML generator uses JTidy we need to make available a JTidy + configuration file. This is placed in + PROJECT_HOME/src/documentation/WEB-INF/jtidy.properties + (the location can be changed in the above sitemap snippet). A sample + config file is given below: +

+
+indent=yes
+indent-spaces=8
+wrap=72
+markup=no
+output-xml=no
+input-xml=no
+show-warnings=yes
+numeric-entities=yes
+quote-marks=yes
+quote-nbsp=yes
+quote-ampersand=yes
+break-before-br=yes
+uppercase-tags=no
+uppercase-attributes=no
+char-encoding=latin1
+        
+
+
Note
+
+ This requirement to add items to your project sitemap will be removed + in a future version either by Lenya outputting XDoc, or by Forrest + switching to using XHTML as its internal format, or through the + development of a plugin for Lenya that will include the necessary + processing (whichever comes first). +
+
+
+
Warning
+
+ This demo is an example only, it does not fully work at this time. For + example, absolute URLs in the source document need to be rewritten to + ensure that they are matched by the locationmap. +
+
+ +

Enhanced PDF-output plugin

+

In order to change PDF rendered output, e.g. for your own skin + it is necessary to enhance/change the + plugin 'org.apache.forrest.plugin.output.pdf'. However, by default the plugin + takes its own locationmap pointing to the file 'document-to-fo.xsl' of the + plugin. +

+
+<match pattern="pdf.transform.*.*">
+  <select>
+    <location src="resources/stylesheets/{1}-to-{2}.xsl"/>
+    <location
+      src="{forrest:forrest.plugins}/org.apache.forrest.plugin.output.pdf/resources/stylesheets/{1}-to-{2}.xsl"/>
+  </select>
+</match>
+        
+

To override this choice you can add this to your locationmap: +

+
+<match pattern="pdf.transform.*.*">
+  <location src="{properties:skins-dir}/yourskin/xslt/fo/{1}-to-{2}.xsl"/>
+</match>
+        
+

Next, you can write your own 'document-to-fo.xsl' in the place specified above. + For example, you like to have a special paragraph that looks different to + default paragraphs by setting the font to 'oblique' and align it right: +

+
+<?xml version="1.0"?>
+
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+                xmlns:fo="http://www.w3.org/1999/XSL/Format"
+                version="1.0">
+
+<xsl:include href="lm://globalpdf.transform.document.fo" />
+
+ <xsl:template match="p[@class='special']">
+   <fo:block
+     font-size="10pt"
+     text-align="right"
+     font-style="oblique">
+     <xsl:apply-templates/>
+   </fo:block>
+ </xsl:template>
+
+</xsl:stylesheet>
+        
+

+ You may notice that this file contains only your definition and + a reference to "lm://globalpdf.transform.document.fo" which needs + to be resolved again in your locationmap with an entry that points to the + plugins 'document-to-fo.xsl'-file where all the other definitions are made: +

+
   
+<match pattern="globalpdf.transform.*.*">
+  <location 
+  src="{forrest:forrest.plugins}/org.apache.forrest.plugin.output.pdf/resources/stylesheets/{1}-to-{2}.xsl"/>
+</match>
+        
+ +

Source Resolving

+

+ As well as being able to use the locationmap as a parameter in the + sitemap, it is also possible to use it as a pseudo-protocol within + resources processed by Forrest. For example, you can use it to import + an XSL provided by one plugin within another plugin: +

+
+
+          <xsl:import src="lm://OOo.transform.write.xdoc"/>
+        
+        
+ +

Link Rewriting

+

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

+
+ <match pattern="rewriteDemo/**">
+   <location src="http://www.domain.org/{1}.xml" />
+ </match>
+        
+

+ With the above match in the locationmap, a link which has + href="lm:rewriteDemo/index" will be rewritten to an + off-site address at domain.org + +

+ +

Debugging Locationmaps

+

+ Debugging the locationmap can be difficult because Cocoons error + messages no longer provide meaningful data. We hope to improve this + over time, in the meantime we recommend that you increase the log + level of the locationmap logger. To do this edit the following line in + $FORREST_HOME/main/webapp/WEB-INF/logkit.conf: +

+
+<category name="modules.mapper.lm" log-level="INFO">
+        
+

+ For example, you could change the log level to "DEBUG". +

+

+ Output from this logger can be found in + $PROJECT_HOME/build/webapp/WEB-INF/logs/locationmap.log +

+

If you are interested in your local locationmap + (PROJECT_HOME/src/documentation/content/locationmap.xml) + the following lines at the top of the log-file indicate that the file + was read with success: +

+
+...
+DEBUG   (2009-02-26) 14:11.30:322   [core.modules.mapper.lm] (/): 
+         loading location map at cocoon://locationmap.xml
+...
+DEBUG   (2009-02-26) 14:11.30:385   [core.modules.mapper.lm] (/): 
+         loading mounted location map at cocoon://locationmap-project.xml
+...
+        
+

If you find any Java-Exception below these lines, you should deactivate + your changes and locate the wrong piece of code, otherwise your locationmap + will be ignored. +

+

In addition it is sometimes useful to increase the log level for the + sitemap too, since it may give hints on the locationmaps searched + in $FORREST_HOME and $PROJECT_HOME. Thus, changing the following line + in the same file from "ERROR" to "DEBUG" results in detailed output in + $PROJECT_HOME/build/webapp/WEB-INF/logs/sitemap.log: +

+
+<category name="sitemap" log-level="ERROR">
+        
+

+ You should not run production systems with this logger set higher than + "INFO" and "ERROR" as each request can generate large amounts of log information. +

+
+ +
+ +
 
+
+ + + Propchange: forrest/site/docs_0_100/locationmap.html ------------------------------------------------------------------------------ svn:eol-style = native Added: forrest/site/docs_0_100/menu-index.html URL: http://svn.apache.org/viewvc/forrest/site/docs_0_100/menu-index.html?rev=1068306&view=auto ============================================================================== --- forrest/site/docs_0_100/menu-index.html (added) +++ forrest/site/docs_0_100/menu-index.html Tue Feb 8 09:44:46 2011 @@ -0,0 +1,288 @@ + + Propchange: forrest/site/docs_0_100/menu-index.html ------------------------------------------------------------------------------ svn:eol-style = native