Home
 

Working with Apache Forrest

Working with Apache Forrest

Lance Hendrix

Revision History
13 April, 2013
Creation Date

Abstract

This article describes the work I have done with Apache Forrest in order to develop my personal publishing pipeline that is heavily based on DocBook as the content format with Apache Forrest as the publishing pipeline for publishing my website (primary goal) and rendering DocBook into other formats.


1. Purpose of this Document

The purpose of this document is to record some of my thoughts on using Apache Forrest as well as to document the configurations, customizations, and work I have done to my publishing pipeline. It is also hopeful that others may find this information of value.

2. Acknowledgements

Acknowledge those that came before and on which the following is based. We always stand on the shoulders of giants.

3. Valuable Links

This section provides what I consider to be valuable links so that I can (or you can) quickly access key information relating to this article or technologies. Many of these links are used throughout the article, but I have tried to aggregate the most significant ones here for easy reference without having to scan through the document.

4. Working with Apache Forrest

This section describe various ways I have configured Apache Forrest for my specific needs.

4.1. Integrating Google Analytics

How did I get Google Analytics to work by customizing the template (pelt).

You will need to go to the google analytics site and create an account (if you don't already have one) and then register your site to the account. Once you have done this, you can go to the registered site and under the admin section (of the site/profile), you can generate the script piece that you can then insert into the XSL for forrest to generate into each page. Once you have your script (best not to use the one below because it is specific to my site), I inserted this script just before the closing head tag ("</head>") in the "site-to-xhtml.xsl" file in the <forrest project root>/src/documentation/skins/pelt/xslt/html/site-to-xhmtl.xsl".

<script type="text/javascript">
          
  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', 'UA-30837340-1']);
  _gaq.push(['_setDomainName', 'lancehendrix.com']);
  _gaq.push(['_trackPageview']);
          
  (function() {
  var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
  ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
  var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  })();
          
</script>
            

4.2. Customizing for DocBook

Describe customizations to the processing pipeline (cocoon?) to get it to generate HTML from DocBook (maybe not the best way because we lose metadata, but it works for now) and then use Forrest to integration the generated HTML into the site (basically taking the body of the generated HTML and generating it into the template, which is why we lose information in the head of the generated HTML).

In the <forrest project root>/src/documentation/sitemap.xmap I have the following to enable the processing of the DocBook documents into Forrest.

<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
    <map:components>

        <map:actions>
            <map:action logger="sitemap.action.sourcetype" name="sourcetype"
                src="org.apache.forrest.sourcetype.SourceTypeAction">
                <sourcetype name="docbook">
                    <document-declaration public-id="-//OASIS//DTD DocBook XML V4.5//EN"/>
                </sourcetype>
                <sourcetype name="docbook">
                    <document-declaration public-id="-//OASIS//DTD DocBook XML V4.1.2//EN"/>
                </sourcetype>
            </map:action>
        </map:actions>

        <map:selectors default="parameter">
            <map:selector logger="sitemap.selector.parameter" name="parameter"
                src="org.apache.cocoon.selection.ParameterSelector"/>
        </map:selectors>

        <map:serializers/>
    </map:components>

    <map:pipelines>
        <map:pipeline>
            <map:match pattern="**.xml">
                <map:act type="sourcetype" src="{properties:content.xdocs}{1}.xml">
                    <map:select type="parameter">
                        <map:parameter name="parameter-selector-test" value="{sourcetype}"/>
                        <map:when test="docbook">
                            <map:generate src="{properties:content.xdocs}{../1}.xml"/>
                            <map:transform 
                                src="{properties:resources.stylesheets}/docbook-xsl-1.78.1/html/docbook.xsl">
                            <map:parameter name="use.extensions" value="1"/>
                                <map:parameter name="linenumbering.extension" value="1"/>
                                <map:parameter name="linenumbering.everyNth" value="1"/>
                                <map:parameter name="section.autolabel" value="1"/>
                                <map:parameter name="generate.meta.abstract" value="1"/>
                                <map:parameter name="linenumbering.separator" value="|"/>
                            </map:transform>
                            <map:transform src="{forrest:forrest.stylesheets}/html-to-document.xsl"/>
                            <map:transform type="idgen"/>
                            <map:serialize type="xml-document"/>
                        </map:when>
                    </map:select>
                </map:act>
            </map:match>
        </map:pipeline>

        <map:pipeline>
            <map:match type="regexp" pattern="^.+/$">
                <map:redirect-to uri="index.html"/>
            </map:match>
        </map:pipeline>

        <map:pipeline>
            <map:match pattern="locationmap-project.xml">
                <map:generate src="{properties:content.xdocs}"/>
                <map:transform src="{properties:resources.stylesheets}"/>
                <map:serialize type="xml"/>
            </map:match>
        </map:pipeline>

    </map:pipelines>
</map:sitemap>

4.3. Other Customizations

I am fairly certain I have done other customizations like to headers and such... Need to start from scratch (fresh forrest "seed') and compare to where I am now.