| Previous | Next | |
| Writing templates for the CHMdefault Converter | Writing templates for the XMLDocBook Converter |
This documentation deals only with adding a new template to the HTMLframes Converter. To learn how to use phpDocumentor, read the phpDocumentor Guide to Creating Fantastic Documentation. To learn how to write a new Converter, read Converter Manual
The HTML:frames converter uses all of the values from the generic Converter (see Converter Default Template Variables), and adds a few more.
All templates have the standard smarty template variables available to them, as well as these:
{$subdir } string - the combination of "../" that will lead to the base output directory, used for linking to other generated documentation.
{$packageindex} array - a list of all the packages and their index pages in the format array('link' => link to the index page, 'title' => package name)
When source code is generated via the @filesource tag, the output is passed into these templates variables:
{$source} string - the fully formatted source code, use as is
{$package} string - the package name of the source file
{$subpackage} string - the subpackage name of the source file
{$name} string - the name of the source file file.ext
{$source_loc} string - the relative path to the file, used for include() statements
{$docs} string - a link to the documentation for this file
When an example file is specified via the @example tag, the output is passed into these templates variables:
{$source} string - the fully formatted source code, use as is
{$file} string - the full path to the file
{$title} string - the title of this example, from the @example tag
The HTML:frames Converter places a table of contents in the left frame. This table of contents contains links to class trees, alphabetical indexes, tutorials, and elements organized by category (class/procedural code).
Each left_frame.tpl consists of one package's documentation. Basic template variables passed to left_frame.tpl include:
{$info} array - the table of contents, see The {$info} template variable for contents
{$package} string - package this table of contents documents
{$hastutorials} boolean - true if this package has external tutorials (see phpDocumentor Tutorials)
{$hastodos} boolean - true if there are any @todo tags in this package
{$todolink} string - file.html name of the todo list.
{$classtreepage} string - name of the file containing class trees, minus .html
{$elementindex} string - name of the file containing the alphabetical index for this package, minus .html
{$packagedoc} string|false - link to package-level documentation, or false if there is none
The {$info} variable is an array of arrays, each indexed by subpackage. Even packages with no explicit @subpackage tags have a subpackage named '' (empty string). Elements in the main package can be detected using the smarty code: {section name=p loop=$info}{if $info[p].subpackage == ''}...
The {$info} variable contains these sub-variables (assuming that {section name=p loop=$info} was used):
{$info[p].package} string - package name
{$info[p].subpackage} string - subpackage name
{$info[p].packagedoc} string - link to old format .html-based package-level documentation (deprecated)
{$info[p].packagetutorial} string - link to new package-level documentation, or subpackage-level documentation for subpackages
{$info[p].packagetutorialnoa} string - link to new package-level documentation, or subpackage-level documentation for subpackages, without enclosing <a href="link to docs"> HTML tag. Use this to do special link handling (opening a new window, opening in the _right frame, etc.)
{$info[p].packagetutorialtitle} string - title of package-level documentation
{$info[p].files}/{$info[p].classes}/{$info[p].functions} array - links to documentation array('link' => html link, 'title' => name of element)
{$info[p].tutorials} string - Formatted tutorial table of contents, see Tutorial table of contents formatting - tutorial_tree.tpl
The tutorial table of contents is formatted using the recursive tutorial_tree.tpl template. This template has only a few variables:
{$name} string - abstract name of the tutorial (tutorial.pkg becomes tutorialpkg)
{$parent} string|false - {$name} from parent tutorial, or false if no parent tutorial
{$main.title} string - the title of the tutorial. Use as {main.title|striptags}
{$main.link} string - link to the tutorial's documentation
{$haskids} boolean - true if this tutorial has sub-tutorials
{$kids} string - fully formatted list of child tutorials
{$subtree} boolean - true if this is a sub-tutorial tree. Use to modify formatting for sub-tutorial listings.
The tutorial_tree.tpl file should represent the hierarchy of tutorials through some form of a nested html tag, such as a nested list (like the default converter), or a nested DHTML menu (like the phpedit or earthli templates).
Class trees are a visual representation of Class inheritance to help facilitate understanding of how a project is organized. Class trees have only a few template variables:
{$package} string - the package that base classes are found in
{$classtrees} array - a pre-formatted list of class trees, organized by base class. Format is: array('class' => name of class, 'classtree' => fully formatted class tree)
The top frame is used to display links to the highest level of documentation, the package table of contents, and the project-wide README/CHANGELOG/FAQ/NEWS/INSTALL files.
{$packages} array - A listing of all packages documented, in format array('link' => name of the left_frame.tpl-generated package table of contents, 'title' => name of the package)
{$ric} array - all of the README/INSTALL/FAQ/NEWS/CHANGELOG files found, in format array('file' => name of the generated output, 'name' => displayable name of the parsed file)
phpDocumentor's generated alphabetical element indexes are organized into an index of all elements in all packages (elementindex.tpl), and indexes of the elements in each individual package (pkgelementindex.tpl). Their variables are the same, except for the addition of the {$package} variable in pkgelementindex.tpl. Here are the template variables:
{$index} array - the index items, see {$index} contents
{$letters} array - a listing of each letter heading that should be used in the index
The {$index} variable is an array of index listings organized by their first letter. All documented elements whose name begins with the letter A will be grouped into the sub-array 'a' => array(listing,listing,...). The listing is organized as follows:
{$index[xxx].name} string - name of the documented element
{$index[xxx].title} string - One of Variable, Global, Method, Function, Constant, Page, Include
{$index[xxx].link} string - hyperlink to the element's documentation, or the file included for include statements
{$index[xxx].listing} string - A fully-formatted index listing in English.
These specialized templates will only be used in certain cases.
ric.tpl - This template is only used when files such as README, INSTALL, or CHANGELOG are detected in the base parse directory.
todolist.tpl - This template is only used when a @todo tag is used in documentation
errors.tpl - This template is always generated, but only contains content when there are parsing syntax errors or logical conflicts in the parsed documentation
This is a very simple template.
{$name} string - name of the file (README, for example)
{$contents} string - contents of the file, ready for display (no modification needed)
This is also a very simple template, and requires only a {section} tag to process the input.
{$todos} array - Format: array(packagename => array('link' => string element containing @todo tag, 'todos' => array(todo item 1, todo item 2,...)),...)
This file is a tool used to help find mistakes in your own documentation, and greatly simplifies determining whether there is a bug in your documentation or in phpDocumentor itself.
The structure of the errors array passed to errors.tpl is somewhat complex to learn, but easy to use once learned. Every error or warning is grouped by the file that triggered it. In the case of post-parsing errors, they are grouped into the pseudo-file "Post-parsing". Within each file, warnings are grouped separately from errors. Hence, the structure looks something like:
{$all} array - This is the structure listed above
{$files} array - a listing of all the files, useful for making a table of contents
{$title} string - this is hard-coded in English. Override by simple using {assign var="title" value="whatever you want"} before including header.tpl
For the basic PHP elements, define, include, function, global variable, class, and so on (see Documentable PHP Elements), there are very few differences between the templates packaged with the HTMLframesConverter and the basic Converter.
The only additional variable is:
{$var_dest} string - html anchor used to pinpoint this class variable's documentation in the class file's documentation. Use as in:
The only additional variable is:
{$method_dest} string - html anchor used to pinpoint this class method's documentation in the class file's documentation. Use as in:
The only additional variable is:
{$function_dest} string - html anchor used to pinpoint this function's documentation in the procedural file's documentation. Use as in:
The only additional variable is:
{$define_link} string - html anchor used to pinpoint this define statement's documentation in the procedural file's documentation. Use as in:
The only additional variable is:
{$global_link} string - html anchor used to pinpoint this global variable's documentation in the procedural file's documentation. Use as in:
The only additional variable is:
{$include_file} string - html anchor used to pinpoint this include statement's documentation in the procedural file's documentation. Use as in:
| Previous | Next | |
| Writing templates for the CHMdefault Converter | Writing templates for the XMLDocBook Converter |
Documentation generated on Mon, 05 Dec 2011 21:29:59 -0600 by phpDocumentor 1.4.4