You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by Paul Bolger <pb...@gmail.com> on 2006/01/12 01:41:46 UTC

common.fv not working - have I missed something?

I've just done a SVN update, built Forrest, built the two dispatcher
plugins, Forrest seed-v2 a new instance. I then added an instance of
common.fv but Forrest ignores it. I'd think that there was a setting
in forrest.properties which I've missed (it's changed quite a bit
since I last did this) but renaming common.fv to index.fv results in
the view working fine on the single target file. Any ideas anyone?

paul b

Re: common.fv not working - have I missed something?

Posted by Thorsten Scherler <th...@apache.org>.
El lun, 16-01-2006 a las 17:51 +1300, Paul Bolger escribió:
> Hi Thorsten, I've been trying to digest your replies before answering.
> Not easy when I understand about 20% of it...

Ok, please keep on asking questions to bring you closer to 100%. ;-) If
I can get you to this all other future user/devs can profit from it. We
should start to document this issue.

> >
> > The only difference is that you are linking to more/other css files in
> > the {customTheme}.fv. ...and like always in the dispatcher we have
> > fallbacks implemented.
> 
> Yeah, I'm beginning to understand that, It'd be good to have the
> fallback sequences detailed in the howtos.

Yes, I agree.

>  I might have a go, but
> unlikely to have time till next week.
> 

That would be awesome. Do you see a chance to reuse parts of my other
mail "How do the structurer and themes work?" as well, would be awesome?

> 
> >
> > No, with the locationmap you can override everything what I wrote above
> > and in the other mail about fallbacks in the dispatcher. That means if
> > you use your custom locationmap you override the core.
> >
> > > Right at the moment I'm finding the whole theme setting/defining
> > > procedure quite confusing.
> >
> > Hmm, ....
> 
> And I think a large part of that is confusion over terms. 

Yeah, I just removed the old views stuff. Maybe that will help as well.

> Maybe I'll
> knock up a rough Dispatcher definitions document.

Yeah, that is something we really need.

>  It's finally
> clicking that the .fv files are 'structurer' files (I thought
> fv=Forrest View= view files). 

yes, that is from historic reason since the structurer was also known as
forrest:view.

> I'm thinking that running an evolving
> list of definitions may be helpful to rename some Dispatcher terms at
> a later date, when their functions have stopped developing. 

We are always open for suggestions.

> I've had a
> look at some of the Cocoon docs and I realise that some of the
> terminology came from there.
> 

Which one?


> 
> > > Wouldn't it make sense to set the project
> > > theme in forrest.properties,
> >
> > Yeah that is how it is done.
> 
> The 'missing link', however, is that a theme *must* have an .fv file
> in the themes directory or the theme fallback mechanism won't work. I
> can understand that this makes sense as there may be project files
> which aren't in the xdocs file system, but I think it would make more
> sense for the master .fv file to be in the theme directory itself.

Hmm, I lost you here. They are in the theme directory.

> Then one could copy and move the whole directory into another project
> and never have to worry about it unless one specifically needed to
> change it.
> 

yeah.

salu2
-- 
thorsten

"Together we stand, divided we fall!" 
Hey you (Pink Floyd)

Re: common.fv not working - have I missed something?

Posted by Paul Bolger <pb...@gmail.com>.
Hi Thorsten, I've been trying to digest your replies before answering.
Not easy when I understand about 20% of it...
>
> The only difference is that you are linking to more/other css files in
> the {customTheme}.fv. ...and like always in the dispatcher we have
> fallbacks implemented.

Yeah, I'm beginning to understand that, It'd be good to have the
fallback sequences detailed in the howtos. I might have a go, but
unlikely to have time till next week.


>
> No, with the locationmap you can override everything what I wrote above
> and in the other mail about fallbacks in the dispatcher. That means if
> you use your custom locationmap you override the core.
>
> > Right at the moment I'm finding the whole theme setting/defining
> > procedure quite confusing.
>
> Hmm, ....

And I think a large part of that is confusion over terms. Maybe I'll
knock up a rough Dispatcher definitions document. It's finally
clicking that the .fv files are 'structurer' files (I thought
fv=Forrest View= view files). I'm thinking that running an evolving
list of definitions may be helpful to rename some Dispatcher terms at
a later date, when their functions have stopped developing. I've had a
look at some of the Cocoon docs and I realise that some of the
terminology came from there.


> > Wouldn't it make sense to set the project
> > theme in forrest.properties,
>
> Yeah that is how it is done.

The 'missing link', however, is that a theme *must* have an .fv file
in the themes directory or the theme fallback mechanism won't work. I
can understand that this makes sense as there may be project files
which aren't in the xdocs file system, but I think it would make more
sense for the master .fv file to be in the theme directory itself.
Then one could copy and move the whole directory into another project
and never have to worry about it unless one specifically needed to
change it.


> if a pult.fv file exists in the project local themes directory.

Hmm, you mean you have to have a default structurer for the theme in the
theme dir?

It certainly seems that way.


