Mailing-List: contact dev-help@forrest.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@forrest.apache.org
Received-SPF: neutral (hermes.apache.org: local policy)
Subject: [HEADS-UP] fbits plugin is now org.apache.forrest.plugin.views
From: Thorsten Scherler <thorsten@apache.org>
To: dev@forrest.apache.org
Content-Type: text/plain
Date: Fri, 25 Mar 2005 22:17:53 +0100
Message-Id: <1111785473.14416.24.camel@localhost.localdomain>
Mime-Version: 1.0
Content-Transfer-Encoding: 7bit

Hello devs,

I cleaned up the fbits plugin by moving all important stuff to
org.apache.forrest.plugin.views and deleting the fbits plugin.

The org.apache.forrest.plugin.views is overriding the last step of the
skin-it pipe. So far all needed resources (img,..) are stored in the
leather-dev skin. I am still using great parts of those skin pipes. The
default implementation of the css is based on the scale-dev css
enhancement of leather-dev.

If you are planing to use this plugin make sure you set your
forrest.properties like follows (,... means all other plugins you need):
project.skin=leather-dev
project.required.plugins=org.apache.forrest.plugin.views,...


How it works 
************

(taken from SOME comments of the output.xmap of views)

This plugin has three components:
  1. fbits - delivers contracts in form of xsl:templates
  2. nuggets - delivers content that is used in the contracts
  3. views - prepares and transforms the requested contracts (fbits) 
     and populate them with the content (nuggets)


          request            request
+-------+<<--------+-------+-------->>+---------+
| fbits |          | views +          | nuggets |
+-------+-------->>+-------+<<--------+---------+
          response           response  


1. fbits
  This is the template producing factory.

a. <map:match pattern="resolve.contract.*"> -> Resolving factory
Project implementation of templates have priority before default ones.
If no implementation can be found we use the noFt (~ - no
forrest:template) implementation.

b. <map:match pattern="get.contract.*.*">
Get the xsl:templates of the requested contract and specific format.

c. <map:match pattern="get.contract-meta.*">
Get the forrest:properties of the requested contract. 
This will determine which templates (css, head, body) we have to call
later on

GENERAL:
Contracts are stored in forrest:templates ({contract-name}.ft) please
have look on
plugins/org.apache.forrest.plugin.views/resources/templates/*.ft do get
an idea how your own implementation have to look like.


2. nuggets
  This is the content producing factory.

NOTE: <map:match pattern="*.page">
The current factory uses the skin producing templates (e.g.
document2xhtml.xsl).
It is only exchanging the last step of a skin producing pipe
(site2xhtml.xsl) till now.
This will have to be changed in the future.


3. views
  prepares and transforms the requested contracts (fbits) and populate
them with the content (nuggets).

a.  <map:match pattern="prepare.view.*"> -> View config resolver
File specific views have priority before default ones.
If no view can be found in the project we use the default one of the
views plugin.

b.  <map:match pattern="prepare.include.*"> 
Aggregate the contract-templates requested by the view with xinclude.
The result is a stylesheet with all needed xsl:templates.

c. <map:match pattern="prepare.meta.*">
Aggregate the forrest:properties requested by the *.fv.
The result is an aggregation of properties which defines the templates
to be call.

d. <map:match pattern="prepare.xhtml.*">
Aggregate all contracts-templates requested by the view.
Create a xsl that can be used for the last step of the transformation of
the view.

e. <map:match pattern="*.html"> -> Last processing step. 
Here we are overriding the default skin generation.

GENERAL:
Views are stored in forrest:view ({file-name}.fv) please have look on
plugins/org.apache.forrest.plugin.views/src/documentation/default.fv do
get an idea how your own implementation have to look like.

Known issues
************
- The generation of the linking is not working.
- Menu /innermenu templates are added directly. Add support for
additional templates support.
- Uses resources of leather (document2html.xsl defines the pdf/xml/...
link this have to be done by the template).
- The views are only working for html so far
- The css support and implementation is VERY basic
- Only first level files are working
- ...

Resume
******
The views plugin can be seen as prototype for the next generation
skinning of forrest. It is still in early stage but with the cleanup I
hope to make it easier for all devs (not only committer) to get the idea
and help to enhance it.

Some basic and simple hints:
a) If you want another implementation of a contract then create a folder
"templates" in ${project.resources-dir} and it will be matched before
the standard implementation. 

e.g. feedback contract:
<forrest:contract name="feedback" type="nugget"
  xmlns:forrest="http://apache.org/forrest/templates/1.0">
<description>
This function will output the html feedback information.
</description>

<forrest:template
xmlns:forrest="http://apache.org/forrest/templates/1.0"
format="xhtml" name="feedback" inputFormat="xsl" body="true"
head="false" css="true">

<xsl:stylesheet version="1.1" 
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:jx="http://apache.org/cocoon/templates/jx/1.0">

<xsl:template name="feedback-css">
#feedback {
    color: black;
    background: #CFDCED;
    text-align:center;
    margin-top: 5px;
}
#feedback #feedbackto {
    font-size: 90%;
    color: black;
}</xsl:template>

<xsl:template name="feedback-body">
<div id="feedback"> Modified project implementation
<xsl:value-of select="$config/feedback"/>
<xsl:choose>
<xsl:when test="$config/feedback/@href and
not($config/feedback/@href='')">
  <a id="feedbackto">
    <xsl:attribute name="href">
      <xsl:value-of select="$config/feedback/@href"/>
      <xsl:value-of select="$path"/>
    </xsl:attribute>
    <xsl:value-of select="$config/feedback/@to"/>
  </a>
</xsl:when>
<xsl:otherwise>
  <xsl:value-of select="$config/feedback/@to"/>
</xsl:otherwise>
</xsl:choose>
</div>
</xsl:template>
</xsl:stylesheet>
</forrest:template>
</forrest:contract>

The @attributes (body="true" head="false" css="true") of the 
forrest:template defining which parts of the html page (head, head-css
and body) we have to render. The xsl:templates are following the simple
naming convention {@name}-(css|head|body).


b. If you want a default view for your project then copy the default.fv
from the plugin to your ${project.conf-dir} and modify this file. When
you want another view for a specific file (e.g. index.html) then copy
the default.fv to your ${project.xdocs-dir} and renamed it to e.g.
index.fv.

I am looking forward for your feedback and support. ;-)


salu2
-- 
thorsten

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