phpDocumentor 1.1 Templates

Joshua Eichorn <jeichorn@phpdoc.org>
Gregory Beaver <cellog@sourceforge.com>

Primary phpDocumentor Documentation

Note: if this howto looks bad, get a browser that supports css

phpDocumentor Template HOWTO written by Joshua Eichorn, Gregory Beaver>
Copyright © 2002, Joshua Eichorn, Gregory Beaver

Table of Contents

Introduction
Basics
Template Includes
Template Loops
Template Variables
Php Api of the Template Class

Introduction

NOTE: This howto is no longer up-to-date. However, it gives a general idea of how to write for the template engine of the default HTML Converter. phpDocumentor is migrating towards the use of Smarty templates, and version 1.2 will probably stop using the Template class and these file formats. The biggest difference between Smarty and this template is that Smarty is very extensible and fast. Check out the templates for HTMLSmartyConverter for examples.

The default HTML converter in phpDocumentor uses a simple template engine, it support, Includes, Loops, and Variable Replacement. Some time after phpDocumentor 1.0 is released the template engine will be updated to a newer codebase that is currently half done. This will provide conditionals and more option for showing/hiding non registered template variables.

The rest of this document walks you through the basics of using the template engine, but if you just want to change how the output looks you don't need to know that much. First copy an exisiting template, then change the html code in it so things looks how you want. Just make sure not to change any of the template specific portions of the files.


Basics

The operation of the template engine is pretty simple, you need a template file, like the example in the box below.

A sample template file {sample_var}

Then you instantiate a template object, telling the directory to perform includes from and the template to parse. Next you register any variables that you have on the template, using the register method. Finally you can display the output using the ret method $template = new Template("/template/dir/","test.html"); $template->register("sample_var","Template Ouput Value"); echo $template->ret(); Thats it, you have output from the template engine.


Template Includes

Includes are parsed in the template constructor. This means that requires happen before any loop processing or variable replacement. The syntax for an include is: <include filename="file_to_include"/> Files are included from the path specified in the class constrcutor. Make sure to keep the tag lower case and follow the syntax of the example exactly, the engine isn't to forgiving on syntax.


Template Loops

You define loops in the template using the loop tag. And then put the variables to be looped inside the pair of tags. Like in includes were picky about syntax make sure to keep the tags lowercase

<loop name="example"> {name} {name2} </loop name="example">

You then register an array to the name specified in the loop. The array you build is multi dimensional with each row containing an associative array with a key => value pair with each variable to be replaced. An example array is shown below.

$data = array( array("name" => "val1","name2" => "val4"), array("name" => "val2","name2" => "val5"), array("name" => "val3","name2" => "val6") }; $template->register("example",$data);


Template Variables

Template variables are the simplest part of the template. Its just the template variables name inside brackets. {variable_name} You then register some text to the variable and it will be replace on output. {variable} $template->register("variable","some value");


Php Api of the Template Class

Everything is private besides, the class Constructor, the register method and the ret method. View the API Docs