> doesn't matter if that file has any content. It also seems this also
> sets the project css default directory to the pult theme directory
> (I'm really starting to regret not giving this theme a sensible name!)

Yes, see the other mail, but you can still use and place them in your
local common directory since it gets matched by the lm. Generally we
assume that a theme will only override parts of the common stuff, but
keeping the resources in the {customTheme} resource dir makes them
unique usable for this theme (if {customTheme} != common).

> Does this mean I've found a real, live, bug?

That part about only if it exist in the theme dir sounds like one, but
as more I think about it, it seems to be a feature. ;-) I mean a theme
*has to* provide a default structurer {themeName}.fv in the theme dir
otherwise it cannot be used out of the box.

See above, it'd be less likely to cause problems if it was in the
custom theme directory itself.

>  It'd be good to adjust
> the documentation to reflect what's going on, but I'm loathe to spend
> much time on it if it's about to be swept away by v3.

v3 has changed the internal processing for delivering e.g. html and some
grammar but the concepts are the same.

Ok, when I'm happy that it's doing what I think it's doing I'll do a patch.

Re: common.fv not working - have I missed something?

Posted by Thorsten Scherler <th...@apache.org>.
El vie, 13-01-2006 a las 12:06 +1300, Paul Bolger escribió:
> > > <forrest:css url="styles.css" media="screen" theme="pult"/>
> >
> > Actually that is only interesting for the theme switcher and optional.
> 
> The dispatcher docs  (howto-structurer-dsl) says
> 
> (attribute:theme) 3. the theme, "pelt" is the default theme (another
> is the "common" theme). Change this if you are using your own theme.
> 
> Which to me means 'if you want to use css from a theme other than the
> default set that here'.

¿? Css actually is just a special contract format. Like always for
common you can reuse the css contract not only in common but as well in
a custom theme.

The only difference is that you are linking to more/other css files in
the {customTheme}.fv. ...and like always in the dispatcher we have
fallbacks implemented.

forrest-trunk/whiteboard/plugins/org.apache.forrest.plugin.output.themer
$ cat locationmap.xml
...
<!-- generic match for theme ressources like css and js. -->
    <!-- 
      {1} name
      {2} extension (note we assume e.g. PATH/css/{1}.css)
      -->
    <match pattern="themes/**.*">
      <select type="exists">
        <location
src="{lm:themer.project.dir}/{project:theme}/{2}/{1}.{2}" />
        <location
src="{lm:themer.project.dir}/{defaults:theme}/{2}/{1}.{2}" />
        <location
src="{project:themer}/resources/themes/{project:theme}/{2}/{1}.{2}" />
        <location
src="{project:themer}/resources/themes/{defaults:theme}/{2}/{1}.{2}" />
        <location
src="{defaults:themer}/resources/themes/{project:theme}/{2}/{1}.{2}" />
        <location
src="{defaults:themer}/resources/themes/{defaults:theme}/{2}/{1}.{2}" />
      </select>
    </match>
...

> In a recent post you wrote about using multiple themes. I didn't
> really understand how this could be done. Could you clarify please.
> 

¿? Multiple views can you post what I wrote. You can use one theme at a
time. You can switch themes with the branding-theme-switcher.ft on the
fly, but you cannot use multiple views otherwise.

> > > but Forrest ignoring them and just looking in the common/css directory.
> >
> > hmm, have you modified your locationmap?
> 
> No I haven't. Wouldn't redirecting using locationmap be a sort of
> 'bulldozer' solution?

No, with the locationmap you can override everything what I wrote above
and in the other mail about fallbacks in the dispatcher. That means if
you use your custom locationmap you override the core.

> Right at the moment I'm finding the whole theme setting/defining
> procedure quite confusing.  

Hmm, ....

> Wouldn't it make sense to set the project
> theme in forrest.properties, 

Yeah that is how it is done.

> and then have all views, css locations
> etc cascade from that unless specifically overridden? 

see my other mail and this since we have based the dispatcher 100% on
the locationmap you are free to override core behavior very easy.

> This would mean
> you could make a copy of a theme, put it in your project themes/
> directory, set the theme in forrest.properties, and then - barring
> putting an .fv file in your xdocs/ directory - do all theme fiddling
> within the theme copy.

That is exactly how it is working. Remember I wrote:
> > If you do and want a fallback for pult you can
> > a) add it to {yourProject}/.../themes/pult.fv
> > b) add it to {yourProject}/.../xdocs/pult.fv

Now a) is the place where you normally would add it.

salu2
-- 
thorsten

"Together we stand, divided we fall!" 
Hey you (Pink Floyd)

Re: common.fv not working - have I missed something?

Posted by Thorsten Scherler <th...@apache.org>.
El vie, 13-01-2006 a las 18:34 +1300, Paul Bolger escribió:
> I've done a bit more experimentation and it seems that pult.fv works
> as expected in the xdocs directory - affects all documents below it -

That is done by

forrest-trunk/whiteboard/plugins/org.apache.forrest.plugin.internal.structurer$ cat locationmap.xml
...
  <act type="RecursiveDirectoryTraversalAction" src="">
    <parameter value="{1}" name="request"/>
    <parameter value="{project:theme}" name="projectFallback"/>
    <parameter value="{project:theme-ext}" name="projectExtension"/>
    <parameter value="{project:content.xdocs}" name="projectDir"/>
    <!--  project-based theme-based = directory-based / parent-directory
