SPIP’s tags: the syntax

Each type of loop selects elements from the SPIP database: articles, sections, news items, etc. Each of these elements contains particular items (fields): a title, a date, a main text, etc. When using a loop in a template, we need to be able place these items in the HTML code to give the layout we wish.

That is what SPIP tags are for.

The basics

A SPIP tag is placed inside a loop (because we need to know if we want to retrieve an article, a section, etc.). Tag names are generally very simple (but in French!). For each type of loop tags that can be used are listed in the documentation of 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:

<li>Title of article 1 <li>Title of article 2 ... <li>Title of last article

It is pretty much straightforward: we simply indicate the name of the field in the HTML code, and it is replaced by its content, which is returned from the database.

Optional code

In practice, a content element is often accompanied by a HTML code which is displayed only if this element exists, otherwise the page layout becomes erratic.

For example: There is a SPIP tag to define the top title of an article. But many articles do not have a top title.

Let us complete the above example:

<BOUCLE_articles(ARTICLES){id_rubrique}> <li>#SURTITRE<br>#TITRE </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 if the article has 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 if an item corresponding to this tag exists in the database.

Our example becomes:

<BOUCLE_articles(ARTICLES){id_rubrique}> <li>[(#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 ignored.

Advanced usage

From version 1.8 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}> [<li> [(#SURTITRE)<br>](#SOUSTITRE)] </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

New with version 1.8

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 requires, then, to append the successive filters to the tag name between the parentheses, separated 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.

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 correction

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 ]

Tags with parameters

From [SPIP 1.8], some tags [1] are used with parameters. The parameter list is written between curly brackets «{» et «}», 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.