Use of Cheetah Templates

This project makes use of Cheetah templates in order to output the HTML formatted reports. However, it does not install user-editable templates. The template files (.tmpl) exist in source control, and are compiled at build-time to python (.py) files.

The build-time compilation is achieved with a custom build_py distutils class, which can be found in setup.py

If you are interested in contributing to this project or working on a fork, you will need to know how the templates are applied during run-time.

Prior to being output, a report is a nested collection of Change objects. These changes represent the information that has been collected from comparing two classes, jars, or distributions. A report is a special subclass of change that has the side-effect of creating output on the file-system when it has completed its tests.

All of the cheetah templates reside as modules within the javatools.cheetah package. The template names are used to indicate what change class they should be used to represent. For example, distdiff_DistContentChange.tmpl is intended to catch instances of the distdiff.DistContentChange class. Objects are paired to their templates at run-time following python's built-in method-resolution-order. So if an individual change class doesn't have a template specific to that class, the inheritance of the change class is followed until a template can be found.

Once a template is running, it has access to the change instance it was called with as the $change variable, the command-line option data as $options, and a function $render_change which can be called with a sub-change to nest to another change template. For example, see the change_Change.tmpl template which is the parent class catch-all for changes.

Most templates will want to #extend change_Change and override the #block details in order to display their complex change data. If you want to be able to collate or otherwise modify the output of child changes, override the #block collect to do so.

Templates are discovered by package introspection at run-time. There is no need to register them with a master list, just create them and they'll be picked up.