forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jeff Turner <je...@apache.org>
Subject [PATCH] customizable skins, greater configurability, image dir fixes, miscellanea
Date Fri, 13 Sep 2002 09:19:19 GMT
Hi,

First, apologies for such a big, monolithic patch doing so much. This patch is
a summary of three weeks of Forrest use, and though I did try to retroactively
separate the patches, it got very messy. Let me know if any bits are dubious
and I'll separate them out.

These changes were made while producing the site at
http://aft.sourceforge.net/

The patch does the following:

 - Allows users to have a custom sitemap, overriding the forrest-provided
   one. Default location is src/documentation/sitemap.xmap, though it is
   configurable.

 - Allows users to add jars to the webapp, by default from
   src/documentation/lib (configurable). This is useful for adding custom
   sitemap components, or testing hacked versions of Cocoon. 

 - By setting properties in forrest.properties, the user can specify
   where their project's doc files (sitemap, xdocs, images, skins,
   skinconf, lib) are located. This is so simple projects can have a
   simple doc structure:

   /xdocs/*.xml
   /xdocs/images/*.{png,gif,jpg}

 - Modifies the forrest-site skin to be configurable for non-Apache
   projects. Previously there were some xml.apache.org hardcodings. Also
   enhances configurability by:
    - providing a flag to disable the search box
    - providing a 'host' section in the bottom-left, for things like
      sourceforge logos
    - by providing a 'credits' section where multiple small images can
      link to 'credited' projects.
   The site whose functionality I was emulating is
   http://krysalis.org/centipede/. See below for implementation details.

 - Previously, each Forrest-generated page had page-relative links to
   'skins/images/*', and then a sitemap rule eliminated any directory
   prefix. This leads to multiple copies of images on the filesystem:

   http://www.outerthought.net/forrest/images/group-logo.gif
   http://www.outerthought.net/forrest/community/howto/images/group-logo.gif
   http://www.outerthought.net/forrest/xml-site/images/group-logo.gif

   and consequently Forrest pages in subdirectories needlessly require
   extra copies of images, and are slow to download.
   
   The patch fixes this by generating a '../' path to the site root, and
   then using the {context-root}/skins/images rule.

 - Changes the 'store' log level from DEBUG to INFO to prevent those
   annoying continual memory logs.


Phew!

The main change to comment on is the skin customizations. This is done with
what we've been calling a "siteplan" file: an XML file containing project
info. It is typically stored in src/documentation/skinconf.xml, and looks
like this:

<skinconfig>
  <disable-search>false</disable-search>

  <project-name>Forrest</project-name>
  <project-url>http://xml.apache.org/forrest/</project-url>
  <project-logo>images/project-logo.gif</project-logo>

  <group-name>Apache XML</group-name>
  <group-url>http://xml.apache.org/</group-url>
  <group-logo>images/group-logo.gif</group-logo>

  <!-- Eg, a sourceforge logo. forrest-site renders it to the bottom-left corner -->
  <host-logo></host-logo>

  <!-- The following used to construct a copyright statement -->
  <year>2002</year>
  <vendor>The Apache Software Foundation.</vendor>

  <!-- Some skins use this to form a 'breadcrumb trail' of links. If you don't
  want these, set the attributes to blank. The DTD purposefully requires them.
  -->
  <trail>
    <link1 name="apache" href="http://www.apache.org/"/>
    <link2 name="xml.apache" href="http://xml.apache.org/"/>
    <link3 name="" href=""/>
  </trail>

  <!-- Credits are typically rendered as a set of small clickable images in the
  page footer -->
  <credits>
    <credit>
      <name>Built with Cocoon</name>
      <url>http://xml.apache.org/cocoon/</url>
      <image>skin/images/built-with-cocoon.gif</image>
      <width>88</width>
      <height>31</height>
    </credit>
    <credit>
      <name>Krysalis Centipede</name>
      <url>http://www.krysalis.org/centipede/</url>
      <image>skin/images/centipede-logo-small.gif</image>
      <width>138</width>
      <height>31</height>
    </credit>
  </credits>
</skinconfig>


This file can be then read by the skin stylesheets:

<xsl:param name="config-file" select="'../../../../skinconf.xml'"/>
<xsl:variable name="config" select="document($config-file)/skinconfig"/>

And then used like:

<a href="{$config/project-url}"><img src="{$root}{$config/project-logo}" ...

ie, the stylesheet *actively* examines the config file, as opposed to *passive*
configuration, which is where @tokens@ are replaced by an Ant task.

Why introduce "active configuration"? Isn't passive, token-based configuration
enough? Not really; as an example, this is how we iterate through the multiple
credits listed in skinconf.xml:

<xsl:if test="$config/credits">
   <div align="right">
   <xsl:for-each select="$config/credits/credit">
     ...
   </xsl:for-each>
   </div>
</xsl:if>

Can't do that (iteration) with tokens.

However, we also do need tokens to "passively" configure other parts of a skin,
like CSS and Javascript pages. Eg, the breadcrumbs.js script is configured with
tokens like @link1.href@.

So the forrest.build.xml uses <xmlproperty> to load skinconf.xml, and set
filters corresponding to each node. So breadcrumbs.js now uses
@skinconfig.trail.link1.href@. To preserve backwards-compat with users' skins,
the old tokens would still work.



I've been working with build.build.xml and forrest.build.xml. The old build.xml
script still works, but the token filters no longer have any effect, as the
stylesheets use skinconf.xml. Hence if this patch is applied, I think
build.build.xml should be officially adopted as build.xml, and the old
build.xml be renamed build-old.xml or something. The new script has (I think)
all the functionality of the old one.


While I've tried hard to keep things backwards-compatible, and AFAIK everything
IS backwards-compatible, I've likely screwed up somewhere. Please let me know
and I'll fix.

Also, I have written no docs other than this email, pending the list's approval
of the general ideas in this patch.


--Jeff

Mime
View raw message