forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Thorsten Scherler <thors...@apache.org>
Subject How do the structurer and themes work? (was Re: common.fv not working - have I missed something?)
Date Fri, 13 Jan 2006 10:22:08 GMT
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)


Mime
View raw message