Some aspects of the pages of your site can be altered by using PHP variables. SPIP gives default values to these variables, but, in order to make fine adjustments to the site’s appearance, they can be changed by the webmaster.
Where can you set these variables?
It’s not necessary to go into SPIP’s source code to do this (phew!).
- to change something for the whole site
If you want to set variables for the whole site, you can do so in a file named mes_fonctions.php, which should be placed in the root directory of the site. (If this file does not already exist, you need to create it, placing <?php at the very beginning of the file and ?> at the very end, to indicate that the file contains PHP code. See the examples below.)
- to change something for a particular template
You can also set variables for each template. To do this, the variable definitions should be inserted at the beginning of the PHP file which calls the template (e.g. article.php, rubrique.php,...) together with the two required variables $fond and $delais.
Text variables
These variables are used when the page layout (SPIP’s typographical corrections) is calculated.
- $debut_intertitre defines the HTML code which SPIP inserts at the beginning of a subheading, in other words, where an author types the shortcut {{{. By default, its value is:
$debut_intertitre = "\n<h3 class=\"spip\">\n";
(\n in PHP creates a line feed.)
- $fin_intertitre defines the HTML code which SPIP inserts at the end of a sub heading (i.e. the short cut }}}). By default, its value is:
$fin_intertitre = "</h3>\n";
- $ouvre_ref is the code to open the reference to a footnote. By default it consists of a non-breaking space followed by a left square bracket: [
- $ferme_ref is the code to close the reference to a footnote. By default it is a right square bracket: ]
- $ouvre_note is the code to open the matching reference which appears at the beginning of the text of the footnote (such as will be displayed by the #NOTES tag). By default it is a left square bracket: [
- $ferme_note is the code to close the matching reference which appears at the beginning of the text of the footnote. By default it is a right square bracket: ]
Instead of using square brackets, you could use ordinary round brackets, or more attractively, use the HTML tags <sup> and </sup> to place the reference in superscript.
- The file puce.gif and the variable $puce: When you begin a new line with a hyphen, SPIP replaces it by a small graphic bullet. This bullet is the graphic contained in the file puce.gif in the root directory of the site. You can replace this file with another of the same name which contains a different graphic. Or you can define how SPIP transforms a dash by assigning a value to the variable $puce. For example, to make SPIP use another graphic file:
$puce = "<img src='mybullet.gif' alt='-' align='top' border='0'>";
or use an HTML element, rather than a graphic:
$puce = "<li>";
From version 1.9.2 onwards, and when using a shared SPIP kernel, you can also insert the following variable into config/mes_options.php, and not into squelettes/mes_fonctions:
$GLOBALS['puce'];
- $nombre_surligne represents the number of times that a sought after word will be highlighted in the text. By default, this value is defined as 4.
- $ligne_horizontale is the code used to replace the typographical shortcut ---- (four hyphens) or ____ (four underscore characters) which is used by editors to insert a horizontal line in the text. By default, this is code: <hr class="spip" />.
- $url_glossaire_externe is the address to be used for automatic shortcut links [?SPIP] to a glossary entry. By default, the external glossary links to the wikipedia.org free encyclopaedia.
Variables for the public forums
There are variables which make it possible to stipulate the behaviour of public forums by using keywords.
N.B. These variables can only be used if your site contains public forums in which visitors are able to select keywords. They are used, therefore, only in very specific cases (and their use is not straightforward).
- $afficher_texte can be set to "oui" or "non" (i.e. yes/no). Public forums have been designed to allow visitors to enter a text message. Thus, the default of this value is "oui". However, if a selection of keywords is offered to the visitor, it may be that any other message is superfluous. Only the selection of keywords matters, the text entry can then be blocked by using:
$afficher_texte = "non";
- $afficher_groupe allows you to choose the groups of keywords which you which to offer in a particular forum. Not all forums on a site are necessarily similar and if, for some, you wish to show a collection of keywords assembled from all the keyword groups (keywords which in the private area have been made accessible for visitors), for other forums you may wish to only use certain groups, or none at all (no keyword selection at all).
The variable $afficher_groupe is an array which is built in the following way:
$afficher_groupe[] = 3;
$afficher_groupe[] = 5;
The above will display only groups 3 and 5. While
$afficher_groupe[] = 0;
will prohibit the use of keywords in these forums (as there is no keyword group numbered 0).
If you don’t put anything, i.e. leave $afficher_groupe undefined, all keyword groups which are "allowed in the public site forums" will be used.
Intercepting the display of the admin buttons
All of the template pages will be supplemented by the "admin buttons" (and in particular: "recalculate this page") whenever you are a logged in administrator and you have activated the correspondence cookie in the private zone. This feature, which is very handy for managing the site, can sometimes be inappropriate in certain contexts; for example with XML files, were you don’t want any sort of supplemented content to mess up the output.
The flag_preserver variable is used to intercept the display of these buttons.
$flag_preserver = true;
You can see that it is already used in the backend.php file.
A separate directory for templates
If you want to put your templates in a separate directory, in order to try out different sets of templates you have downloaded, for example, or else because you like to keep them apart from the other SPIP system files, you can do this by setting the variable $dossier_squelettes in the file mes_options.php:
$GLOBALS['dossier_squelettes'] = 'design';
If SPIP finds this variable, it will first look for its templates in the design/ directory (which you will have created within the root directory of the site). And if, in addition, you use <INCLURE(fond=xxx)> in your template, SPIP will first look for the file xxx.html in the design/ directory. If it doesn’t find it there, then it will look in the root directory of the site.
The advantages of organising things in this way are clear: it gives a better separation between SPIP code and the site layout, and makes it simpler to replace a whole set of templates in one go. The major disadvantage is that it becomes more difficult to look at the templates directly using a web browser, because some links, including links to images and CSS files, will probably be "broken" in this view. This is so because the HTML content in templates, including those located in this subdirectory, must be written as if the template was in the root directory.
In order to handle this problem automatically, SPIP offers the #CHEMIN tag, fully described in Tags available throughout the site. Also note that viewing the templates with a simple web browser will also be messed up, since the visitor will not be able to find them at the site root; this does not upset any normal operation of the site, but it’s not really in the spirit of open source software.
This variable makes it possible to specify one or more folders where SPIP will go to look for the template files before looking in its "normal" locations:
$GLOBALS['dossier_squelettes'] = 'my_templates1:my_templates2';
This technique opens various new possibilities, such as:
- testing our a new set of templates without destroying the previous ones,
- organising your templates in a hierarchy with sub-directories: my_templates:my_templates/rss:my_tempaltes/forms:my_templates/mailing,
- dynamically managing several sets of templates using plug-ins such as the switcher,
- etc.
Examples
- To change variables for the whole site, you should set them in the file mes_fonctions.php.
N.B. When you set variables in this file, it is essential to use the syntax $GLOBALS['xxx'] for each one. For example, you set the variable $debut_intertitre by declaring it as $GLOBALS['debut_intertitre']. This syntax is necessary in order to ensure the site’s security.
Example:
$GLOBALS['debut_intertitre'] = "<h3 class='mon_style_h3'>";
$GLOBALS['fin_intertitre'] = "</h3>";
$GLOBALS['ouvre_ref'] = ' (';
$GLOBALS['ferme_ref'] = ')';
$GLOBALS['ouvre_note'] = '(';
$GLOBALS['ferme_note'] = ') ';
$GLOBALS['espace_logos'] = 0;
There do exist other variables for changing the default behaviour of SPIP at the system level. These variables are described on the official system documentation site.
See also
- The process of building public and private pages
- Variables et Constantes de personnalisation
- The mes_options.php file
- Extending SPIP
On the site Programmer.spip.net
On the site code.spip.net
There are other variables that can be used to modify SPIP’s behaviour at a technical level.