Chapter 5: Using Output Modes

The modes.php file lives in the base folder of your template set and is an INI-formatted file, although it is recommended you edit it via the SiteTemplate "Edit Properties" form instead of modifying the file directly. This file contains INI "blocks" that each describe an output mode. You will find an example modes.php file in the default template set that comes pre-installed in new installations of Sitellite. This example contains the following:

; <?php /*

[html]

content_type    = text/html
filter 1        = "body: saf.Misc.Search"
;filter 2       = "body: siteglossary.Terms"

; */ ?>

Here is a simple content filter example function. You can try this out by saving it to a file named inc/app/myapp/lib/Example.php.

<?php

/**
 * This is an example filter that inserts a trademark symbol next to
 * any occurrence of the name "Sitellite".
 *
 * @access public
 * @param string
 * @return string
 * @package Myapp
 */
function myapp_example_content_filter ($body) {
	return str_replace (
		'Sitellite',
		'Sitellite<sup>TM</sup>',
		$body
	);
}

?>

To activate this filter for the body field, add the following line under the [html] block of your modes.php file:

filter 3 = "body: myapp.Example"

First, we'll need to create the default template for our new output mode. Save the following DocBook markup to a file named docbook.default.tpl in your template set. In SiteTemplate, you can do this by entering "docbook" in the Output Mode field, and "default" in the Template Name field.

<xt:tpl version="1.0"><xt:xmldecl version="1.0" encoding="UTF-8" />
<xt:doctype
	root="book"
	access="public"
	name="-//OASIS//DTD DocBook XML V4.3//EN"
	uri="http://www.docbook.org/xml/4.3/docbookx.dtd"
/>
<article>
	<articleinfo>
		<title xt:content="head_title">Title</title>
		<abstract>
			<para xt:content="description">Description</para>
		</abstract>
	</articleinfo>
	<section>
		<title xt:content="title">Title</title>
		<para xt:replace="body">Body</para>
	</section>
</article>
</xt:tpl>

Next, we'll create an output filter to translate the HTML in the body field. Save this to the file inc/app/myapp/lib/DocBook.php

<?php

loader_import ('saf.HTML.Messy');

/**
 * Converts various HTML tags to their DocBook equivalents.  Please note that
 * this list is far from complete.
 *
 * @access public
 * @param string
 * @return string
 * @package Myapp
 */
function myapp_docbook_content_filter ($body) {
	$m = new Messy;
	$m->transform = array (
		'p' => 'para',
		'b' => 'strong',
		'i' => 'emphasis',
		'em' => 'emphasis',
		'ul' => 'itemizedlist',
		'li' => 'listitem',
		'h1' => 'title',
		'h2' => 'title',
		'h3' => 'title',
		'h4' => 'title',
		'h5' => 'title',
		'h6' => 'title',
	);
	$body = $m->clean ($body);
	$body = strip_tags ($body, '<para><strong><emphasis><itemizedlist><listitem><title>');
	return $body;
}

?>

Finally, we'll add the following new block to the modes.php file:

[docbook]

content_type    = "application/docbook+xml"
filter 1        = "body: myapp.DocBook"

Our new output mode is now ready to be viewed. You can try it out by going to the following URL in your own Sitellite installation:

http://www.example.com/index/mode.docbook

The installation process for HTMLDoc itself should be straight-forward on most Unix systems, including Mac OS X:

tar -zxf htmldoc.tar.gz
cd htmldoc
./configure
make
sudo make install

Now for the fun part. Creating a PDF output mode is as simple as creating the necessary pdf.default.tpl template (you can just copy your html.default.tpl for testing), and adding the following INI block to your modes.php file:

[pdf]

content_type = application/pdf
filter 1 = "final: ext.htmldoc"

You should now be able to view a PDF of your home page at:

http://www.example.com/index/mode.pdf

If you do run into problems, make sure that your command line htmldoc binary is somewhere in PHP's PATH environment variable. You will find useful information on the HTMLDoc web site about customizing the HTML of your template to control the PDF output. Note that where the HTMLDoc documentation says to put comments, use xt:note tags instead. For example:

<xt:note>HEADER LEFT "Site Name"</xt:note>