forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Piroumian Konstantin <KPiroum...@protek.com>
Subject RE: [PATCH] customizable skins, greater configurability, image di r fixes, miscellanea
Date Fri, 13 Sep 2002 09:35:36 GMT
> From: Jeff Turner [mailto:jefft@apache.org] 
> 
> 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.

Hopefully you'll be able to commit everything yourself ;)

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

Seems that Forrest's skin is the favourite one. We already have at least 3
sites with the same skin.

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

Why not the src/resources/conf?

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

Why not the /lib directory (or /lib/optional or /lib/endorsed)?

I don't like having JARs inside of the documentation folder. Custom jars can
be used not only for the documentation, but also for custom Ant tasks or
other java source that is placed in the src/java directory.

> 
>  - 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}

Fine!

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

Maybe the search box can be made more configurable? I've noticed that you
have a label 'Search AFT site' instead. Did you changed the stylesheet for
that?

>     - 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/gro
> up-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.

Yes this was a known issue. Thanks for fixing it.

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

Ooh! ;)

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

I wonder how can be the XML.apache.org site itself be configured. Am I
correct saying that it'll be like this:
 <project-name>Apache XML</project-name>
...
<group-name>Apache</group-name>
?

Not bad.

> 
>   <!-- 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=""/>

<link4/><link5/>...<linkN/>?

Maybe simply:
	<link ...>
	<link ...>
and process them in the order of appearance?

>   </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'"/>

Maybe something like a base-dir can be used instead of relative links? E.g.:
<xsl:param name="config-file" select="'{$base-dir}/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@.

Hm... Is it really needed? Can't we stick to a single configuration
location?

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

+1

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

No problems. Thanks for moving Forrest forward!

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

It's Ok. 
But as we settle the things, we will need some User's docs for all the
configurations and an entry in the changes.xml with a summary.

--
  Konstantin

> 
> 
> --Jeff
> 

Mime
View raw message