based (recursively) -->
    <location src="{uri}" />
  </act>
...


> if a pult.fv file exists in the project local themes directory. 

Hmm, you mean you have to have a default structurer for the theme in the
theme dir?

> It
> doesn't matter if that file has any content. It also seems this also
> sets the project css default directory to the pult theme directory
> (I'm really starting to regret not giving this theme a sensible name!)

Yes, see the other mail, but you can still use and place them in your
local common directory since it gets matched by the lm. Generally we
assume that a theme will only override parts of the common stuff, but
keeping the resources in the {customTheme} resource dir makes them
unique usable for this theme (if {customTheme} != common).

> Does this mean I've found a real, live, bug?

That part about only if it exist in the theme dir sounds like one, but
as more I think about it, it seems to be a feature. ;-) I mean a theme
*has to* provide a default structurer {themeName}.fv in the theme dir
otherwise it cannot be used out of the box. It would forces the user to
add a default structurer for the customTheme which is not good.

>  It'd be good to adjust
> the documentation to reflect what's going on, but I'm loathe to spend
> much time on it if it's about to be swept away by v3.

v3 has changed the internal processing for delivering e.g. html and some
grammar but the concepts are the same.

salu2
-- 
thorsten

"Together we stand, divided we fall!" 
Hey you (Pink Floyd)

Re: common.fv not working - have I missed something?

Posted by Paul Bolger <pb...@gmail.com>.
I've done a bit more experimentation and it seems that pult.fv works
as expected in the xdocs directory - affects all documents below it -
if a pult.fv file exists in the project local themes directory. It
doesn't matter if that file has any content. It also seems this also
sets the project css default directory to the pult theme directory
(I'm really starting to regret not giving this theme a sensible name!)
Does this mean I've found a real, live, bug? It'd be good to adjust
the documentation to reflect what's going on, but I'm loathe to spend
much time on it if it's about to be swept away by v3.

Re: common.fv not working - have I missed something?

Posted by Paul Bolger <pb...@gmail.com>.
> > <forrest:css url="styles.css" media="screen" theme="pult"/>
>
> Actually that is only interesting for the theme switcher and optional.

The dispatcher docs  (howto-structurer-dsl) says

(attribute:theme) 3. the theme, "pelt" is the default theme (another
is the "common" theme). Change this if you are using your own theme.

Which to me means 'if you want to use css from a theme other than the
default set that here'.
In a recent post you wrote about using multiple themes. I didn't
really understand how this could be done. Could you clarify please.

> > but Forrest ignoring them and just looking in the common/css directory.
>
> hmm, have you modified your locationmap?

No I haven't. Wouldn't redirecting using locationmap be a sort of
'bulldozer' solution?
Right at the moment I'm finding the whole theme setting/defining
procedure quite confusing.  Wouldn't it make sense to set the project
theme in forrest.properties, and then have all views, css locations
etc cascade from that unless specifically overridden? This would mean
you could make a copy of a theme, put it in your project themes/
directory, set the theme in forrest.properties, and then - barring
putting an .fv file in your xdocs/ directory - do all theme fiddling
within the theme copy.

pb

Re: common.fv not working - have I missed something?

Posted by Thorsten Scherler <th...@apache.org>.
El jue, 12-01-2006 a las 23:10 +1300, Paul Bolger escribió:
> Actually, come to think of it: the css links in the common.fv file
> have theme attributes:
> 
> <forrest:css url="styles.css" media="screen" theme="pult"/>

Actually that is only interesting for the theme switcher and optional.

> 
> but Forrest ignoring them and just looking in the common/css directory.

hmm, have you modified your locationmap? 

It should look in 
pult/css

if you defined pult as project.theme.

salu2
-- 
thorsten

"Together we stand, divided we fall!" 
Hey you (Pink Floyd)

Re: common.fv not working - have I missed something?

Posted by Paul Bolger <pb...@gmail.com>.
Actually, come to think of it: the css links in the common.fv file
have theme attributes:

<forrest:css url="styles.css" media="screen" theme="pult"/>

but Forrest ignoring them and just looking in the common/css directory.

How do the structurer and themes work? (was Re: common.fv not working - have I missed something?)

Posted by Thorsten Scherler <th...@apache.org>.
El vie, 13-01-2006 a las 10:43 +1300, Paul Bolger escribió: 
> > If you do and want a fallback for pult you can
> > a) add it to {yourProject}/.../themes/pult.fv
> > b) add it to {yourProject}/.../xdocs/pult.fv
> >
> > This are absolute fallbacks.
> >
> > >  Now I have common.fv working,
> > > but Forrest isn't finding the modified theme.
> >
> > Hmm, weird. ...but if you do not specify pult in your properties that
> > would be the explanation. Anyway try adding pult.fv to b)
> >
> > > I've tried two entries,
> > > doesn't work; comma separated values, ditto;
> >
> > multiple fallbacks are not supported. It would be a logical problem
> > which fallback to use.
> >
> > > changing the name of
> > > 'common.fv' to pult.fv... I'm running out of ideas!
> > >
> >
> > changing common.fv to pult.fv and defining the theme in
> > forrest.properties should work.
> 
> But the problem with that is that 'common.fv' stops working. 

