forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ferdinand Soethe <ferdin...@apache.org>
Subject [Proposal] Rules for Forrest Use of class-Attributes
Date Thu, 05 Jan 2006 07:55:57 GMT
Some recent discussion on this list made me think a bit more about our
concepts with regard to the use of class attributes ...

I'd appreciate your comments.

Ferdinand Soethe

Function of class-Attributes
----------------------------

Forrest components (and users) use "class"-attributes in 4 different
ways:

1. Forrest uses class-attributes to preserve special meanings when
   transforming custom grammer (such as xdocs) to html.

   Example: In the following clipping (from document2html.xsl) you can
            see that the xdocs-elements 'warning', 'note' and 'fixme'
            (that have no equivalent in html) are transformed to
            div-elements and assigned a class-attribute to preserve
            meaning and allow for special formatting treatment.

            <xsl:template match="note | warning | fixme">
                <xsl:apply-templates select="@id"/>
                <div>
                  <xsl:call-template name="add.class">
                    <xsl:with-param name="class"><xsl:value-of select="local-name()"/></xsl:with-param>
                  </xsl:call-template>

2. Skinning uses class-attributes to identify, format and place skin specific
   (often generated) components such as menus and tabs.

3. Users add class-attributes to elements to create new meanings or
   add 'submeanings' to existing elements and facilitate formatting of
   those with the Extra-CSS-mechnism.

   Example: By adding a class 'instructions' to a simple bulleted list
            I can format these lists differently with extra-css.   
   
4. Plugins (often) need to use class-attributes (just like Forrest in
   2) to carry meaning over to html.


(My) Problems with the Current Approach
---------------------------------------

In customizing Forrest and attempting a plugin I found that our
current system will generally take care of functions 1 and 2, supports
3 to a limited extend and has few or no provisions for handling
funtion 4.

The problem I have identified so far are:

1. Class-transparency
   Most of our transformations are not class-transparent. A
   class-attribute fed into that transformation is often ignored,
   or overwritten.

2. No Conflict-Handling
   There is not concept to avoid or handle conflicts, when more than one
   function tries to add class to an element.

3. No rules for indirect transport of classes
   For example: Even though xdoc has a body-element, attaching a class
                or id to it will not carry it over into the body
                element of the final html because there is no direct
                tranformation.

Avoiding these problems
-----------------------
Since we are in the process of reqriting most of our pipelines for the
transition to xhtml, I'd like us to discuss a couple of binding rules
for the handling of class in Forrest.

Some of these could be (please add and correct)

- all transformations (including those in skinning and plugins)
  must preserve foreign class attributes. That is: Any class attributes
  attached to an element going into the transformation must be carried
  over into the resulting element.

  Transformations that significantly change the structure of elements
  or create multiple elements in the result tree (see the example of 'warning')
  should try to preserve class-attributes true to their meaning. For
  example transfer the warning-class to the surrounding div-element
  rather than its child element.
  
  Exception: Class-attributes created as internal markers within a
             chain of transformations may or even must be removed.

- When adding classes to elements that already have a class attribute,
  each new class it added to a space separated list. All
  transformations and css-formatting must be written to properly handle such
  class-lists.

- To avoid conflicts between class names created by different modules,
  a module-specific prefix is added to the class name. For Forrest core
  modules and extra-css-classes this prefix can be static while each new
  plugin should be automatically assigned a unique prefix to use with
  all their class names.

  Example Class Naming

     function        prefix
     Forrest core    fo..
        menus        fomu-
        tabs         fota-
        body         fobo-
        footer       fofo-
        etc.

     extra-css       ecss-

     plugin          pi..
       skills-plugin   piskill-
       docbook-plugin  pidb-
       etc.

- Facilitate indirect transport

  To facilitate indirect transport (such as the class from body of
  xdocs to body of html) we should create and clearly document
  class-channels in our transformation. In other words, make sure that
  there is a channel class or id attributes into all major elements of
  a page and document it ("if you want id in the html-body, attach it
  to xdocs document-element").
  
       
Open Issues
-----------

I have no idea how all this will be effected by structurer. Can one of
the insiders please comment.





























--
Ferdinand Soethe


Mime
View raw message