From this point on, what follows concerns the description language for the page layout of SPIP’s templates; if you have well understood the previous concepts. You have probably guessed that we will therefore be working with the ".html" files.
This documentation is voluntarily technical (this is part of SPIP’s technical references); you may prefer to start with our guide Step by Step which is more didactic, then come back here for a more detailed documentation.
Loops
The basic notion of the SPIP language is the loop.
- The Logic of the Loop
The classic way to see a database is as a list of elements: here, a list of articles, a list of sections, a list of authors,etc. To "build" the site, we will therefore extract of this list certain of its elements:
- we begin by extracting only one element from the list; for example, show the requested articles;
- but frequently we need to extract many elements from a list; for example, in the page of a section, we may want to show all the articles belonging in this section;
- and for some less obvious but important needs: what if there are no elements available? SPIP must work with situations where there is an absence of the required elements; for example, we want a template that shows all the sub-sections available in a given section; what should be the right reaction if there are no sub-sections in this section?
The above three situations are all processed by the unique notion of loop that can be used for managing the result of one element, many successive elements, or the absence of elements.
The loops system can, in the same code:
- indicate where in the HTML code we need a specific type of element (where to list the articles, where to include a list of sub-sections, ...);
- determine how to react if there is only one element;
- indicate the layout of a list of many elements;
- show alternate content when there are no elements available.
Analogy with PHP/MySQL programming
Those who have already programmed MySQL database requests with PHP know that the request is processed in two steps:
- the construction of the syntax of the request (which is a way of saying "I want the list of articles of ’that’ section ...");
- the analysis and the displaying of the results with the help of a loop.
In SPIP, The above two events are managed only with the help of loops.
SPIP Tags
With the help of loops, we have now fetched the unique element or the list of elements: for example, a list of articles or a list of sections.
However, each element of such lists is made of many more precise elements: for example, an article is made of a title, a top title, a subtitle, an introduction text (deck), a main text, a post-scriptum, etc. Therefore, there are many specific SPIP tags that we can use to specify where to place the elements: "put the title here", "put the text here", and so on.
Tags inside loops
Lets analyse, with the help of a classical example, the general concept of a loop and its tags (warning, it’s not in the SPIP language, it’s a logical description):
LOOP (BOUCLE in SPIP) : show the list of articles in this section
show here the title of the article
show the subtitle
show the text
End of the LOOP
This loop, when analyzed by SPIP, can give three different results.
- There are no articles in this section.
In this case, obviously, none of the elements "show this ..(title, subtitle, ...)" are used. Then again, if we have predicted this case, we can show a message such as "There are no articles."
- There is one article in this section.
In this case, the HTML page is built on the model of the loop:
Title of the article
Subtitle
Text of the article
- There are many articles in this section.
The description of the page formatting ("place here ..")
will then be applied successively for each of the articles.
The result will be:
Title of the article 1
Subtitle of the article 1
Text of the article 1Title of the article 2
Subtitle of the article 2
Text of the article 2...
Title of the last article
Subtitle of the last article
Text of the last article
This reference guide continues with the following structure:
- SPIP’s Loops: the syntax;
- SPIP’s tags: the syntax;
- followed by a specific page for each type of loop,
including a list of tags that are available for each of them.