If you change the theme then surely common.fv is not taking anymore as
default structurer.

Let us start from the very beginning. You know more or less how old
fashion skins are working? 

The important thing about them is that each skin has to provide certain
files.

forrest-trunk/main/webapp/skins$ tree pelt/
pelt/
|-- css
|   |-- basic.css
|   |-- print.css
|   |-- profile.css.xslt
|   `-- screen.css
|-- images
|   |-- chapter.gif
|   |-- chapter_open.gif
|   |-- current.gif
|   |-- error.png
|   |-- header_white_line.gif
|   |-- info.png
|   |-- instruction_arrow.png
|   |-- label.gif
|   |-- page.gif
|   |-- pdfdoc.gif
|   |-- printer.gif
|   |-- success.png
|   |-- warning.png
|   `-- xmldoc.gif
|-- note.txt
|-- skinconf.xsl
`-- xslt
    |-- fo
    |   `-- document-to-fo.xsl
    `-- html
        |-- book-to-menu.xsl
        |-- document-to-html.xsl
        |-- site-to-xhtml.xsl
        `-- tab-to-menu.xsl

5 directories, 25 files

The interesting files that you need to change to create a new html skin
are in xslt/html. Skins are working with one fallback mechanism since
the common-skins is aimed to be the aggregation of common functions in
different skins. 

forrest-trunk/main/webapp/skins$ cat pelt/xslt/html/document-to-html.xsl
...
<xsl:import href="../../../common/xslt/html/document-to-html.xsl"/>
...

This import let you call and apply all templates that are in the common
skins. This makes it possible to only override parts of the common skin
to enhance maintenance. This idea can be as well found in the dispatcher
aimed to be even less copyless. That is the reason why some directories
in a theme are having the same name as in skins.

forrest-trunk/whiteboard/plugins/org.apache.forrest.plugin.output.themer/resources/themes$ tree
.
|-- common
|   |-- css
|   |   |-- basic.css
|   |   |-- common.css
|   |   |-- default.scale-dev.css
|   |   |-- new.css
|   |   `-- profiling.css.xslt
|   |-- html
|   |   |-- blank.ft
|   |   |-- branding-breadcrumbs.ft
|   |   |-- branding-fontsize.ft
|   |   |-- branding-logo.ft
|   |   |-- branding-tagline.ft
|   |   |-- content-abstract.ft
|   |   |-- content-author.ft
|   |   |-- content-authors.ft
|   |   |-- content-feeder.ft
|   |   |-- content-include-html.ft
|   |   |-- content-ls-contracts.ft
|   |   |-- content-main-lenya.ft
|   |   |-- content-main.ft
|   |   |-- content-minitoc.ft
|   |   |-- content-motd-page.ft
|   |   |-- content-pdf-link.ft
|   |   |-- content-pod-link.ft
|   |   |-- content-source-xml-link.ft
|   |   |-- content-title.ft
|   |   |-- content-txt-link.ft
|   |   |-- content-xml-link.ft
|   |   |-- export-link.vt.xml
|   |   |-- genericMarkup.ft
|   |   |-- helper-prototype-ajax.ft
|   |   |-- nav-main-sub.ft
|   |   |-- nav-main.ft
|   |   |-- nav-section.ft
|   |   |-- noFt.ft
|   |   |-- search-input.ft
|   |   |-- siteinfo-compliance-links.ft
|   |   |-- siteinfo-copyright.ft
|   |   |-- siteinfo-credits.ft
|   |   |-- siteinfo-current-time.ft
|   |   |-- siteinfo-feedback-dyn.ft
|   |   |-- siteinfo-feedback.ft
|   |   |-- siteinfo-last-published-net.ft
|   |   |-- siteinfo-last-published.ft
|   |   |-- siteinfo-meta-icon.ft
|   |   |-- siteinfo-meta-navigation.ft
|   |   `-- siteinfo-meta.ft
|   |-- images
|   |   |-- README.txt
|   |   |-- add.jpg
|   |   |-- built-with-forrest-button.png
|   |   |-- corner-imports.svg.xslt
|   |   |-- dc.svg.xslt
|   |   |-- external-link.gif
|   |   |-- fix.jpg
|   |   |-- forrest-credit-logo.png
|   |   |-- hack.jpg
|   |   |-- pdfdoc.gif
|   |   |-- poddoc.png
|   |   |-- poddoc.svg.xslt
|   |   |-- printer.gif
|   |   |-- rc.svg.xslt
|   |   |-- remove.jpg
|   |   |-- rss.png
|   |   |-- spacer.gif
|   |   |-- txtdoc.png
|   |   |-- txtdoc.svg.xslt
|   |   |-- update.jpg
|   |   |-- valid-html401.png
|   |   |-- vcss.png
|   |   `-- xmldoc.gif
|   `-- js
|       |-- LICENSE-prototype.txt
|       |-- breadcrumbs-optimized.js
|       |-- breadcrumbs.js
|       |-- fontsize.js
|       |-- getBlank.js
|       |-- getMenu.js
|       |-- menu.js
|       `-- prototype.js
|-- common.fv
|-- pelt
|   |-- css
|   |   |-- leather-dev.css
|   |   |-- pelt.basic.css
|   |   |-- pelt.print.css
|   |   `-- pelt.screen.css
|   |-- html
|   |   |-- branding-theme-profiler.ft
|   |   |-- content-abstract.ft
|   |   |-- content-main.ft
|   |   |-- nav-main-sub.ft
|   |   |-- nav-section-round-bottom.ft
|   |   |-- nav-section.ft
|   |   |-- search-input.ft
|   |   `-- siteinfo-credits.ft
|   |-- images
|   |   |-- Thumbs.db
|   |   |-- chapter.gif
|   |   |-- chapter_open.gif
|   |   |-- current.gif
|   |   |-- doc.gif
|   |   |-- header-background-grad.png
|   |   |-- header-background.gif
|   |   |-- header-background.png
|   |   |-- header_white_line.gif
|   |   |-- instruction_arrow.png
|   |   |-- label.gif
|   |   |-- page.gif
|   |   |-- pdfdoc.gif
|   |   |-- printer.gif
|   |   |-- search-left.gif
|   |   |-- search-right.gif
|   |   |-- sidebar_bg.gif
|   |   |-- singlepage.gif
|   |   |-- spacer.gif
|   |   |-- tab-left.gif
|   |   |-- tab-right.gif
|   |   |-- tl-off.gif
|   |   |-- tl-on.gif
|   |   |-- tr-off.gif
|   |   |-- tr-on.gif
|   |   `-- xmldoc.gif
|   `-- js
`-- pelt.fv

