Template layers

DEVELOPER DOCUMENTATION > TEMPLATE LAYERS

Templates

Each theme is organized in templates (i.e. any of the php files in the theme's directory ending in .template.php). Each template (in other words each file) can contain three kind of functions:

• so called "sub_template"s (or main templates),
• "normal"⁽¹⁾ functions, that means functions containing blocks of template that are called from sub-templates (or layers),
• one or more (usually more) layers.

Sub templates are the "central" part of the "current" template, for example in Post.template.php, the main template is the one rendering the textarea where the message is written, while in Display.template.php the main template is the list of messages.

Normal functions are useful functions that may be called from any part of the template in order to render a specific piece of html, for example in GenericMessages.template.php the template_build_poster_div is a function that creates the poster area in Display.template.php or in PersonalMessage.template.php.

Layers are a slightly more complex beast. Layers are used to define "accessory" template elements that should be placed before (i.e. above) and/or after (i.e. below) the main template. They can be used for example by addons to "inject" specific pieces of template in certain positions.

Layers are ordered symmetrically starting from the central main/sub template as explained in the following picture:

ElkArte gives addons an easy way to manipulate the order of the layers: the Template_Layers class. This class provides a series of functions to add and remove layers. For convention all the actions of this class are relative to the above series of layers, but may affect the below too, so for example if we use:

$template_layers->addBefore('layer_1', my_layer');

the result will be the following:

While if we use:

$template_layers->addAfter(layer_1', my_layer');

we will obtain the following order of layers:

Layers above and below are rendered if the corresponding function exists, so if in the template we have: template_my_layer_above, but we don't have template_my_layer_below, only the above one will be created. It's true also the other way around: if only the function template_my_layer_below is present, only this one will be used. This implies that if we want to add a piece of template only below the main one, we have to use the opposite function in order to obtain the "correct" order.

For example, if we want to add only my_layer below and, in the above picture, after layer_2 below we have to use:

$template_layers->addBefore(layer_2', my_layer');

In order to obtain the following:

---

(1)At the moment I can't think of anything more appropriate