Templates
=========

.. important::

   This document is a design for an upcoming refactoring. It does not reflect
   the current state of affairs.

This document describes the technical details for the use of Templates; where a
Template represents a collection of transformations which, when executed,
produce a meaningful representation of the User's source code.

Examples of output generated by a *Template* can be, but is not limited to:

* A HTML website
* A single PDF
* An XML file containing the errors found in the checkstyle format
* or a combination of the above

Scope
-----

- The actual transformation process is not described in this document, this is
  considered to be an implementation detail of the Transformer and individual
  Writers.

Basic Usage
-----------

The simplest example of using a template is by defining it in a configuration
file and pass that in the constructor using a Template Loader:

.. code-block:: php

   use phpDocumentor\Transformer\Template;

   $template = new Template(
       Template\Loader\Xml('template.xml')
   );

   // ... initialize $transformer ...
   $transformer->execute($template);

It is also possible to assemble your template using plain PHP code. You would
need to create and add each individual transformation. A more detailed
examination of the different components is in the next chapters.

.. code-block:: php

   use phpDocumentor\Transformer\Template;
   use phpDocumentor\Transformer\Transformation;
   use phpDocumentor\Transformer\Writer\Factory;

   // ... initialize $transformer ...

   $writer_factory = new Factory($transformer);
   $xsl_writer = $writer_factory->get('Xsl');

   $template = new Template();
   $template->add(new Transformation($xsl_writer, $artefact, $source));
   $template->add(new Transformation($xsl_writer, $artefact, $source, $query));

   $transformer->execute($template);

Transformations
---------------

A transformation enables you to generate an artefact. An artefact represents
one or more files on your file system that have meaning for a user; examples
can be: HTML files, PDFs, search indexes, graphs, etc.

Each transformation may have the following information:

* **Writer**, the abbreviated name for the class responsible for reading the
  AST and generating the artefact, see `Writers`_
* **Artefact**, The destination location for the generated file(s) relative to the
  target directory
* **Source**, an optional argument providing the Writer with a source file. The
  meaning of this parameter may differ per Writer.
  Example: the XSL writer uses this item to determine which template to use
* **Query**, an optional argument which allows transformations to restrict the
  scope of a Writer. Example: the XSL writer may be given a xpath expression
  if only a piece of the AST is needed for a template.
* **Parameters**, an optional associative array containing additional settings that
  may influence the operation of a writer.

Writers
~~~~~~~

phpDocumentor supports a number of writers:

*File operations*

.. toctree::
   :maxdepth: 1

   templates/writers/fileio

*HTML Rendering*

.. toctree::
   :maxdepth: 1

   templates/writers/xsl
   templates/writers/twig
   templates/writers/sourcecode
   templates/writers/search

*XML Rendering*

.. toctree::
   :maxdepth: 1

   templates/writers/checkstyle

*Graph rendering*

.. toctree::
   :maxdepth: 1

   templates/writers/graph
