Where do I put the template files for my site?

The default templates: squelettes-dist/

The distribution templates — i.e. those supplied in the standard SPIP installation — are all grouped together in a single directory. These files contain information for the site’s default page formatting and should not be modified. Of course, you are free to explore the contents of this directory and use this default set as a basis to make modifications to suit your own needs [1].

However, you really should not modify the distribution templates, otherwise you will risk losing your modifications any time that perform a standard update of the core SPIP system itself!
To avoid doing that, make a copy of any files that wish to modify, and store them all in another directory, as will be suggested just below.

Your squelettes/ folder

Customised templates should be stored in a directory called squelettes/ (note the plural "s" at the end!), that you must create in the root directory of your SPIP site. Whether you intend to install a complete set of templates (sourced from SPIP - Contrib or elsewhere), or only wish to make light modifications to the default templates, always store your templates in this directory.

As such, a user who wants to create her own graphical charter will develop her own article.html, rubrique.html, etc. files in this squelettes/ directory. Note that it is not necessary to have a complete set of templates in this directory, only those that you have changed or added and will actually use.

To display pages for the site, SPIP first looks for the templates in the squelettes/ folder; if SPIP does not find the .html file that it’s looking for, it will then look for the distribution version in the squelettes-dist/ folder.
So if you only have a single file in the squelettes folder, perhaps the article.html, then SPIP will use that template to display article pages, and the template files in the dist folder for all other site pages.

The squelettes/ folder is intended to store all of the files necessary to format a page for the site. It therefore stores:

• the templates, these being the .html files with embedded SPIP code;
• the files included by the templatesand any models ;
• any modified forms, preferably stored in a formulaires/ sub-directory
• the CSS stylesheets used to provide the graphical layout; customising them effectively allows for sometimes quite spectacularly different presentation of a site without altering the templates at all. See: "article 2463";
• the images used by the templates;
• the mes_fonctions.php file containing the filters and customisation variables belonging to the template set;
• the JavaScript files;
• the personalised language files (cf.: "Internationalizing Templates", multiple language files method), also preferably in a lang/ sub-directory;
• etc...

Using another template folder

It is possible to store the templates in a folder named according to your choice, by declaring it in the mes_options.php file with the $dossier_squelettes customisation variable, as explained in the corresponding documentation. SPIP will then go to look for the template files first in that defined directory.

This option allows you to try out a new set of templates without touching the old set, or to dynamically manage and switch between several sets of templates.

Template folder priority

To be more exhaustive and briefly summarise, by and large, when SPIP must use a particular file, it will look for it in the following order:

1. firstly in the list of folders specified in the $dossier_squelettes folder, if one has been defined;
2. then in the squelettes/ folder located at site root;
3. then in the list of folders in the $plugins variable;
4. then in the site root;
5. then in the squelettes-dist/ folder;
6. and finally in the ecrire/ directory.

Roughly speaking, since there are several subtleties to add to all that [2], including an order of priority per template file which offers finer variants of template files: per section, per sector or per language, as explained fully in the corresponding documentation.

Note: In fact, the mechanism described above for choosing the location of a file applies not only to templates, but also to all SPIP code. In developer jargon, this is known as "overloading the code", and the order in which the folders are chosen is in the "SPIP_PATH". This established the framework and standards for developing "plug-ins", extensions to SPIP’s functionalities that anyone in the SPIP community is free to offer.

In addition, you can change almost any characteristic of SPIP’s behaviour without depriving yourself in the future of changes and support in the community. SPIP is now truly modular