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
:
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 byspecified_name
participates in the overlay chain or not.