forrest-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <rgard...@apache.org>
Subject Re: Reusing legacy HTML
Date Wed, 16 Feb 2005 16:49:03 GMT
Ferdinand Soethe wrote:
> So here it is. Your comments much appreciated before I format it for
> inclusion in the Forrest documention?

I've moved to the dev list rather than the user list. The devs want to 
see this develop, the users want the final document.

> I was going to use document.dtd and write a second shorter and more to
> the point how-to on the specifics of processing your own legacy html.
> OK?

That would be brilliant (don't forget we have a HowTo DTD).

> So this tries to explain what happens internally when a clients asks Forrest to serve
> "mytests/mybad.html", a legacy html-file with lots of junk in
> it.

junk = things like legacy navigation?

> 
> 0. Clients asks Forrest to serve ".../xdocs/mytests/mybad.html"

"http://some.domain.org/mystest/mybad.html"

> 1. Forrest looks for a matching pipeline in
>    "...\forrest\main\webapp\sitemap.xmap".
> 
> 2. This Pattern  would in fact match the request but generates no xml since the
>    map:parts match no cocoon pipeline and thus no xml is generated.

Actually this does not match because *.html will only match something 
like "mybad.html". Here you have a directory structure so you need "**" 
in order to match it. "*" means a single part of an URL, "**" means any 
number of parts to an URL.


> 3. This pattern also matches the request and is used to continue
>    processing
>    
>         <map:match pattern="**/*.html">
>                                                 {0}= mytests/mybad.html
>                                                 {1}= mytests
>                                                 {2}= mybad
>             <map:aggregate element="site">
>               <map:part src="cocoon:/skinconf.xml"/> adds skin info
>               <map:part src="cocoon:/build-info"/> adds meta data
>               <map:part src="cocoon:/{1}/tab-{2}.html"/> creates tabs
>                            =>cocoon:/mytests/tab-mybad.html
>               <map:part src="cocoon:/{1}/menu-{2}.html"/> creates menus
>                           =>cocoon:/mytests/menu-mybad.html
>                           
>               Below a cocoon pipeline is called to generate the body 
>               <map:part src="cocoon:/{1}/body-{2}.html"/>
>                           =>cocoon:/mytests/body-mybad.html
>                           
>              return here for the rest of this pipeline in step 9
>               
>           
> 4.  This is the pipeline called in step 3
>     Check if there is an ehtml-file (deprecated embedded html)
>     
>         <map:match pattern="**body-*.html">
>                                             {0}= mytests/body-mybad.html
>                                                 {1}= mytests/
>                                                 {2}= mybad
>         <map:select type="exists">
>           <map:when test="{project:content.xdocs}{1}{2}.ehtml">
>                         =>.../xdocs/mytests/mybad.ehtml 

The value of {project:content.xdocs} depends on the settings in 
forrest.properties

>             <map:generate src="{project:content.xdocs}{1}{2}.ehtml" />
>                              =>.../xdocs/mytests/mybad.ehtml 
>             <map:transform src="{forrest:stylesheets}/html2htmlbody.xsl" />
>             <map:transform type="linkrewriter" src="cocoon:/{1}linkmap-{2}.html"/>
>                                                   =>cocoon://mytests/linkmap-mybad.html

>             <map:transform src="resources/stylesheets/declare-broken-site-links.xsl"
/>
>             <map:serialize type="xml" />
>           </map:when>
>         </map:select>
>       </map:match>        
> 
>       Since file does not exist, pipeline generates nothing so Forrest
>       keeps looking for next matching pipeline ...

Yes, a pipeline is only considered as having executed when it generates 
some content, the test for the *.ehtml file fails so no processing is done.

> 5. ... and finds another pipeline for the same matches
> 
>   <!-- Default matches -->
>   <!-- (HTML rendered from doc-v11 intermediate format -->
>   <map:match pattern="**body-*.html">
>                                             {0}= mytests/body-mybad.html
>                                                 {1}= mytests/
>                                                 {2}= mybad
>   
>     In the following step we ask Forrest to call the pipeline for mybad.xml.
>     This triggers a new matching attempt starting from the top of the pipeline section.
>   
>     <map:generate src="cocoon:/{1}{2}.xml"/>
>                      =>cocoon:/mytests/mybad.xml
>     
>     Return here for the rest of this pipeline in step

The number of slashes is significant. "cocoon:/" means look for a 
pipeline in the current sitemap, "cocoon://" means look for a match in 
any xmap. This is not significant a this point but will be later.

> 6. This below is relevant now as it loads the project sitemap and
>    inserts it right at this position of the main sitemap. (This project
>    sitemap was also loaded before, but was irrelevant since there were no matches
>    in the project sitemap)

Probably best, in the documentation to describe what happens *without* a 
project sitemap first since this will be the default behaviour. Then 
your howto can describe how the project sitemap intercepts this request.

>   <!-- 
>      This is the user pipeline, that can answer requests instead
>      of the Forrest one, or let requests pass through.
>      To take over the rendering of a file it must match the file name and path.
>      To take over the generation of the intermediate format, it must give
>      Forrest the same filename but ending with xml, and a DTD that Forrest
>      recognizes.
>   -->
>   <map:pipeline internal-only="false"> 4t!!!h step patterns above first
>        <map:select type="exists">
>          <map:when test="{project:sitemap}">
>            <map:mount uri-prefix="" 
>                       src="{project:sitemap}" 
>                       check-reload="yes" 
>                       pass-through="true"/>
>          </map:when>  
>        </map:select>
>   </map:pipeline> 
> 
> 7. In the project sitemap we find this match for our call for an XML-file!
> 
>         <map:match pattern="**/mybad.xml">
>                                                 {0}= mytests/mybad.xml
>                                                 {1}= mytests
>                                                 
>   
> 
>         Load my file with the html-generator. This generator
>         internally uses jtidy to clean up the html and make it xhtml.
>         
>         <map:generate src="{project:content.xdocs}{1}/mybad.html" type="html"/>
> 
>         Now we call my special stylesheet to remove all
>         elements that I don't want in the forrest page.
>         I place it in the same directory as the source document as it
>         is very specific.
>         
>         <map:transform src="{project:content.xdocs}{1}/mybadHTMLfixer.xsl"/>


Stylesheets should be placed in the {project:resources.stylesheets} 
directory, only displayable content should be in the xdocs directory.

>         Finally call the existing stylesheet to convert html to document1.1
>         <map:transform src="{forrest:stylesheets}/html2document.xsl" />
>         
>         Serialize result as xml (it is now the body of my Forrest page
>         and uses in document.dtd)
>         <map:serialize type="xml"/>
>         
>       </map:match>
>       
>   
>  8. Return to calling routine in step 5 and execute the rest of the pipeline
>     to finalize the body of my Forrest page.
>     
>                         {0}= mytests/body-mybad.html
>                                                 {1}= mytests/
>                                                 {2}= mybad
>     
>             ???
>             <map:transform type="idgen"/>

generates ID attributes for elements that are used for internal linking 
(i.e. <a href="thispage.html#thatPosition">Go to thatPosition</a>)

> 
>             ???
>             <map:transform type="xinclude"/>

XInclude content from other files (see http://www.w3.org/TR/xinclude/)


>             Adjust links
>             <map:transform type="linkrewriter" src="cocoon:/{1}linkmap-{2}.html"/>
>                                                   => cocoon:/mytests/linkmap-mybad.html
>             <map:transform src="resources/stylesheets/declare-broken-site-links.xsl"
/>
>             <map:call resource="skinit">
>               <map:parameter name="type" value="document2html"/>
>               <map:parameter name="path" value="{1}{2}.html"/>
>                                               => mytests/mybad.html 
>               <map:parameter name="notoc" value="false"/>
>             </map:call>
>    </map:match>
>   
>    At the end of the pipeline this is the page body in Html with all
>    links adjusted.

Yes, to see it you can type http://localhost:8888/mytest/body-mybad.html 
into your browser.

> 9. Return to the calling routine in step 3 and finish processing
> 
>                                 {0}= mytests/mybad.html
>                                                 {1}= mytests
>                                                 {2}= mybad
> 
>                 </map:aggregate>
>                 
>                 At this point the body (as html) is aggregated with the menus and tabs
>                 and the next part just adds the final touches to the presentation.
>                 
>             <map:call resource="skinit">
>               <map:parameter name="type" value="site2xhtml"/>
>               <map:parameter name="path" value="{0}"/>
>                                               => mytests/mybad.html
>             </map:call>
>           </map:match>      
>           
> 
>          At the end, the result is delivered to the browser. 

Looks good to me.

Ross

Mime
View raw message