SPIP

[ar] [ast] [bg] [br] [ca] [co] [cpf] [cs] [da] [de] [en] [eo] [es] [eu] [fa] [fon] [fr] [gl] [id] [it] [ja] [lb] [nl] [oc] [pl] [pt] [ro] [ru] [sk] [sv] [tr] [uk] [vi] [zh] Espace de traduction

Download

How to <INCLUDE> other templates

April 2004 — updated on : December 2010

All the versions of this article:


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.

Typical usages for such included code in such files called from numerous templates are:
— header declarations for HTML headers (JavaScript calls, style sheets...),
— navigation elements common to most of a site’s pages (at the to of a screen, in the left column...),
— the top banner section (logo, liens to the site’s credits, contact page, search tool...),
— a page footer...

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.

From SPIP 1.4 onwards, 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:

<INCLURE{fond=filename, parameters ...}>

The “filename” argument 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. 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:

Other parameters

The INCLURE / INCLUDE syntax allows you to pass any other parameters that you want to down to the included code, where they can be accessed just like normal environment variables.

As an example, the templates provided in the current default squelettes-dist directory include a call to the included code for the page footer:

This permits the "inc-pied" code to access the #ENV{skel} value, which it then displays as the name of the template in the page footer. Refer to the #ENV article for more information on how to access environment variables and their values.

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 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:

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

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:

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].

In a multilingual context

If SPIP multilinguism has been activated, since SPIP 1.7, SPIP 1.7.2 , 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 en statique

SPIP 1.9.1 introduced another method of inclusion with #INCLURE.

The <INCLURE{fond=..}> syntax causes the inclusion on pages each time a they are visited by a web site user, regardless of whether a page has already been cached or not.

With the new [(#INCLURE{fond=...})] tag, the inclusion is made when the template is calculated, and its results are stored in the calling page. With this system, you can no longer specify a reduced expiry time (#CACHE{}) for an included template; on the other hand, it now becomes possible to apply filters to the included template: [(#INCLURE{fond=letter}|version_texte)].

<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.

<INCLURE> and {doublons}

There is also a loop criteria 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.

Since SPIP 2.0, it has been possible to overcome this problem. 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.

Footnotes

[1Remember that the #CACHE variable defines the frequency of the cache update. This can be a convenient way of separating resource-heavy parts of the site that rarely need regenerating from some dynamic elements requiring frequent updating (such as syndication, for example).


Show the template of this page Site powered by SPIP | Translation area | Private area