forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jeff Turner <>
Subject Re: [PATCH] customizable skins, greater configurability, image di r fixes, miscellanea
Date Fri, 13 Sep 2002 11:20:03 GMT
On Fri, Sep 13, 2002 at 01:35:36PM +0400, Piroumian Konstantin wrote:
> > From: Jeff Turner [] 
> > These changes were made while producing the site at
> >
> Seems that Forrest's skin is the favourite one. We already have at least 3
> sites with the same skin.

I like the Krysalis one (avalon-site) though. I think this patch would
allow the krysalis skin mods to be rolled back into avalon-site.

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

That's where it lives in Forrest's CVS module, where it is indeed a
"resource". But inside a live Forrest-using project, it's not a static
"resource", but the active controller. It specifies how resources
(images, xdocs) are mapped to URIs, so it's not a resource itself. Thus I
followed the Cocoon example of putting it at
src/documentation/sitemap.xmap. It's configurable of course.

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

Putting them in lib/ might interfere with other jars there, and might
cause unforseen interactions with either Cocoon or the user's app.
lib/optional and lib/endorsed are Centipede specific. How about lib/doc/?
Hmm.. if your project doesn't have a lib/ directory anyway, it would look
a bit silly. The intention with src/documentation/lib is that all doc
stuff (xdocs, stylesheets, images, jars) are in one directory.

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

It's "Search the <xsl:value-of select="$config/project-name"/> site"

skinconf.xml is intended to contain declarative, reusable information
about one's project, reusable in multiple locations, like here.

> >   <group-name>Apache XML</group-name>
> >   <group-url></group-url>
> >   <group-logo>images/group-logo.gif</group-logo>
> I wonder how can be the 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>

That's right. See src/resources/conf/skinconf.xml, which contains the
Forrest defaults.

> >   <trail>
> >     <link1 name="apache" href=""/>
> >     <link2 name="xml.apache" href=""/>
> >     <link3 name="" href=""/>
> <link4/><link5/>...<linkN/>?
> Maybe simply:
> 	<link ...>
> 	<link ...>
> and process them in the order of appearance?

Yes it would be nice. However the 'processor' is the <xmlproperty> task,
and unfortunately it provides no way for accessing the n'th link.

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

That's just a default, which assumes that skinconf.xml is alongside the
sitemap. If that's not true, then the sitemap could configure the stylesheet as

<map:transform src="skins/@skin@/xslt/html/{type}.xsl">
  <map:parameter name="config-file" value="../../../../skinconf.xml"/>

So it is quite flexible.

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

?? Yes, tokens are needed.. how else do you customize a .js file?

>  Can't we stick to a single configuration location?

Everything is configured from skinconf.xml. Stylesheets access it directly, and
everything else gets filters applied, where filters correspond directly to
skinconf.xml elements. There's no duplication of config info anywhere.
> > 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.

I don't know. Isn't it more fun when users have to figure stuff out themselves?
Brings some excitement to their dull pointless little lives..

;) Yes of course.


> --
>   Konstantin

View raw message