SPIP

[ar] [ast] [bg] [br] [ca] [co] [cpf] [cs] [da] [de] [en] [eo] [es] [eu] [fa] [fon] [fr] [gl] [id] [it] [ja] [lb] [nl] [oc] [pl] [pt] [ro] [ru] [sk] [sv] [tr] [vi] [zh] Espace de traduction

Download
Home > English documentation > Where do I put the template files for my site?

Where do I put the template files for my site?

In the squelettes/ folder :-)

June 2010

All the versions of this article:

Since SPIP 2.0, the default SPIP template files are stored in a dedicated folder named squelettes-dist/. The squelettes/ folder should be used to store any customised template files you build (or copy) for your own site.


The advantages of this organisation are obvious: it provides better separation of the core SPIP code and the site structure, making it possible to change an entire set of template files in a single stroke, etc.

Previous history: In versions SPIP 1.8, 1.8.1 and SPIP 1.9, the template files supplied in the SPIP distribution were located in the dist folder. In versions prior to SPIP 1.8, 1.8.1, the template files were stored in the root directory. See : "What are the files in that “dist” directory?".

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

Since SPIP 1.8, 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 templates (as well as their corresponding php3 file for versions prior to SPIP 1.9) and any models (since SPIP 1.9);
  • 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: "Add your style!";
  • 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

Since SPIP 1.5, it has been 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 (since SPIP 1.9) 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.

"By and large", 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.

Remark: Since SPIP 1.9: In fact, the mechanism described above for choosing the location of a file is not only applies to just templates, but also to all of the SPIP code. In the jargon used by programmers, this is known as "overloading the code", with the order of the folders being determined by the "SPIP_PATH". This established the framework and standards for developing "plugins", 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

Previous history: The fact that SPIP looks for template files in the root directory has historic reasons, since that was the first location where they were stored. This had the advantage of making the templates "visible" from a browser, since the links to the .css files and other graphical components were necessarily "hard-coded" from the root directory (absolute file referencing).
In addition, up until SPIP 1.8.3, SPIP would look for the templates in the root directory before looking in the squelettes/ directory.

And what about the .php3 (or .php) files then?

Remembering that from SPIP 1.9 onwards, there are no longer any .php3 (or .php) files used for the templates: SPIP calculates all of its pages from a single unique script called spip.php.

In SPIP 1.8.2 and SPIP 1.8.3, there was a page.php3 file which foreshadowed spip.php and the inclusion method in SPIP 1.9. In fact, page.php3 made it possible, by itself, to call any template by passing the base variable as a parameter, this being the .html template file to be used:

The simplest procedure then was to use a call of this type [3] for any template other than those of the base objects (article, news item, section, sommaire (home),...) for which a .php3 file existed in the root directory, which made possible standardised calls such as:

Up until SPIP 1.8, you had to create a .php3 file, which was the hook for your .html in the previous SPIP template structure, which therefore had to be located in the site root directory [4].

Footnotes

[1This is a highly-recommended method to apply, since this set of templates has indeed been developed with this purpose in mind and is as modular as possible.

[2There is also a file naming convention that transcribes the purpose of the files, which means, for example, that SPIP will search for language files first in a lang/ sub-directory as we saw just above.

[3Note that this method also works for calls to the <INCLURE(page.php3){fond=inc-entete}> tag.

[4Except, possibly, those that are only used in a <INCLURE(squel.php3)> call and not directly with a URL. In this case, the squel.php3 file could also be located in the templates folder.


Show the template of this page Site powered by SPIP | Translation area | Private area