Layouts
=======

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

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

  >>> layout.slots
  (u'title', u'content')

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

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

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

Verify existance of render-method:

  >>> layout.render
  <bound method Layout.render ...>

  
Layout directories
------------------

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

  >>> from repoze.bfg.layouts.layout import LayoutDirectory
  >>> directory = LayoutDirectory(os.path.dirname(filename))

Layouts are given names based on their relative path.

  >>> directory['example']
  <Layout filename=".../tests/layouts/example.html">

If the layout 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 layouts
------------------

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

  >>> from repoze.bfg.layouts.layout import get_layout

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

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

  >>> context = request = object()
  >>> get_layout(context, request, 'example')
  <Layout filename=".../tests/layouts/example.html">
