forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jeff Turner <je...@apache.org>
Subject Re: tabs, and site.xml versus book.xml
Date Tue, 08 Jul 2003 11:57:11 GMT
On Mon, Jul 07, 2003 at 08:29:44AM -0400, Robert P. J. Day wrote:
> 
>   prelim:  as i understand it (and as it appears to work), if i define
> a top-level site.xml file, that site file will define the navigation 
> menu for all selections i make, even if some of those selections
> take me into subdirectories.

Yes.

>   if i want to override the top-level site.xml file, i can add
> specifically a book.xml file to whichever directory i want, and
> that book.xml file will be used to define the menu for just that
> sub-directory.  can only a book.xml file be used for this?  is
> it possible to use lower-level site.xml files for this as well,
> for the sake of consistency?

Only book.xml can be used, currently.  It's more to keep
backwards-compatibility than intended to be a new feature.

Allowing site.xml's in subdirectories would be a nice addition, and
probably not too hard to code up, if you'd like to try it.  The relevant
file is menu.xmap.

> and, taking this a bit further, if i want to define multiple tabs
> for my site, normally, each tab would have an independent navigation
> menu.  i know i can implement this by having a top-level site.xml
> file for the first tab (say, "Home"), have subdirectories for each
> of the remaining tabs, and use a book.xml file to define each of
> *those* menus.

Oh.. okay, I think there might be a simpler solution.  There is a shiny
new tab system in CVS Forrest, much more flexible than the old
directory-based one, but it isn't yet documented.

Which tab system is in use is determined by the 'project.menu-scheme'
property in forrest.properties.  It has two possible values,
'tab_attributes' (the new system) and 'directories' (the
old system).  In anticipation of a 0.5 release, 'tab_attributes' is the
default.

The new system works by allowing you to specify exactly which pages in
site.xml belong to which tab, by giving each site.xml entry a 'tab'
attribute.  The new tab system requires two changes:

 - In tabs.xml, each <tab> entry now requires an 'id' attribute.  An
   example from JIRA (result online at
   http://www.atlassian.com/software/jira/docs/latest):

   <tab id="" label="JIRA" dir=""/>
   <tab id="install" label="Install" href="install.html"/>
   <tab id="config" label="Configure" href="configure.html"/>
   <tab id="user" label="Use" href="issues.html"/>
   <tab id="faq" label="FAQ" href="faq.html"/>

 - In site.xml, nodes that belong in a tab must be marked (or have a parent
marked) as such with a tab='<tabid>' attribute.  For instance:

<site label="JIRA" href="" xmlns="http://apache.org/forrest/linkmap/1.0">

  <about label="About">
    <index label="Index" href="index.html"/>
  </about>
  <install label="Installing JIRA" href="" tab="install">
    <requirements label="Requirements" href="requirements.html"/>
    <guide label="Install Guide" href="install.html"/>
     ....
  </install>
  <concepts label="Concepts" tab="user">
    <issues label="Issues" href="issues.html"/>
    ....
  </concepts>
  <configuring label="Configuration" href="" tab="config">
    <configuration label="Configuring JIRA" href="configure.html">
    ....
  </configuring>
  <ref label="Reference Guides" tab="user">
    <dashboard label="Configuring the Dashboard" href="dashboard.html"/>
    ....
  </ref>
  <misc label="Miscellaneous">
    <faq label="FAQ" href="faq.html" tab="faq"/>
    ...
  </misc>
</site>

  Some features to note about this site.xml:

    - The 'user' tab is used in two separate trees ('Concepts' and
      'Reference Guides'), meaning only those sections will appear in the
      "Use" tab.
    - The 'faq' tab has only one page (see the website for the effect of
      this).
    - (advanced) The '' tab is special, and matches all nodes.  The root
      <site> node contains no tab attribute.  It therefore defaults to
      '', and so the front page contains links to all pages.  Usually,
      you'd use <site tab="home">, and call the home tab 'home', in which
      case only a subset of the site's content would appear on the home
      tab.


Hmm, I might as well just have written the proper docs..

Hope it's enough to get you going.


--Jeff

>   is that the recommended way to do it?
> 
> rday
> 

Mime
View raw message