tabs, and site.xml versus book.xml

["Robert P. J. Day" <rp...@mindspring.com>]

  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.

  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?

  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.

  is that the recommended way to do it?

rday

Re: tabs, and site.xml versus book.xml

[Antonio Gallardo <ag...@agsoftware.dnsalias.com>]

Jeff Turner dijo:

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

Hi:

I already done <site tab="home"> with no results:

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

I always get all the site menu in the home tab.

I also uncommented project.menu-scheme=tab_attributes in
forrest.properties file.

I am using project.skin=krysalis-site

What I am doing wrong?

Best Regards,

Antonio Gallardo

Re: tabs, and site.xml versus book.xml

[Jeff Turner <je...@apache.org>]

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
>