10 directories, 117 files

Like you see the common theme provides most of the contracts but the
default structurer for this just uses some. This can be seen by looking
on the dispatcher contracts that are only implemented for common.fv
needed contracts.

forrest-trunk/main/template-sites/v3/src/documentation/resources/themes/
|-- common
|   |-- css
|   |   |-- branding-generic-css.ft
|   |   `-- branding-theme-profiler.ft
|   |-- html
|   |   |-- ajax-example.ft
|   |   |-- blank.ft
|   |   |-- branding-css-links.ft
|   |   |-- branding-tagline.ft
|   |   |-- branding-theme-switcher.ft
|   |   |-- content-abstract.ft
|   |   |-- content-main.ft
|   |   |-- content-minitoc.ft
|   |   |-- content-pdf-link.ft
|   |   |-- content-source-xml-link.ft
|   |   |-- content-title.ft
|   |   |-- content-xml-link.ft
|   |   |-- master.ft
|   |   |-- nav-main-sub.ft
|   |   |-- nav-main-testing-foo.ft
|   |   |-- nav-main-testing.ft
|   |   |-- nav-main.ft
|   |   |-- nav-section.ft
|   |   |-- search-input.ft
|   |   |-- siteinfo-feedback.ft
|   |   |-- siteinfo-last-published.ft
|   |   |-- siteinfo-meta.ft
|   |   |-- xhtml2-content-abstract.ft
|   |   |-- xhtml2-content-body.ft
|   |   |-- xhtml2-content-title.ft
|   |   `-- xhtml2-content-toc.ft
|   |-- js
|   |   `-- cssStyleSwitcher.js
|   `-- xhtml2
|       |-- abstract.ft
|       |-- blank.ft
|       |-- body.ft
|       |-- title.ft
|       `-- toc.ft
`-- common.fv

6 directories, 37 files

The pelt theme is depending on the rest of the contracts. Remember what
I said about the xsl:import in old fashion skin?

"This import let you call and apply all templates that are in the common
skins. This makes it possible to only override parts of the common skin
to enhance maintenance."

If you call templates contracts, then we are coming to the dispatcher.
Since we have in skins 4 big xsl where we mix structuring markup with
pure contracts. This makes it hard to change the design rapid since you
have to edit the xsl whenever you only wanted to change some positions
of contracts.

We had started to encapsulate functional code into templates, but there
are still in 4 xsl files and without any documentation what they are
doing and how to use them. IMO that is the highest entry barrier in
understanding skins. The skinconf was a very good start to document
contracts but it is too inflexible.

Back to contracts used in views/dispatcher, they are standalone, self
explaining, configurable pieces of xsl templates, created out of pure
maintenance reasons. This leads us to one entry barrier understanding
the dispatcher - the locationmap. The locationmap allows us to let the
user decide which resources to use and to provide an awesome fallback
mechanism (in the end we are matching the common core templates). 

forrest-trunk/whiteboard/plugins/org.apache.forrest.plugin.output.themer
$ cat locationmap.xml
...
<!-- Project implementation of templates have priority before default
ones. If no implementation can be found we use the noFt (~ - no
forrest:template) implementation.  
{1} format
{2} name of the contract 
-->
  <match pattern="resolve.contract.*.**">
    <select type="exists">
      <!-- project-based theme -->
      <!-- 1. selected theme -->
      <location
src="{lm:themer.project.dir}/{project:theme}/{1}/{2}.ft" />
      <!-- project-based default fallback -->
      <!-- 2. {defaults:theme} theme for us "common"-->
      <location
