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 11:38:35 GMT
> From: Jeff Turner [mailto:jefft@apache.org] 
> On Fri, Sep 13, 2002 at 01:35:36PM +0400, Piroumian Konstantin wrote:
> > > From: Jeff Turner [mailto:jefft@apache.org] 
> ...
> > > 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.

Ok. I got the idea and it sounds good. So any project deciding to use
Forrest can simply put all the project-specific files inside of a folder
(e.g. 'documentation'), point Forrest to that folder and get all processed,
right? This is what Forrest was missing long time.
 ...

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

Ah, sorry for being lazy, I could have seen it in your patch.

> 
> 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>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>
> 
> That's right. See src/resources/conf/skinconf.xml, which contains the
> Forrest defaults.

Ok.

> 
> ...
> > >   <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?
> 
> Yes it would be nice. However the 'processor' is the 
> <xmlproperty> task,
> and unfortunately it provides no way for accessing the n'th link.

The good thing is that Nicola is the author of the xmlproperty task. Nicola,
is it possible to specify some XPath expression for the task?

> 
> ...
> > > 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
> follows:
> 
> <map:transform src="skins/@skin@/xslt/html/{type}.xsl">
>   ...
>   <map:parameter name="config-file" value="../../../../skinconf.xml"/>
> 
> So it is quite flexible.

This snippet reminded me about another thing that can be fixed using input
modules and global parameters of Cocoon. I'll have a look at it next week.
How would you like the above rewritten like this:

 <map:global-parameter name="config-file" value="../../../../skinconf.xml"/>

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

Find differences ;)
The 'skin' input module can read the skinconf.xml at the initialization and
provide all the data for use in sitemap.

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

Yes, you are right. 

Btw, is it now really needed? We can get all the needed data from the
skinconf.xml and generate the needed 'breadcrumbs'. Are there any problems
with it?

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

Cool!

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

Usually, they don't like this kind of entertainment, otherwise they become
developers

> 
> ;) Yes of course.

;)

Konstantin

> 
> 
> --Jeff
> 
> > --
> >   Konstantin
> > 
> 

Mime
View raw message