Templates
=======

Dynamic HTML templates may be used as "templates" by registering the
directory where they're located as a template directory. A template is a
class that provides higher-layer dynamic template support.

  >>> filename = os.path.join(path, 'templates', 'example.html')
  
  >>> from repoze.bfg.htmlpage.template import HTMLPage
  >>> htmlpage = HTMLPage(filename)
  >>> repr(htmlpage)
  '<HTMLPage filename=".../tests/templates/example.html">'
  
The template provides information on dynamic slots and attributes:

  >>> htmlpage.slots
  ('title', 'content')

  >>> htmlpage.attributes
  ('meta-description', 'section, ltr', 'meta-keywords', 'meta-generator')

To serve up resource referenced by the template, we can use the
``get_resource`` method.

  >>> resource = htmlpage.get_resource('example.css')
  >>> print resource.read()
  h1 {
    text-decoration: blink;
  }

Verify existance of render-method:

  >>> htmlpage.render
  <bound method HTMLPage.render ...>

  
Template directories
------------------

In a real-world application, we'll often want to register a directory
where we put several templates in.

  >>> from repoze.bfg.htmlpage.template import TemplateDirectory
  >>> directory = TemplateDirectory(os.path.dirname(filename))

Templates are given names based on their relative path.

  >>> directory['example']
  <HTMLPage filename=".../tests/templates/example.html">

If the template is not found (maybe removed from the directory), a key
error is raised.
  
  >>> directory['non-existing']
  Traceback (most recent call last):
   ...
  KeyError: 'non-existing'
  
  
Looking up templates
------------------

A utility method helps locating a template when several template directories are registered.

  >>> from repoze.bfg.htmlpage.template import get_htmlpage

Before we can use the registry, we must register the template directory
as an adapter on (context, request):

  >>> from repoze.bfg.htmlpage.interfaces import ITemplateDirectory
  >>> component.provideAdapter(
  ...    directory, (interface.Interface, interface.Interface),
  ...    ITemplateDirectory)
  
The registry provides only the ``get`` method:

  >>> context = request = object()
  >>> get_htmlpage(context, request, 'example')
  <HTMLPage filename=".../tests/templates/example.html">