src="{lm:themer.project.dir}/{defaults:theme}/{1}/{2}.ft" />
      <!-- project-application-based theme -->
      <!-- 3. {project:themer} is a collection of themes -->
      <location
src="{project:themer}/resources/themes/{project:theme}/{1}/{2}.ft" />
      <!--  project-application-based default fallback -->
      <!-- 4. This collection of themes can provide as well a common
theme -->
      <location
src="{project:themer}/resources/themes/{defaults:theme}/{1}/{2}.ft" />
      <!--  plugin provided contracts -->
      <!-- 5. {project:themer} is a collection of themes -->
      <location src="{lm:resolvePluginContract.{1}.{2}}" />
      <!-- forrest-application-based theme -->
      <!-- 6. plugins can provide contracts as well -->
      <location
src="{defaults:themer}/resources/themes/{project:theme}/{1}/{2}.ft" />
      <!--  forrest-application-based default fallback -->
      <!-- 7. finally we are looking for the contract in the core -->
      <location
src="{defaults:themer}/resources/themes/{defaults:theme}/{1}/{2}.ft" />
      <!--  forrest-application-based no found -->
      <!-- 8. Giving up -->
      <location
src="{defaults:themer}/resources/themes/{defaults:theme}/{1}/noFt.ft" />
    </select>
  </match>
...


> I think
> we need to clarify this as the docs (which I had a hand in writing)
> say that common.fv sets the same view (I'm using view in the sense
> that it's a set of contracts, hooks and css links in a .fv file which
> lay out the structure of an output document - correct me if that's not
> the meaning of view) for all the documents unless overridden. 

The common.fv (structurer) is the default configuration file as fallback
for the *common* theme. In the dispatcher actually a structurer can only
provide contracts and hooks since css-links are too html specific (those
are done with contracts). In a structurer you can define x different
views (formats) for an url. 

To be more specific on the fallback mechanism:
forrest-trunk/whiteboard/plugins/org.apache.forrest.plugin.internal.structurer$ cat locationmap.xml
<!-- File specific structurer have priority before default ones. If no
structurer can be found in the project, we use either the theme or the
default one of the themes plugin. 
{project:theme-ext} = project.theme-extension
{project:theme} = project.theme
-->
<match pattern="resolve.structurer.**">
  <select type="exists">
   <!-- project-based file-based
{1} request (e.g. index or docs/index) -->
   <location src="{project:content.xdocs}{1}{project:theme-ext}" />
   <act type="RecursiveDirectoryTraversalAction" src="">
    <parameter value="{1}" name="request"/>
    <parameter value="{project:theme}" name="projectFallback"/>
    <parameter value="{project:theme-ext}" name="projectExtension"/>
    <parameter value="{project:content.xdocs}" name="projectDir"/>
    <!--  project-based theme-based = directory-based / parent-directory
based (recursively) 
#  *description*
#  Forrest will resolve which structurer is responsible
#  for the request with the help of the themes fallback.
#
#  If no structurer (first choice or fallback) can be found,
#  the structurer will return the default core fallback
#  ({defaults:view-themes}/{defaults:theme}{defaults:theme-ext}).
#
# Example (common.fv - the fallback structurer of the common theme):
# 1.request: index
#  First choice: index.{project:theme-ext} = index.fv
#  First/last fallback: {project:theme}.{project:theme-ext} = common.fv
#
# 2.request: sample/index
#  First choice: sample/index.fv
#  First fallback: sample/common.fv
#  Last fallback: common.fv
#
# 3.request: sample/subdir/index
#  First choice: sample/subdir/index.fv
#  First fallback: sample/subdir/common.fv
#  Second fallback: sample/common.fv
#  Last fallback: common.fv
# ...
# The parent structurer inherits to its children until a child
# is overriding this template. This fallback templating can be
# used to have directory (common.fv) based and/or file (*.fv) specific
theming.
# That means that the root structurer is the default structurer as long
no other
# structurer can be found in the requested child.
##########################################

-->
    <location src="{uri}" />
   </act>
   <!-- themes-dir: project-application-based theme-dir-based -->
   <location
src="{lm:themer.project.dir}/{project:theme}{project:theme-ext}"/>
   <!-- themer: project-application-based theme-based -->
   <location
src="{project:themer}/resources/themes/{project:theme}{project:theme-ext}" />
   <!-- themes-dir: project-application-based default -->
   <location
src="{lm:themer.project.dir}/{defaults:theme}{defaults:theme-ext}"/>
   <!-- themer: project-application-based default -->
   <location
src="{project:themer}/resources/themes/{defaults:theme}{defaults:theme-ext}" />
   <!-- themer: forrest-application-based theme-based -->
   <location
src="{defaults:themer}/resources/themes/{project:theme}{project:theme-ext}"/>
   <!-- themer: forrest-application-based default -->
   <location
src="{defaults:themer}/resources/themes/{defaults:theme}{defaults:theme-ext}"/>
  </select>
</match>

> I
> doesn't say that this is also sets the theme to 'common'. 

That is correct. You need to activate common theme it in the
forrest.properties. 

