forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Thorsten Scherler <thors...@apache.org>
Subject Re: [RT] plugin infrastructure
Date Thu, 11 Nov 2004 18:15:50 GMT
El jue, 11-11-2004 a las 14:46, Nicola Ken Barozzi escribió:
<snip/>
> > The problem is what you wrote above "Ok, but how will forrest render the
> > open office plugin, contract?" by now we will have to add this manually
> > in the ft. I mean the 
> > <contract name="openofficeplugin">
> >    <metadata name="param" value="some value"/>
> > </contract>
> > part. 
> 
> what does the above xml mean? Who writes it?
> 

Explaining the above mentioned xml snippet:
The output of the contract with the name "openofficeplugin" should be
placed in the location (depends on the overall ft). The metadata tag is
new I took it from this thread. I thought it would be some information
that are basic for the plugin and should be parsed like a param.

*What does it mean?*
The forrest-template (ft) is something like tiles in struts. Here you
can define how your site should look like in terms of div-container. I
invented to elements in the ft:
- hooks
- contracts

*hooks* are graphical div container that helps a designer to alter the
html skelleton. It is based on the assumption that a webdesigner needs
absolute freedom to change the default container (html-skelleton) for
the sake of a good look.

*contracts* are functions or specific content. All elements that we have
now like the logos are contracts. We define them in the skinconf.xml and
use them in the skins. Now we have fixed places (sometimes with
alternativ location) that depends on the skin author who placed them.

*hooks & contracts* the combination of both seems very powerful because
a) we do not have to write new skins to change the html skelleton. To
alter the html outcome we have the possibility to add graphical
container. That lets a designer place the elements where ever he likes
without touching the xsl-code.
b) we do not have to write new skins nor exend the old ones (if their
support ft) when we add a new feature. We just have to extend the ft and
add the new contract (all functions have contract names) where we want
have it displayed. 

Now lets have a look on an example:
The following template shows the pelt skin using leather naming 
conventions and graphical hooks.
<forrest-template>
   <contract name="branding-trail-path"/>
   <hook name="top">
     <contract name="grouplogo"/>
     <contract name="projectlogo"/>
     <contract name="search-input"/>
     <contract name="nav-main"/>
     <contract name="nav-main-sub"/>
   </hook>
   <hook name="main">
     <contract name="published-a1"/>
     <contract name="branding-trail-path-a1"/>
     <contract name="nav-section">
       <contract name="nav-section-current"/>
     </contract>
     <contract name="content">
       <contract name="content-pdf"/>
       <contract name="content-xml"/>
       <contract name="content-txt"/>
       <contract name="font-size"/>
       <contract name="minitoc"/>
     </contract>
   </hook>
   <hook name="clear"/>
   <hook name="footer">
     <contract name="siteinfo-legal"/>
     <contract name="published"/>
     <hook name="outro-feedback">
       <contract name="feedback"/>
     </hook>
   </hook>
</forrest-template>

After transforming this ft has the good old pelt DOM. Using a
transformation like:
<xsl:template match="hook">
  <div id="{@name}">
    <xsl:apply-templates />
  </div>
</xsl:template>
<xsl:template match="contract">
  <div id="{@name}">
    <xsl:apply-templates />
  </div>
</xsl:template>

We then have empty divs that have to be deployed with the actual
content. Read on. ;-)

Your so called nuggets are for me nothing else then new contracts.
Imagine that you want to add the nugget news to the above skin. 
e.g.
...
<hook name="main">
  <contract name="published-a1"/>
  <contract name="news"/>
...
</hook>
...

