overlay template chains

The $overlay{} directive defines a dependency chain of templates,
super-imposing a template on top of another.
This functionality is often called template inheritance —
a term that may however be a little misleading given the very
specific connotations from object-oriented programming.
Nonetheless, a great feature of evoque overlays is that they are in many
ways similar in behaviour to the inheritance paradigm of object-oriented
programming, as for example the nice feature that an evoque template does
not care or even know about whether it is being used as a base template
to an overlay.

Layered positive and negative spaces

A simple way to think of an overlay is as a graphic, with layers that may be
transparent, and having positive and negative space. The positive space are
the sub-template objects on the page, i.e. the top-level
begin/end blocks defined by the template.
The negative space is everything else, i.e. all markup that is not
contained in any top-level begin/end block.
An overlay template may declare that it overlays the
space="positive"
or the space="negative" of the overlaid template:

  • A positive-space overlay is one that may override any objects in
    the positive-space, i.e. top-level sub-template objects.
    Any markup in the negative-space of such a template is ignored.
    By default, overlays are positive-space.
  • A negative-space overlay is required to supply the
    negative-space for the template. That negative space may evoque
    sub-templates from the overlay chain below as if they were
    defined locally. Any sub-template defined below that is not
    evoque’d from the supplied negative-space will not be rendered.
    Naturally, such a template may of course also override any
    top-level sub-templates that make up its positive space.

Examples

The pages below offer some overlay scenario examples.
These examples are live, in the sense that the
templates and generated output are included automatically
from the Evoque unit tests,
with zero touch-up or modification.

Overlay directive parameters

The first 3 parameters are the same as for the
evoque directive
plus an additional space keyword
that as we have seen may be
either positive or negative:

$overlay{ name, src, collection, space }

name, src, collection
: behave in same way as for $evoque{} directive

space : “positive” : either(“positive”, “negative”)

Additional notes about overlays

  • An overlay directive declares that this template overlays
    the specified template, in either a positive-space or in a negative-space
    mode.
  • Only one overlay directive per template is allowed.
  • Any template may be overlaid, and overlaid templates are just normal
    templates requiring no modifications.
  • An overlaid template may itself overlay another template.
  • In an overlay, overlaid templates may be addressed with multiple
    leading # characters, to indicate deeper levels into the
    overlay chain, i.e.:

    • #label tells to start lookup from self
    • ##label tells to start lookup from one level below
    • ###label tells to start lookup from two levels below, etc.
    • specified_name#label continues to work as in any other template, of
      course, irrespective of whether the template given by specified_name
      participates in the overlay chain or not.