> I'm getting
> confused here over whether the 'common' in 'common.fv' is related to
> the 'common' in the theme 'common' or whether we are just using the
> same term with a different meaning in a different context.
> 

see above.

"The common.fv (structurer) is the default configuration file as
fallback for the *common* theme." They are directly related. The same is
true for the pelt theme and pelt.fv. It is always {theme}.fv.

> 
> 
> > All what I said assumes that you are changing stuff in your project and
> > *NOT* in the core.
> 
> That's correct: 'Pult' is a copy of Pelt, and it's at
> \$ProjectHome\src\documentation\resources\themes\pult\

HTH

...and yes we have to document this better. 

Patches welcome. ;-)

salu2
-- 
thorsten

"Together we stand, divided we fall!" 
Hey you (Pink Floyd)

Re: common.fv not working - have I missed something?

Posted by Paul Bolger <pb...@gmail.com>.
> If you do and want a fallback for pult you can
> a) add it to {yourProject}/.../themes/pult.fv
> b) add it to {yourProject}/.../xdocs/pult.fv
>
> This are absolute fallbacks.
>
> >  Now I have common.fv working,
> > but Forrest isn't finding the modified theme.
>
> Hmm, weird. ...but if you do not specify pult in your properties that
> would be the explanation. Anyway try adding pult.fv to b)
>
> > I've tried two entries,
> > doesn't work; comma separated values, ditto;
>
> multiple fallbacks are not supported. It would be a logical problem
> which fallback to use.
>
> > changing the name of
> > 'common.fv' to pult.fv... I'm running out of ideas!
> >
>
> changing common.fv to pult.fv and defining the theme in
> forrest.properties should work.

But the problem with that is that 'common.fv' stops working. I think
we need to clarify this as the docs (which I had a hand in writing)
say that common.fv sets the same view (I'm using view in the sense
that it's a set of contracts, hooks and css links in a .fv file which
lay out the structure of an output document - correct me if that's not
the meaning of view) for all the documents unless overridden. I
doesn't say that this is also sets the theme to 'common'. I'm getting
confused here over whether the 'common' in 'common.fv' is related to
the 'common' in the theme 'common' or whether we are just using the
same term with a different meaning in a different context.



> All what I said assumes that you are changing stuff in your project and
> *NOT* in the core.

That's correct: 'Pult' is a copy of Pelt, and it's at
\$ProjectHome\src\documentation\resources\themes\pult\

Re: common.fv not working - have I missed something?

Posted by Thorsten Scherler <th...@apache.org>.
El jue, 12-01-2006 a las 22:51 +1300, Paul Bolger escribió:
> Thanks Cyriaque. That's the answer to the my first problem.
> 
> Hi Thorsten - now my problem is that I have a copy of 'pelt', er
> 'pult' in which I have a few modified contracts (in my local themes
> directory) Before changing the project theme to 'common' I was
> specifying 'pult' as the project theme.

If you do and want a fallback for pult you can 
a) add it to {yourProject}/.../themes/pult.fv
b) add it to {yourProject}/.../xdocs/pult.fv

This are absolute fallbacks.

>  Now I have common.fv working,
> but Forrest isn't finding the modified theme. 

Hmm, weird. ...but if you do not specify pult in your properties that
would be the explanation. Anyway try adding pult.fv to b)

> I've tried two entries,
> doesn't work; comma separated values, ditto; 

multiple fallbacks are not supported. It would be a logical problem
which fallback to use.

> changing the name of
> 'common.fv' to pult.fv... I'm running out of ideas!
> 

changing common.fv to pult.fv and defining the theme in
forrest.properties should work.

All what I said assumes that you are changing stuff in your project and
*NOT* in the core.

hth
salu2

> thanks
> Paul b
> 
> 
> 
> On 12/01/06, Thorsten Scherler <th...@apache.org> wrote:
> > El jue, 12-01-2006 a las 10:01 +0100, Cyriaque Dupoirieux escribió:
> > > Hi Paul,
> > >
> > >     check the following properties in your project forrest.properties :
> > >
> > >     # codename: views
> >
> > The project.skin became obsolete with v2, since v2 do not depend anymore
> > on skins:
> >
> > >     # uncomment the following skin if you are using views
> > >     project.skin=*leather-dev*
> >
> > Just to make sure: project.theme=common (without *).
> >
> > >     # views is using a fallback mechanism for theming.
> > >     # You can configure the theme name and its extension here
> > >     project.theme-extension=.fv
> > >     project.theme=*common*
> > >
> > > Then your common fv file should be common.fv...
> > >
> > > Salutations,
> > > Cyriaque,
> > >
> > >
> > > Paul Bolger a écrit :
> > >
> > > >I've just done a SVN update, built Forrest, built the two dispatcher
> > > >plugins, Forrest seed-v2 a new instance. I then added an instance of
> > > >common.fv but Forrest ignores it. I'd think that there was a setting
> > > >in forrest.properties which I've missed (it's changed quite a bit
> > > >since I last did this) but renaming common.fv to index.fv results in
> > > >the view working fine on the single target file. Any ideas anyone?
> > > >
> >
> > What theme do you see, since you said it get ignored. If you see pelt
> > Cyriaque gave the answer.
> >
> > salu2
> >
> > > >paul b
> > > >
> > > >
> > > >
> > > >
> > --
> > thorsten
> >
> > "Together we stand, divided we fall!"
> > Hey you (Pink Floyd)
> >
> >
> 
> 
> --
> Paul Bolger
> 19 Raggatt St
> Alice Springs
> NT 0870
> 08 8953 6780
-- 
thorsten

