Ferdinand Soethe wrote:
In preparing for the 0.8-release I'd like to try and refine the
documentation on location maps. Here are a couple of questions that
came to my mind while working through
http://forrest.apache.org/docs_0_80/locationmap.html:
1. Architecture
a) In which way do locationmaps work?
Is it
- a transformation or
- java code that calculates the final url or
Java code:
http://svn.apache.org/viewcvs.cgi/forrest/trunk/main/java/org/apache/forrest/locationmap/
b) Where does this processing take place?
- Everywhere linkrewriter is called?
Yes, whenever the psuedo prototocl of "lm:" is used.
c) What are the standard processing steps for
- a normal url
If no variables present, i.e. src="/foo/bar.html"/> Used by the
generator or reader to directly retrieve the document from the indicated
locaton (relative to the sitemap).
If a variable is present, ie. src="{project.xdocs}/foob/bar". The
variable is substituted by a Cocoon InputModule and the sorce is
retrieved from the resulting location.
- a url in site.xml
The URL is retrieved by the Cocoon crawler and processed as in a) above
- a site:-url
- an ext:-url
These are processed by an Input Module (just like the locationmap one).
The pseudo protocol is used to find the real URL of the "site:" url and
then it is processed as in a) above.
2. Docs state that
> 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.
This is a great feature!
This is not the case any more. We did it like this in the original
enabvlement of the LM as it gave a guarentee existing sites would not
break. However, the locationmap is always consulted now. This enables
users to override the default behaviour.
Default behaviour is still to look in the default location first, but
this may be changed by a project.
a) Is it correct to say that lms are evaluated whenever a normal
URL such as "/blabla.html" cannot be resolved? Even when the
URL does not begin with lm:?
No - LMs are only involved if the psudeo protocol is present.
b) How do sitemap cascades (such as looking up an image file in
different places) coexist with locationmaps? Will lm only be
evaluated when _all_ other matchers have failed?
All resolving of resources is now done the the locationmap. If you take
a look at resources.xmap you will see that there are no longer
alternative locations, only alternative source file formats (i.e. jpg.
svg, gif etc.). Now take a look at the locationmaop-resource.xml file
and you'll see that all the alternative locations are moved to there.
c) Is it correct to assume that using the lm:-prefix on a URL will
skip the step of looking for the standard file location?
Or else what would the standard location on named files be?
See a) above. In summary, it is correct to assume this if the user has
not overridden the locationmap entry for that resource type.
d) So if I wanted to implement tab-specific logos in our skin
- I just point to a file like logo.gif in the tabs base directory
- and create a locationmap with a pattern that would resolve all
those references to a central (main) logo
and, as a result, would see the local local if there is such a
file or the main logo if there was none?
Again, see a) and c) - same answer again.
Note, you would not need to create a locationmap entry unless you wanted
to put the images in a non-standard location. just ensure you use the
naming convention, i.e. "lm:project.images.myTabImage"
3. When it says
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 offsite address
at domain.org
Is it correct to say that the user will see an address of
mysite/rewrite/blablub.hmtl while the content was retrieved from
http://www.domain.org/blablub.xml?
No, this is a rewrite. The user will see the new URL. This is similar
functionality to ext: and site: In fact it is a duplicateion of ext: and
a much more efficient way of managing such things (in my opinion) since
it means you can have rewrites in content objects that do not have a
site.xml schema that can define rewrite rules (like Daisy or IMS
manifests for example).
The behaviour you describe (user sees one URL but content comes from
another) is the effect seen in the the "other" way of using the LM.
Ross
