forrest-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ferdinand Soethe <>
Subject Re: Inconsistent tab/menu behavior
Date Fri, 17 Feb 2006 09:00:32 GMT
[sorry, I was just gonna write a short answer and then I got carried
away ...]

Collapsed menus showing all of the menu items usually indicates an
error in site or tabs.xml.

1 Quite often a mismatch of directory names
  that need to be exactly identical across both files.

  [checking ...] Don't see any of that.

2 A missing reference (in site) to the indexfile mentioned in tabs.

  [checking ...] See that problem in <docs ...

        > <Docs label="Documentation" href="Docs/" tab="Docs">
        >    <Installation label="Installation" href="Installation/">


     Site.xml _has_ to have a visible reference to the file mentioned in tabs
     because Forrest calculates the state of the menu (embedded in each
     file) from the position of that reference in site.xml (more on
     that below).

     In other words: if Forrest finds an element referencing index.html
     within your docs-element, it will build the menu of the file to show
     an open docs-menu.

     And because it is within the doc-element (which is associated
     with the Documentation tab by its tab-attribute), it will limit
     the visible menus to those that are also associated with that

     So when you click on that tab, effectively opening index.html
     in you browser, you will see the correct menu in an open state.

     If however the file referenced by the tab (and thus opened when
     clicking the tab) is not also referenced in site.xml, Forrest will
     not know where to place it in the menu and which menus to show with
     it, so Forrest will simply show you all menus in an unopened

     As a general rule: _All_ files within your Forrest need to have a
     reference in site.xml (even if you want to open them via a link
     within another page) or else you will loose menu-context when the
     user navigates to that page (expressed in seeing the full Forrest
     menu in a collapsed state).

3 A file element in site.xml that has a pathname in href.

  Haven't checked that ...


  The menu for a file referenced in site.xml is calculated in the
  following steps better digestible in a short explample:

  Let's look at your file located in


  and referenced in site.xml by

        <Overview label="Overview" href="install-overview.html"/>

  Steps to build the menu when skinning that file:

      a) For each file reference in site
         build a virtual path name from the href of the site element
         prepended with all the hrefs of it's parent-menus

         so for

                <Overview label="Overview" href="install-overview.html"/>

         this means


        prepended with the hrefs from it's parents

        <Docs label="Documentation" href="Docs/" tab="Docs">
                <Installation label="Installation" href="Installation/">


     b) calculate the physical path name of the file
        relative to the Forrest xdocs directory


     c) compare physical path name to the list of virtual pathnames
        calculated above. If there is a match, build a menu for that
        file reflecting its position in site.xml.

  The menu system is unable to properly place a file-reference on a
  certain menu if the href of that file reference contains a path name.

  So (to my knowledge) _all_ files referenced within a menu element in
  site.xml have to be in the same directory or also you will loose
  context when opening that file in a different directory.

Hope that helps,

View raw message