How to <INCLUDE> other templates

The inclusion syntax

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

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

<INCLURE{fond=filename, param}>
<INCLURE{fond=filename, param1,param2}>
<INCLURE{fond=filename, param1,param2}{param3=#LISTE{valA,valB}}>

The “filename” argument is the name of the file you want to include in 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. 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:

<INCLURE{fond=footer}>

Context dependent inclusions

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

In the templates where you intend to display the hierarchy from the current section you will then need 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:

<INCLURE{fond=hierarchie, id_rubrique}>

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

Let’s imagine that you don’t want to fetch 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:

<INCLURE{fond=hierarchy, id_rubrique=5}>

N.B. It is possible to specify 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 #CACHE value [1].

Passing on all current context

The env parameter is used to pass the compilation context of the current template to the included one.

<INCLURE{fond=filename, env}>

In a multilingual context

If SPIP multilinguism has been activated, it has been possible to define the language environment for the included file using the {lang} parameter.

-  If no language parameter is used, i.e. code><INCLURE{fond=footer}>, the included template is called using the site’s default language.

-  <INCLURE{fond=footer, 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)

-  <INCLURE{fond=footer, 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.

#INCLURE in static

With this tag, it becomes possible to apply filters to the included template:

[(#INCLURE{fond=letter, env}|version_texte)]

In addition, the inclusion is performed during the calculation of the template, and its result is stored in the cache of the calling page. With this system, we can no longer manage a reduced lifetime (#CACHE{}) for an included template.

Warning : the result of the inclusion being stored in cache, so the #INCLURE must not contain dynamic elements, in particular no #FORMULAIRE_XYZ tags.

<INCLURE{fond=..}> and [(#INCLURE{fond=..})] therefore have different methods of operation:
— with <INCLURE{fond=..}>, each template includes an independent cache;
— with [(#INCLURE{fond=..})], the main calling page contains, in the cache, all of the generated code, and the included files do not have their own separate caches.

Note : By default, 3 environment variables are automatically passed to the inclusion evaluation:
lang, date and date_redac. These additions to the environment can be avoided by using the star: #INCLURE*. It then becomes possible to use conditional criteria on these variables in the included template.

<INCLURE> and {doublons}

There is also a loop criterion called {doublons}. Because if we use an <INCLURE> within a template file, the memorised duplicates are not automatically transmitted down to the included template code.
To do so, just add the {doublons}> parameter to your call of the template file to be included. For example <INCLURE{fond=mypage, doublons}>.

Note, however, that the duplicates selected in the included template will not "feed back" into the calling template file.

<INCLURE> and AJAX

SPIP 2.0 introduces the possibility of easily using AJAX technology, which allows you to click on a link and thereby only refresh a particular section of the HTML page which would change if you redisplayed the entire page but with different new parameters. For more details on this functionality, please refer to the detailed article.

#INCLURE a file which is not a template

The #INCLURE tag can also be used to include a file that is not a template: to do this, simply indicate the file included directly as the first argument, omitting the "fond=" that is used to include templates. The file is then read and its content is returned in the calling context without being interpreted by SPIP.

Example of uses in different SPIP files or plug-ins:
-  in sedna.js.html : [(#INCLURE{javascript/sedna.js}|...]
-  in adminer.html : [<style type="text/css">(#INCLURE{adminer.css}|compacte{css})</style>]
-  in portfolio_document.html : [(#INCLURE{javascript/medias_edit.js}|compacte{js})]
-  in gis.js.html : [(#INCLURE{lib/leaflet/dist/leaflet-src.js})]

Most of these uses are for javascript or CSS files, but it is possible to include other file types:
-  in favicon.ico.html : [(#INCLURE{favicon.ico}|sinon{#INCLURE{spip.ico}})]

See also

• `ajax` for inclusions
• The template debugging tools and in particular the "var_mode=include" call

On programmer.spip.net

• Passing parameters
• The #ENV environment