SPIP’s tags: the syntax

The basics

A SPIP tag is placed inside a loop (because we need to know whether we are trying to retrieve data about an article, or a section, etc.). Tag names are generally very simple (but in French!). For each type of standard loop that exists in SPIP, the tags that can be used are listed in the documentation for the corresponding loop.

A tag always starts with the hash symbol (#) and is written in capital letters.

For instance, to display a list of article titles:

<BOUCLE_articles(ARTICLES){id_rubrique}>
<li>#TITRE
</BOUCLE_articles>

Each time the loop is executed, the SPIP tag #TITRE will be replaced by the actual article title:

Title of article 1
Title of article 2
...
Title of last article

At it’s core, it’s pretty much straightforward: we simply indicate the name of the field in the HTML code, and it is replaced by that field’s content which has been retrieved from the database.

Optional code

In practice, a content element is often accompanied by some HTML code which is output only when the requested records actually exist, otherwise the page layout can become erratic.

For example: There is a SPIP tag to define the top title of an article. But many articles may not actually have a top title, since it is not a required field for an article to exist.

Let us complete the above example:

<BOUCLE_articles(ARTICLES){id_rubrique}>
#SURTITRE<br>
#TITRE<br>
</BOUCLE_articles>

which should return a list of articles, displaying the top title and title of each article. But what happens if an article doesn’t have a top title? The result would be: "<li><br>", i.e. a small bullet followed by a blank line.

In fact, we want to generate the code "<br>" only when the article does have a top title.

This syntax resolves the problem:

[optional text before(#TAG) optional text after ]

The tag defining the option is placed between parentheses, and the whole of the conditional text is placed between square brackets. The optional text before and the optional text after are displayed only when the field corresponding to that tag is populated in the database.

Our example then becomes:

<BOUCLE_articles(ARTICLES){id_rubrique}>
[(#SURTITRE)<br>]
#TITRE
</BOUCLE_articles>

This gives the result we need: if a top title exists for this article, it is displayed and followed by <br>; if there is no top title, then the <br> is omitted.

-  warning: this conditional display does not work with dynamic tags (for example #URL_LOGOUT).

-  Since SPIP 4.0, it is possible to use loops in the optional parts before or after a tag. They must be entire in the same part.

Advanced usage

It is possible to nest tags inside each other. For example, if we wish to display the top title only if the article’s subtitle is defined, we can write:

<BOUCLE_articles(ARTICLES){id_rubrique}>
     [[(#LOGO_ARTICLE)<br>](#SURTITRE)<br>]
</BOUCLE_articles>

N.B. It is not possible to insert a loop within the “optional code” part of a tag. If you want to run a loop which depends on a tag having a value or not, it is possible to do so by using <INCLURE()> in the optional code section of a tag.

Distinguishing between tags with the same name

When loops are nested, they frequently have tags of the same name. For example:

<BOUCLE_sections(RUBRIQUES){id_rubrique}>
     <BOUCLE_articles(ARTICLES){id_rubrique}>
         #TITRE
     </BOUCLE_articles>
</BOUCLE_sections>

Here the title displayed will be that of the article, because the innermost loop is the articles loop. If we wish to use a tag belonging to an outer loop, the name of the loop must be stipulated with the following syntax:
#n:TAG where n is the name or number of the loop (including the underscore in the case of a loop with a name). For example:

<BOUCLE_sections(RUBRIQUES){id_rubrique}>
     <BOUCLE_articles(ARTICLES){id_rubrique}>
         #_sections:TITRE : #TITRE
     </BOUCLE_articles>
</BOUCLE_sections>

will display the section title followed by the article title, separated by a colon.

Filtering the result

Often you may want to change an item returned by a tag before displaying it. For example
-  to display a title in capital letters, or
-  to display the day of the week corresponding to a date.

SPIP provides filters to carry out some common operations. Filters are placed after the name of the tag in the following way:

[ option before (#TAG|filter1|filter2|...|filterN) option after ]

The syntax specifies that the successive filters be appended to the tag name, all enclosed between the parentheses, and each filter prefixed by a vertical bar "|" or “pipe”.

Note. In fact, filters are really PHP functions. Therefore, you can use PHP functions directly (provided these functions have only one variable as argument), on top of the functions provided by SPIP.

-  Warning: filters can not be applied to dynamic tags

Here some filters provided by SPIP:

-  majuscules converts the text to uppercase (note that unlike the similar function in PHP, this filter works with accented letters); example:

[(#TITRE|majuscules)]

-  justifier, applies full justification to text (i.e. <p align=justify>); example:

[(#TEXTE|justifier)]

See this article for a full documentation of SPIP’s filters.

Bypassing the SPIP’s typographical corrections

SPIP applies a typographical processing to all the texts retrieved from the database, such as analysing the layout shortcuts. For example, ~ is converted into a non-breaking space.

In some instances you may need to bypass this processing in order to retrieve the raw text as it is stored in the database. To achieve this, you simply append an asterisk (*) to the SPIP tag, thus:

[ option before (#TAG*|filter1|filter2|...|filterN) option after ]

(see the article about #TAG* and #TAG**)

Tags with parameters

Some tags [1] are used with parameters. The parameter list is written between curly brackets «{» and «}», using commas to separate the parameter values. For example: #ENV{lang,fr}.

A parameter may be a constant or another SPIP tag [2]. However, only simple tags (without optional text or filters) may be used as parameters.