evoque

The $overlay{} directive defines a dependency chain of templates, super-imposing a template on top of another. Other template systems often call this functionality template inheritance -- a term that may however be a little misleading given the very specific connotations from object-oriented programming, and it is best to not add to any object-disorientation. 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 are included directly from the Evoque unit tests, and the generated output is included into these pages automatically and with zero touch-up or modification.

Overlay directive parameters

The parameters are the same as for the evoque directive, but with an additional space keyword (inserted at the second position, after the name that is the only one required) that as we have seen may be either positive or 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.