General principle - archived version

The details given in this article are valid for versions of SPIP up to 1.83 and outdated from SPIP 1.9 onwards. For recent version of SPIP, read here (French).

However, reading this article is still a good introduction to SPIP. What is said about .html files is still true. The .php3 files mentioned have disappeared from use and the URLs have changed.

The whole content of a SPIP driven site is stored in a MySQL database. To make this information available to the site visitors, it must be read from the database, organised and inserted in a layout displaying an HTML page in the web browser.

This operation is usually very awkward:
-  it requires a good knowledge of PHP and MySQL programming and the creation of complex routines;
-  the integration of such routines in an advanced HTML layout is quite laborious;
-  performance issues should be taken into account: systematically executing PHP code and querying the database consumes much resources, slows the visits and in extreme cases causes the Web server to hang.

SPIP offers a complete solution to avoid these problems: the layout of the site is achieved through HTML pages called templates, containing simple instructions which indicate where and how to place the information retrieved from the database; a cache system allows to store each page thus avoiding repeated queries to the database at each visit. This not only lightens the burden on the server and improves the speed of the visits but a SPIP driven site could also be always alive even when the MySQL database is down.

A couple of files for each type of documents

The advantage (and restriction) of a content management system (CMS) is that you do not develop an HTML layout for each individual page. For instance, all the articles will use the same page layout as the system places them automatically in this layout (we will see later however, that SPIP allows some flexibility in this matter).

The advantage of this method is obvious: we define a standard format (template) for all the articles, for instance, and the system will create each individual page by automatically placing the title, the body, the navigation links… for each article.

For each type of document SPIP requires two files: a .php3 file and an .html file. After the installation of the system, you will then, find the couples: "article.php3 / article.html", "rubrique.php3 / rubrique.html", etc. Of course, you can modify these couples or create new ones.

How the cache works

The call for a specific page is made from the .php3 file. For instance, to call article 5, the URL should be:
-  http://mysite.net/article.php3?id_article=5

1.The called file is therefore, article.php3 with the parameter id_article=5.

2. The file article.php3 is a PHP file; its first task is to check the folder /CACHE on the server to find whether there is a file corresponding to this article.

2b. If such a file exists in /CACHE, article.php3 checks its creation date. If this file is quite recent, it returns it to the visitor and the visit process ends.

3. If such a file doesn’t exist in /CACHE (first visit to this article, for instance), or if it is quite old, SPIP starts the processing of this page.

4. Then, the page article.html is loaded and analysed. This page contains the layout suited for this type of document. It consists of HTML tags accompanied by indications on how and where to place the items retrieved from the database. Based on the items required by article.html, SPIP fetches the needed information from the MySQL database and inserts them in the locations assigned.

5. So a file is created by article.php3, from the description contained in article.html, with the items retrieved from the database. This file is then saved in the folder /CACHE and returned to the visitor.

During the next visit, if the gap between the two visits is short enough, it is the new file in the /CACHE folder that is returned to the visitor, without the need of processing the page again. If the database is down, it is definitely the file in the cache that is returned even if it is "too old".

Note. We notice here that each page is stored individually in the cache and each re-processing is triggered by the visits. A periodic re-processing of all the page in one go does not happen (an operation of this magnitude has the bad habit of overloading the server and causing it to hang).

The .PHP3 file

The ".php3" file is very simple. For instance, the file article.php3 only contains:

Its only aim is to set two variables ($fond and $delais) and to call the file that triggers SPIP (inc-public.php3).

The variable $fond (base) is the name of the file containing the page description (the template). Here, as $fond="article", the description file will be in article.html [1]. Note that in the $fond variable, we don’t enter the extension ".html".

Note. The advantage for the developer in choosing the template filename himself (which we can deduct straight away from the .php3 filename) is to use a different name if the need arises. This will avoid overwriting possible HTML files remaining from an older version of the site that he would rather keep. So if an article.html file from an old version of the site, exists and we don’t want to delete it, we will use, for instance, a template file called article-new.html and, in article.php3, we set:
$fond="article-new".

The variable $delais (delay) is the maximum age of the file stored in /CACHE. This delay is set in seconds. A delay of 3600 is then equal to an hour; a delay of 24*3600 is therefore 24 hours.

