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] [uk] [vi] [zh] Espace de traduction

Download
Home > English documentation > What is SPIP? > Introduction > The overall structure of SPIP

The overall structure of SPIP

August 2010

All the versions of this article:


SPIP is a CMS truly quite unique in its field.

Beyond the underlying system that defines it as being "data driven" by using its famous BOUCLE (loop) constructs, it has always emphasised and facilitated methods for individual webmasters to "customise" it’s operations and presentation to meet the particular needs and tastes of any given site.

This is primarily accomplished by creating one’s own squelettes (templates), by enabling the attachment of special PHP code fragments, and by overloading the basic functions in the "core" code (the default function xxx_dist() naming mechanism that we will address again later).

Version 1.9 introduced an additional mechanism, that of administrator selected plugins. These are the results of wanting to open up SPIP to new additional functionalities without needing to over-burden the SPIP kernel (aka the core). In fact, the current tendency is to actually work on minimising this core code by transferring optional features out to the plugins.
The SPIP 2.0 version has indeed been reduced and delivered with a collection of basic plugins that the user/administrator can activate as and when necessary. For example, there’s a debate running as to whether news items should no longer be in the core but handed off to an optional plugin - many sites, in fact, have no need or call for news items at all, so it would be preferable to lighten the base system for those who do not actually need them.

Already previously, SPIP 1.9 had completely reorganised the directory structures that it employed in order to clearly separate elements according to their life expectancies, according to whether they were modifiable or not, and according to whether their appearance is standardised or customised relative to the core code or to the site’s own standards. One of the other targeted objectives with that release was to open up the possibility of sharing the kernel core amongst several sites, allowing them to share a common code base that no longer then needed to be duplicated.

First up here, we will look at this new directory structure, in terms of what belongs to SPIP, what belongs to a specific site, what remains constant and what continually changes. In the following discussion, a number of directories have been renamed and/or deleted and/or added, so don’t panic if you see something that you are unfamiliar with - check the version of SPIP that you are working with, and you should see that everything is, in fact, correctly structured as it ought to be.

Distribution

The site root

The root folder of a SPIP site has been completely emptied and now practically only contains the index.php which redirects to spip.php, which is now the unique point of entry to the public HTML site (of course, RSS feeds are still available, but they are XML and not HTML).

inc-public.php3 is a ghost file that has been retained for backwards compatibility.

.htaccess is an optional file, essentially used for rewriting URLs.

win_png.htc [1] onwards and rien.gif to ensure png transparencies under most versions of MSIE.

ecrire/

This folder now contains all of the files that can be interpreted by the server (PHP and MySQL) for both the private and public (in the public/ sub-directory) display screens.

The name of this folder (in French - "to write") is historical, because it was previously the location which contained the code for writing and modifying the site content. Paradoxically, it has now become a folder which never changes, as no one ever writes into it. In a standard installation, it only contains the scripts delivered with the standard distribution, and it is almost sacrosanct against any modifications of any kind whatsoever.

Its index.php script is the entry point into ecrire/, the private zone of the site, aka the "back-end".

dist/ [2]

This folder contains all of the files deliverable to the client (HTML, JavaScript, stylesheets, images in various formats) as well as the format templating files commonly known in SPIP as squelettes, or templates or template files for English speakers. These squelettes are interpreted by the server in order to send pure MIME text content out to clients (most of the time this is HTML, but may also be RSS, SVG... maybe even JS or some other esoteric content format that you may require).

These are the standard such templates delivered with the SPIP distribution, which you theoretically MAY modify, but which you really OUGHT NOT to as your changes would be lost if you ever upgrade your SPIP system - it is vastly preferred to copy them into a new directory that you should create in the root directory named squelettes/, and then modify them there instead, and they will automatically override the default ones in the dist/ directory. They are included in the standard distribution so that you at least have something to display any content that you insert in the SPIP database, even if you haven’t done any template customising work yet.

oo/ [3]

This folder supplies the "accessibility" mode for SPIP, being a text only based presentation. It essentially only contains an index that links into the standard system.

Adaptation

config/

This folder, created at system installation time, contains the database connection script: connect.php and the script that assigns protections on files created by the server: chmod.php.

It is also where the universal site options are specified in a file (that you must create yourself) called : mes_options.php [4]

IMG/

This folder contains all of the document originals (in their original full sizes) associated with the site. It is subdivided into sub-folders for each possible type of document.
Upon installation, it only contains the test documents used for constructing images so that the administrator can observe the available functionalities of the server when setting up the site configuration in the private zone.

squelettes/

This is where all of the files: scripts, images, form... particular to the site are stored, and its structure exactly follows that of ecrire/ or dist/. For example, to redefine the the home page sommaire for the site, you need to copy and then modify the sommaire.html file form the dist/ directory.

In addition, and of particular importance, the mes_fonctions.php script should be located here if/when you create one, so that it can be loaded on every recalculation of every page. Also note that you may create additional xxx_fonctions.php files which will be only loaded when the corresponding xxx page is requested (e.g. sommaire_fonctions.php) for the home page.

When the system is first installed, you have no customisations of any kind, so this folder does not exist - you need to create it yourself when you start customising the SPIP installation. At this point, bear in mind that in recent versions of SPIP there are plugins available that supply their own entire sets of squelette templates, which are maintained within the plugin directory structure, and which case you will not see the squelettes/ directory appear even though the public and private zones seem to clearly indicate that the site has been customised.

plugins/

This folder, which also needs to be created manually after system installation, is used to store all of the sub-folders for each of the plugins. For example, the crayons plugin is stored in the plugins/crayons/ folder.

Temporary files

local/

This contains all of the (re-)calculable files based on the site’s data and uploaded or referenced documents.

It essentially normally consists of caches of reduced images. There are also some other calculated caches stored here by certain plugins such as "coloration_code".

This folder may will be emptied, without any other impact than requiring its contents to be recalculated at such time as they are requested by site visitors.

tmp/

This folder is used to store all of the site’s normal temporary files, such as the template caches, session data, log files, etc.

It is also home to the dump/ sub-directory which stores all the database backups generated by the standard SPIP backup procedures provided in the private zone.

This folder, too, can be emptied at any time without affecting the site, but BE WARNED that you may also be deleting your only backups. Accordingly, proceed with caution and copy at least one back-up to your local machine before deleting all of those stored on the server.

P.S.

See also: Extending SPIP

Footnotes

[1deleted from version SPIP 2.0

[2From SPIP 2.0 onwards, this folder has been renamed as squelettes-dist/.
Please read: Updating from 1 .9 .x to 2 .0 .x.

[3deleted starting from version SPIP 2.0

[4Please read: The mes_options.php file


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