With the ft approach I just add the new contract in the place where it
should be displayed. I then will create a html/xml/xsl/... snippet that
contains the data. I will then store it in the fct-bits/ dir. The
directory generator now will output this new contract with something
like:
<xsl:template match="dir:file[starts-with(@name,'c-')]">
    <xsl:variable name="fct-bit-file">
      <xsl:value-of select="$contentDir"/>
      <xsl:text>/</xsl:text>
      <xsl:value-of select="@name"/>
    </xsl:variable>
    <xsl:variable name="fct-bit-title">
      <xsl:value-of select="document($fct-bit-file)/contract/@name"/>
    </xsl:variable>
    <xsl:variable name="fct-bit-nc">
      <xsl:value-of select="document($fct-bit-file)/contract/@nc"/>
    </xsl:variable>
    <xsl:variable name="fct-bit-tlc">
      <xsl:value-of select="document($fct-bit-file)/contract/@tlc"/>
    </xsl:variable>
    <xsl:variable name="fct-bit-description">
      <xsl:value-of select="document($fct-bit-file)/contract/description"/>
    </xsl:variable>
    <xsl:if test="$fct-bit-tlc='content'">
      <content>
        <contract name="{$fct-bit-title}" css="{$fct-bit-nc}" file-name="{@name}">
          <description>
            <xsl:value-of select="$fct-bit-description"/>
          </description>
          <realpath>
            <xsl:value-of select="$fct-bit-file"/>
          </realpath>
        </contract>
      </content>
    </xsl:if>
</xsl:template>

I then have to match all selected contracts of the ft and use something
like the following to extract the e.g. html output:
<xsl:template match="contract" mode="xhtml-head">
  <xsl:comment>function name=<xsl:value-of select="@name"/> HEAD</xsl:comment>
  <xsl:copy-of select="xhtml/head/*"/>
</xsl:template>

<xsl:template match="contract" mode="xhtml-body">
  <xsl:comment>function name=<xsl:value-of select="@name"/> BODY</xsl:comment>
  <xsl:copy-of select="xhtml/body/*"/>
</xsl:template>

Which can be called from the last xsl that I still have to develop. ;-)
I reckon I will have to parse the actual name of the function into the xsl via the directory
generator 


*Who writes it?*
1) In my RT I was talking about webdesigner who wants to alter the look
and feel of the site. 
2) There is always a default ft provided by the skin.
3) Plugin author have to provide their contract-snippet.

> >This should be normally done by adding a new plugin:
> > 
> > add plugin -> plugins adds the default contract and metadata to the ft
> > -> user can alter the ft -> user can implement his own implementation of
> > the contract
> 
> User? Who are you referring to here? Our users are documentation writers.
> 

...and webdesigner that producing the design of the site. 
...and functionality provider (mostly designer) that produce the extra
functionality of the site.
-> SOC ;-)

> > The other thing is that every plugin has to deliver a default output for
> > the skin. This is a fallback mechanism if the user do not want to
> > implemend his own implementation of the functionality.
> 
> Are we not mixing content (plugins) with style (skins) ?
> 

Yeah a wee bit, but on the other hand not at all. Some content produced
by plugins are "married" with functionality. Imagine a search-provider
plugin. I would like to create a plugin that is able to extend the
search form we have now. That means the "content" are the provider uri
that are conected with the functionality of searching.

> > The whole concept can be compared with the interface concept from java.
> > The interface is the contract. We will deliver a default implementation
> > of the contract.
> 
> Too generic, I don't understand. :-(   (yet ;-)

Thanks, not for not understanding but saying that it is generic.
Actually that is the power of the ft approach because it is generic it
can be easily extended.

In java you have an interface that are basicly contains:
- class name
- input parameter
- output parameter

Now in the ft case we have:
- class name -> contract name
- input param -> e.g. values from the skinconf
- output param -> e.g. <div id="content-pdf"/>

Now the implementation of a java interface is that you write a class
that is doing what the interface defines before.

The implementation of a contract is e.g.
http://svn.apache.org/viewcvs.cgi/forrest/trunk/main/webapp/skins/leather-dev/xslt/xml/fct-bits/c-fontsize-fct.xml?rev=56669&view=markup

The big advantage is that the forrest user (as defined above) can add
his/her own implementation of contracts following our example. I mean we
can allow to store project specific implementation of functionality and
use them instead of the fallbacks. 

I hope you understand a wee bit more what I am trying to say. ;-)

Please ask question and discuss the above. :) 

-- 
thorsten

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


Mime
View raw message