This value can be set according to the frequency of the site updates (new articles or news items…). A site updated several times a day could adopt a delay of an hour; on the other hand, a site that publishes a few articles a week, can set a much longer delay. The content of the pages is important as well: if you insert a content syndication from sites, which are frequently updated, you might want to adapt your delays to the syndicated sites.

Note. Some webmasters yield to the temptation to set very short delays (a few seconds) to try and keep the site up to date at any moment with all the changes in the database. In this case, you will loose all the advantages of the cache system: pages are slower and, in some extreme cases when the traffic on the site is heavy, you can cause the database to hang (or your host could terminate your account because you are monopolizing the resources of his server…).
Note. Another reason likely to influence webmasters into setting very short delays is the presence of forums on the site. As a matter of fact, a short re-processing delay is susceptible, they think, of displaying contributions as soon as they are posted. This is useless: SPIP manages this matter automatically; when a contribution is posted, the corresponding page is deleted from the cache and re-processed immediately no matter how long or how short its delay is.

The .HTML file

In SPIP, .html files are called templates. They are the files that describe the graphical interface of the pages.

These files are written in straight HTML, accompanied by instructions that indicate to SPIP where it should place the elements retrieved from the database (such as: "place the title here", "display here the list of articles related to the same topic"…).

These placement instructions are written in a specific language, which is the subject of the present documentation. Anyway, this language constitutes the only difficulty in SPIP.

"What? Another language?" Well yes, you have to learn a new language. However, it is rather simple and it allows the creation of very complex interfaces, very quickly. Compared to the couple PHP/MySQL, you will soon find that it will save a great deal of time (especially that it is simpler). It is a markup language, which means a language using tags similar to those used by HTML.

Note. As you learn HTML by drawing our inspiration from the source code of the sites we visit, you can learn from the templates used by other SPIP driven sites. You just have to download the proper ".html" file. For instance, you can refer to the template of uZine’s articles (look at the source code to see the templates text).

A different interface in the same site

First of all, you should note that it is possible to create couples of files for the same logical element (articles, sections…). For instance, you can create files to visit the same article but with different interfaces: article.php3/html for the standard format, print.php3/html for the same article but in format more suited for printing, article-text.php3/html for the same article but in a text format (suits the disabled), article-heavy.php/html for the same article but with a heavy interface suitable for broadband, etc.

-  A different interface according to the sections. For the same type of document, you can create different templates according to the sections in the site. You just have to create new .html files according to the sections (no need, here, to modify the .php3 file, as you can control the templates’ filenames).

You just have to append "-number" to the template’s filename (a hyphen followed by a section number). For instance, if you create a file: article-60.html, all the articles included in section number 60 will use this template (and not the default template article.html anymore). Note that the number indicated in the filename is a section number. If this section 60 contains sub-sections, articles contained in those sub-sections will also use the new template article-60.html.

Note.In our example, we could benefit from creating a rubrique-60.html (for the sub-sections) or even a breve-60.html (for the news items) to go along with the change in the layout of this section.

An interface for one section. (SPIP 1.3) You could create an interface dedicated to one section, but not to its sub-sections. For this, you must create a file: article=60.html which will only address the articles of section 60, but not its sub-sections.

What can we put in a .HTML file?

The .html files are basically "text" files complemented by instructions for the placement of the database elements.

SPIP analyses only those instructions (written with the SPIP language); SPIP doesn’t give a monkey’s toss about what’s in the file that doesn’t relate to those instructions.

The main content of these files is then standard HTML. You define the page layout, the required HTML version, etc. Of course, you can use Cascading Style Sheets (CSS), JavaScript, Flash animations… you name it, basically everything you usually put in a web page.

Furthermore, you can create XML documents; at the end of the day, it is still only text (for instance, the couple "backend.php3/html" generates XML).

More exotic: all the pages returned to the visitor are retrieved from the /CACHE folder by a file written in PHP. Therefore, you can include PHP instructions in your templates and they will be executed during the visit. If used wisely, this method gives SPIP much flexibility and opportunities to be extended and enhanced (like adding a counter, for instance) or even allows the improvement of some layout elements according to information pulled out from the database.

Footnotes

[1See What are the files in that “dist” directory?, and “A different interface in the same site” (on this page) for further information.

Author George, Paolo Published : Updated : 26/10/12

Translations : عربي, català, Deutsch, English, Español, français, italiano