"Together we stand, divided we fall!" 
Hey you (Pink Floyd)

Re: common.fv not working - have I missed something?

Posted by Paul Bolger <pb...@gmail.com>.
Thanks Cyriaque. That's the answer to the my first problem.

Hi Thorsten - now my problem is that I have a copy of 'pelt', er
'pult' in which I have a few modified contracts (in my local themes
directory) Before changing the project theme to 'common' I was
specifying 'pult' as the project theme. Now I have common.fv working,
but Forrest isn't finding the modified theme. I've tried two entries,
doesn't work; comma separated values, ditto; changing the name of
'common.fv' to pult.fv... I'm running out of ideas!

thanks
Paul b



On 12/01/06, Thorsten Scherler <th...@apache.org> wrote:
> El jue, 12-01-2006 a las 10:01 +0100, Cyriaque Dupoirieux escribió:
> > Hi Paul,
> >
> >     check the following properties in your project forrest.properties :
> >
> >     # codename: views
>
> The project.skin became obsolete with v2, since v2 do not depend anymore
> on skins:
>
> >     # uncomment the following skin if you are using views
> >     project.skin=*leather-dev*
>
> Just to make sure: project.theme=common (without *).
>
> >     # views is using a fallback mechanism for theming.
> >     # You can configure the theme name and its extension here
> >     project.theme-extension=.fv
> >     project.theme=*common*
> >
> > Then your common fv file should be common.fv...
> >
> > Salutations,
> > Cyriaque,
> >
> >
> > Paul Bolger a écrit :
> >
> > >I've just done a SVN update, built Forrest, built the two dispatcher
> > >plugins, Forrest seed-v2 a new instance. I then added an instance of
> > >common.fv but Forrest ignores it. I'd think that there was a setting
> > >in forrest.properties which I've missed (it's changed quite a bit
> > >since I last did this) but renaming common.fv to index.fv results in
> > >the view working fine on the single target file. Any ideas anyone?
> > >
>
> What theme do you see, since you said it get ignored. If you see pelt
> Cyriaque gave the answer.
>
> salu2
>
> > >paul b
> > >
> > >
> > >
> > >
> --
> thorsten
>
> "Together we stand, divided we fall!"
> Hey you (Pink Floyd)
>
>


--
Paul Bolger
19 Raggatt St
Alice Springs
NT 0870
08 8953 6780

Re: common.fv not working - have I missed something?

Posted by Thorsten Scherler <th...@apache.org>.
El jue, 12-01-2006 a las 10:01 +0100, Cyriaque Dupoirieux escribió:
> Hi Paul,
> 
>     check the following properties in your project forrest.properties :
> 
>     # codename: views

The project.skin became obsolete with v2, since v2 do not depend anymore
on skins:

>     # uncomment the following skin if you are using views
>     project.skin=*leather-dev*

Just to make sure: project.theme=common (without *).

>     # views is using a fallback mechanism for theming.
>     # You can configure the theme name and its extension here
>     project.theme-extension=.fv
>     project.theme=*common*
> 
> Then your common fv file should be common.fv...
> 
> Salutations,
> Cyriaque,
> 
> 
> Paul Bolger a écrit :
> 
> >I've just done a SVN update, built Forrest, built the two dispatcher
> >plugins, Forrest seed-v2 a new instance. I then added an instance of
> >common.fv but Forrest ignores it. I'd think that there was a setting
> >in forrest.properties which I've missed (it's changed quite a bit
> >since I last did this) but renaming common.fv to index.fv results in
> >the view working fine on the single target file. Any ideas anyone?
> >

What theme do you see, since you said it get ignored. If you see pelt
Cyriaque gave the answer. 

salu2

> >paul b
> >
> >
> >  
> >
-- 
thorsten

"Together we stand, divided we fall!" 
Hey you (Pink Floyd)

Re: common.fv not working - have I missed something?

Posted by Cyriaque Dupoirieux <Cy...@pcotech.fr>.
Hi Paul,

    check the following properties in your project forrest.properties :

    # codename: views
    # uncomment the following skin if you are using views
    project.skin=*leather-dev*
    # views is using a fallback mechanism for theming.
    # You can configure the theme name and its extension here
    project.theme-extension=.fv
    project.theme=*common*

Then your common fv file should be common.fv...

Salutations,
Cyriaque,


Paul Bolger a écrit :

>I've just done a SVN update, built Forrest, built the two dispatcher
>plugins, Forrest seed-v2 a new instance. I then added an instance of
>common.fv but Forrest ignores it. I'd think that there was a setting
>in forrest.properties which I've missed (it's changed quite a bit
>since I last did this) but renaming common.fv to index.fv results in
>the view working fine on the single target file. Any ideas anyone?
>
>paul b
>
>
>  
>