How to <INCLUDE> other templates

[SPIP 1.4] When several templates share the same text items or loops you may want to extract these elements from their original pages and place them in separate files from where they can be called into other templates as needed. This way, the common code is stored in one place only, so further changes affecting several templates can be made in one go.

Those of you familiar with PHP will be aware of the include function, whose principle is similar to what is dealt with here.

In SPIP, a template can be fetched from a another template by the <INCLUDE> tag — <INCLURE> can also be used (the two are synonyms). The general syntax is as follows:

<INCLUDE(file.php3){parameter}...>

The “file.php3” is the name of the file you want to include into the page. Here’s an example: if the same information is displayed at the bottom of all your web pages, you can write the HTML code of this “footer” into one “footer.html” file, a template which will be fetched by the “footer.php3” page (following the basic notion of calling templates through the combination of a pair of files). Then all you need to do is add the following line in the right place in each of the templates in which you want the footer displayed:

The way to include a template can depend on the context. Let’s take the example of a “hierarchy” template which will display the path from the site root to a section; this page would be fetched by a URL matching this pattern: “hierarchy.php3?id_rubrique=xxx”.

In the templates where you mean to display the hierarchy from the current section you have to set the parameter to {id_rubrique}. If necessary you first create the proper loop to fetch the number of the section, and then you place the following code inside this loop:

Note: in this case the hierarchy.html template will certainly begin with a RUBRIQUES loop (section) including the {id_rubrique}...criteria.

Let’s imagine you want to fetch not the hierarchy dependent on a “variable” section (according to the context, such as the URL-included parameter) but the hierarchy dependent on a section whose number you already know. To do this you can set the parameter value in this way:

N.B. It is possible to set several parameters in the <INCLURE> tag. However this is very seldom necessary in practice. It’s best to avoid adding superfluous parameters which will make the cache less effective and slow down your site.

N.B. As the included file is itself a template it can be given its own $delais value [1]. This can be a convenient way of separating heavy parts of the site that rarely need regenerating from some dynamic elements requiring frequent updating (such as syndication, for example).

In a multilingual context

SPIP 1.7.1 makes it possible to define the language environment for the included, using the {lang} parameter.

-  If no language parameter is used, i.e. <INCLUDE(footer.php3)>, the included template is called using the site’s default language.

-  <INCLUDE(footer.php3){lang=es}> calls the template in Spanish. Replace “es” with the ISO code for the desired language, en for English, fr for French, vi for Vietnamese, etc. (see Internationalizing Templates)

-  And <INCLUDE(footer.php3){lang}> calls the template in the current language. Note that this makes it possible to use multilingual strings in included templates (see Internationalizing Templates).

Included templates are susceptible to the same language selection technique as “top-level” templates. In other words, included templates (here footer.html) can be selected according to a chosen language (footer.es.html) in the same way as other templates. Once again, see “Internationalizing Templates” for more details.