From: Lucien Gentis Date: Sun, 28 Jun 2026 15:20:08 +0000 (+0000) Subject: fr doc XML file update. X-Git-Url: http://git.ipfire.org/gitweb/?a=commitdiff_plain;h=db446cac58d6b3fa2fe85fc999fa8d92b72456a7;p=thirdparty%2Fapache%2Fhttpd.git fr doc XML file update. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1935696 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/howto/ssi.xml.fr b/docs/manual/howto/ssi.xml.fr index 238bfbe428..863f50da83 100644 --- a/docs/manual/howto/ssi.xml.fr +++ b/docs/manual/howto/ssi.xml.fr @@ -1,7 +1,7 @@ - + @@ -30,7 +30,10 @@

Les SSI permettent d'ajouter du contenu dynamique à des documents -HTML préexistants.

+HTML préexistants sans nécessiter de cadriciel complet d’application. Ils +s’avèrent particulièrement utiles pour insérer des éléments courants — en-têtes, +pieds de page, navigation, horodatages — dans des pages qui, sans cela, seraient +statiques.
Qu'est-ce que SSI ? -

SSI (Server Side Includes) est constitué de directives placées dans - des pages HTML, et évaluées par le serveur au moment où les pages - sont servies. Elles vous permettent d'ajouter du contenu généré - dynamiquement à une page HTML préexistante, sans avoir à servir la - page entière via un programme CGI, ou toute autre technologie de - contenu dynamique.

- -

Par exemple, vous pouvez insérer la directive suivante dans une - page HTML existante :

- - - <!--#echo var="DATE_LOCAL" --> - +

Les directives SSI sont des commentaires HTML avec une syntaxe spécifique + que le module mod_include reconnaît et évalue avant que la + page ne soit envoyée au client. Elle sont de la forme suivante :

-

Ainsi, lorsque la page sera servie, la directive sera évaluée et - remplacée par sa valeur :

+ ++ ++<!--#echo var="DATE_LOCAL" --> ++ ++ +

Lorsque la page est servie, ce fragment est remplacé par sa valeur :

+ - Tuesday, 15-Jan-2013 19:28:54 EST + Thursday, 18-Jun-2026 14:22:07 EDT -

Le choix entre l'utilisation des SSI et la génération entière de - la page par un programme quelconque, est en général dicté par la - proportion de contenu statique et de contenu devant être généré - chaque fois que la page est servie. SSI est idéal pour ajouter de - petites quantités d'information, comme l'heure courante dans - l'exemple précédent. Mais si la - plus grande partie de votre page est générée au moment où elle est - servie, vous devez vous tourner vers une autre solution.

+

Les directives étant intégrées dans des commentaires HTML, les + navigateurs les ignoreront si les SSI ne sont pas activées (bien qu’elles + demeurent visibles dans le code source de la page).

Configurer votre serveur pour permettre les SSI -

Pour permettre l'utilisation des SSI sur votre serveur, vous - devez ajouter la directive suivante dans votre fichier - httpd.conf, ou dans un fichier .htaccess - :

+

Pour activer le traitement des SSI, ajoutez la directive suivante à votre + fichier httpd.conf ou à un fichier .htaccess :

+ + Options +Includes + + +

Si cette option est définie, httpd va analyser les fichiers en y + recherchant des directives SSI. Comme la plupart des configurations + contiennent plusieurs directives Options qui peuvent s’outrepasser les unes les autres, + appliquez la directive d’activation au répertoire spécifique pour lequel + vous voulez activer les SSI.

-

Cette directive indique à Apache que vous désirez permettre la - recherche de directives SSI lors de l'interprétation des fichiers. - Notez cependant que la plupart des configurations contiennent de - nombreuses directives Options - qui peuvent s'écraser les unes les autres. Vous devrez probablement - appliquer ces directives Options au répertoire - spécifique pour lequel vous voulez activer les SSI, afin d'être sûr - qu'elles y seront bien activées.

- -

Tout fichier ne fera cependant pas l'objet de recherche de - directives SSI. Vous devez indiquer à Apache quels fichiers seront - concernés. Vous pouvez y parvenir en indiquant une extension, comme - .shtml, à l'aide des directives suivantes :

+

Vous devez aussi indiquer à httpd les fichiers qu’il doit analyser. Pour + ce faire, il existe deux approches courantes.

+ +

La première consiste à indiquer une extension de nom de fichier (en + général .shtml) pour les pages pour lesquelles les SSI sont + activées :

+ + AddType text/html .shtml AddOutputFilter INCLUDES .shtml + -

Un des désavantages de cette approche réside dans le fait que si - vous voulez ajouter des directives SSI à une page préexistante, vous - devrez changer le nom de cette page, et donc tout lien qui la - contient, de façon à ce qu'elle possède l'extension - .shtml, condition nécessaire pour que les directives - SSI qu'elle contient soient traitées.

+

Cette approche a pour désavantage de nécessiter, pour ajouter des SSI à + une page existante, de renommer le fichier (et de mettre à jour tous les + liens vers ce dernier) pour utiliser l’extension .shtml.

-

Une autre méthode consiste à utiliser la directive La seconde approche consiste à utiliser la directive XBitHack :

+ + XBitHack on + + +

La directive XBitHack indique + à httpd qu’il doit analyser tout fichier dont le bit d’exécution est + positionné. Ainsi, pour activer les SSI pour une page existante, il suffit + de rendre le fichier exécutable :

-

La directive XBitHack - indique à Apache qu'il doit rechercher des directivves SSI dans les - fichiers si leur bit d'exécution est positionné. Il n'est ainsi plus - nécessaire de changer le nom du fichier pour ajouter des directives - SSI à une page préexistante ; vous devez simplement attribuer les - droits d'exécution au fichier à l'aide de chmod.

- chmod +x pagename.html + +chmod +x pagename.html + - -

Un bref commentaire sur ce qu'il ne faut pas faire. Certaines - personnes peuvent vous conseiller de tout simplement indiquer à - Apache de rechercher des directives SSI dans tous les fichiers - .html, ce qui vous évite d'avoir à gérer les noms de - fichiers avec extension .shtml. Ils n'ont probablement - pas entendu parler de la directive XBitHack. En effet, vous devez - garder à l'esprit qu'en faisant ceci, Apache va devoir rechercher - des directives SSI dans chaque fichier qu'il sert, même s'il n'en - contient aucune. Ce n'est donc pas une bonne idée car les - performances peuvent en être sensiblement affectées.

- -

Bien entendu, sous Windows, il n'y a pas de bit d'exécution à - positionner, ce qui limite un peu vos choix.

- -

Dans sa configuration par défaut, Apache n'envoie pas la date de - dernière modification ou les en-têtes HTTP relatifs à la taille des - contenus dans les pages SSI, car ses valeurs sont difficiles à - calculer pour les contenus dynamiques. Ceci peut induire une - impression de diminution des performances côté client, en empêchant - la mise en cache de votre document. Il existe deux méthodes pour - résoudre ce problème :

+ +

+ Évitez de configurer httpd pour analyser tous les fichiers + .html pour y trouver des directives SSI. Cela force en effet le + serveur à parcourir tous les fichiers HTML qu’il sert, même ceux qui n’ont + pas de contenu SSI, ce qui ajoute une surcharge de travail inutile. +

+ +

Sous Windows, il n’y a pas de bit d’exécution ; l’approche avec la + directive XBitHack n’est donc + pas valable dans ce cas. Vous devrez alors utiliser l’approche par extension + de nom de fichier.

+ +

Par défaut, httpd n’envoie pas la date de dernière modification ou les + en-têtes content-length sur les pages SSI, car ces valeurs sont difficiles à + calculer pour un contenu dynamique. Cela peut empêcher la mise en cache et + induire un ressenti de performances plus lentes. Deux approches peuvent + aider :

    -
  1. Utilisez la configuration XBitHack Full. Elle - indique à Apache de déterminer la date de dernière modification en - ne regardant que la date du fichier à l'origine de la requête, - tout en ignorant la date de modification de tout fichier inclus.
    2. - -
  2. Utilisez les directives fournies par le module - mod_expires pour définir de manière explicite la - date d'expiration de vos fichiers, laissant par la-même - aux navigateurs et aux mandataires le soin de déterminer s'il est - opportun ou non de les mettre en cache.
    3. +
  3. Utilisez la directive XBitHack Full qui indique à httpd + qu’il doit déterminer la date de dernière modification à partir du fichier + initialement demandé, tout en ignorant les dates de dernière modification + des fichiers inclus.
    4. + +
  4. Utilisez le module mod_expires pour définir un moment + d’expiration explicite, indiquant ainsi aux navigateurs et aux mandataires + que le contenu peut être mis en cache.
    5. +
Directives SSI de base -

Les directives SSI adoptent la syntaxe suivante :

+

Les directives SSI utilisent la syntaxe suivante :

- <!--#fonction attribut=valeur attribut=valeur ... --> + +<!--#function attribute=value attribute=value ... --> + -

Le format d'une directive SSI étant similaire à celui d'un - commentaire HTML, si vous n'avez pas activé correctement SSI, le - navigateur l'ignorera, mais elle sera encore visible dans le source - HTML. Si SSI est correctement configuré, la directive sera remplacée - par ses résultats.

- -

"fonction" peut prendre de nombreuses formes, et nous décrirons - plus précisément la plupart d'entre eux dans la prochaine version de - ce document. Pour le moment, voici quelques exemples de ce que vous - pouvez faire avec SSI.

+

Si les SSI sont correctement configurées, la directive sera remplacée par + sa sortie. Dans le cas contraire, elle demeurera en tant que commentaire + HTML — invisible à l’utilisateur final, mais présente dans le code source de + la page.

La date courante - <!--#echo var="DATE_LOCAL" --> + +<!--#echo var="DATE_LOCAL" --> + -

La fonction echo permet d'afficher la valeur d'une - variable. Il existe un grand nombre de variables standards, y - compris l'ensemble des variables d'environnement disponibles pour - les programmes CGI. De plus, vous pouvez définir vos propres - variables à l'aide de la fonction set.

+

La fonction echo a pour sortie la valeur d’une variable. Les + variables standard incluent le jeu complet de variables d’environnement + disponibles pour les programmes CGI, ainsi que les variables que vous pouvez + définir avec set.

-

Si vous n'aimez pas le format sous lequel la date s'affiche, vous - pouvez utiliser la fonction config avec un attribut - timefmt, pour le modifier.

+

Pour personnaliser le format de la date, utilisez la fonction + config avec l’attribut timefmt :

- <!--#config timefmt="%A %B %d, %Y" -->
- Today is <!--#echo var="DATE_LOCAL" --> + +<!--#config timefmt="%A %B %d, %Y" -->
+Today is <!--#echo var="DATE_LOCAL" --> +
Date de modification du fichier - Dernière modification du document <!--#flastmod file="index.html" --> + +Dernière modification du document <!--#flastmod file="index.html" --> +

Le format peut là aussi être modifié à l'aide de l'attribut @@ -236,12 +229,13 @@ AddOutputFilter INCLUDES .shtml

Inclusion des résultats d'un programme CGI -

C'est le cas le plus courant d'utilisation des SSI - afficher les - résultats d'un programme CGI, comme l'universellement adoré - "compteur d'accès".

+

Les SSI permettent d’inclure directement la sortie d’un programme CGI + dans la page :

- <!--#include virtual="/cgi-bin/counter.pl" --> + +<!--#include virtual="/cgi-bin/counter.pl" --> +
@@ -250,246 +244,216 @@ AddOutputFilter INCLUDES .shtml
Exemples additionnels -

Vous trouverez dans ce qui suit quelques exemples spécifiques de - ce que vous pouvez faire de vos documents HTML avec SSI.

+

Vous trouverez dans les exemples pratiques suivants des cas d’utilisation + courants des SSI.

Quand ce document a-t-il été modifié ? -

Nous avons mentionné plus haut que vous pouviez utiliser SSI pour - informer l'utilisateur de la date de dernière modification du - document. Cependant, la méthode pour y parvenir n'a pas été vraiment - abordée. Placé dans votre document HTML, le code suivant va insérer - un repère de temps dans votre page. Bien entendu, SSI devra avoir - été correctement activé, comme décrit plus haut.

- - <!--#config timefmt="%A %B %d, %Y" -->
- Dernière modification du fichier <!--#flastmod file="ssi.shtml" --> - +

Une des utilisations courantes des SSI est l’affichage d’un horodatage + « date de dernière modification » sur chaque page. Le code suivant utilise + la variable LAST_MODIFIED ; vous pouvez donc coller le même + extrait dans tout fichier sans modifier son nom :

-

Bien entendu, vous devez remplacer ssi.shtml par le - nom du fichier auquel vous faites référence. Ceci ne conviendra pas - si vous recherchez un morceau de code générique que vous pourrez - insérer dans tout fichier ; dans ce cas, il est préférable - d'utiliser la variable LAST_MODIFIED :

- <!--#config timefmt="%D" -->
- This file last modified <!--#echo var="LAST_MODIFIED" --> + +<!--#config timefmt="%D" -->
+Date de dernière modification de ce fichier <!--#echo var="LAST_MODIFIED" --> + + -

Pour plus de détails sur le format timefmt, tapez - strftime dans votre moteur de recherche préferé. La - syntaxe est identique.

+

Pour des détails à propos des chaînes de formatage de + timefmt, voir la documentation de strftime dans le + manuel de référence de la bibliothèque C de votre système.

-Que puis-je configurer d'autre ? +Autres options de configuration -

En plus du format de date, vous pouvez utiliser l'élément - config pour configurer deux autres choses.

+

En plus de timefmt, la fonction config accepte + deux autres attributs.

-

En général, lorsque quelque chose se passe mal avec votre - directive SSI, vous recevez le message :

+

L’attribut errmsg modifie le message d’erreur affiché + lorsqu’une directive SSI échoue. Le message par défaut est :

- [an error occurred while processing this directive] +[an error occurred while processing this directive] -

Pour modifier ce message, vous pouvez utiliser l'attribut - errmsg avec la fonction config :

+

Vous pouvez le remplacer par un contenu plus adapté à votre site :

- <!--#config errmsg="[Il semblerait que vous ne sachiez pas - utiliser les SSI]" --> + +<!--#config errmsg="[Content unavailable]" --> + -

Il est cependant probable que les utilisateurs finaux ne voient - jamais ce message, car vous aurez résolu tous les problèmes issus de - vos directives SSI avant que votre site ne soit mis en production. - (N'est-ce pas ?)

- -

Vous pouvez aussi modifier le format sous lequel les tailles de - fichiers sont affichées à l'aide de l'attribut sizefmt. - Vous pouvez spécifier bytes pour un affichage en - octets, ou abbrev pour un affichage plus concis en Ko - ou Mo, selon le cas.

-
+

L’attribut sizefmt contrôle la manière dont les tailles de + fichier sont spécifiées : bytes pour un décompte en octets ou + abbrev pour une forme abrégée en Ko ou Mo.

+
Exécution de commandes -

Voici autre chose que vous pouvez faire avec la fonction - exec. Vous pouvez vraiment faire exécuter une commande - par SSI en utilisant le shell (/bin/sh, pour être plus - précis - ou le shell DOS, si vous êtes sous Win32). Par exemple, ce - qui suit vous permet d'afficher le contenu d'un répertoire.

- - <pre>
- <!--#exec cmd="ls" -->
- </pre> - +

La fonction exec permet d’exécuter une commande du shell et + d’inclure sa sortie dans la page. Sur les systèmes de style Unix, la + commande est exécutée via /bin/sh, et sous Windows via + l’interpréteur de commande.

-

ou, sous Windows

- <pre>
- <!--#exec cmd="dir" -->
- </pre> + +<pre> +<!--#exec cmd="ls" --> +</pre> + +

+ La fonctionnalité exec constitue un risque de sécurité + significatif. En effet, elle exécute des commandes arbitraires avec les + privilèges du processus du serveur web. Si les utilisateurs peuvent éditer + du contenu sur votre site, assurez-vous que cette fonctionnalité soit + désactivée en spécifiant IncludesNOEXEC au lieu de + Includes dans la définition de la directive Options. +

+
-

Vous noterez probablement l'étrange formatage provoqué par cette - directive sous Windows, car la sortie de dir contient - la chaîne de caractères "<dir>", ce qui trompe le - navigateur.

- -

Notez que cette fonctionnalité est très dangereuse, car elle va - permettre d'exécuter tout code associé à l'élément - exec. Si vous êtes dans la situation où les - utilisateurs peuvent éditer le contenu de vos pages web, dans le cas - d'un "livre d'or" par exemple, assurez-vous de désactiver cette - fonctionnalité. Vous pouvez, tout en permettant les SSI, désactiver - la fonctionnalité exec à l'aide de l'argument - IncludesNOEXEC de la directive - Options.

-
+
Techniques SSI avancées -

Outre l'affichage de contenu, les SSI d'Apache vous permettent de - définir des variables, et de les utiliser dans des comparaisons et - des conditions.

+

Au-delà de la simple inclusion de contenu, les SSI prennent en charge les + variables et les expressions conditionnelles, rendant possible la génération + de contenus différents en fonction du contexte de la requête.

Définition de variables -

Avec l'élément set, vous pouvez définir des - variables pour un usage ultérieur. Comme nous en aurons besoin plus - loin, nous allons en parler tout de suite. La syntaxe se présente - comme suit :

+

La directive set permet de définir des variables à utiliser + plus tard dans la page :

+ - <!--#set var="name" value="Rich" --> + +<!--#set var="name" value="Rich" --> + -

Pour affecter une valeur à vos variables, en plus de la - définition littérale de l'exemple ci-dessus, vous pouvez utiliser - une autre variable, y compris les variables d'environnement, ou les variables - décrites plus haut (comme LAST_MODIFIED par exemple). - Pour indiquer qu'il s'agit d'une variable et non d'une chaîne, vous - devez utiliser le symbole dollar ($) devant le nom de la - variable.

+

Les variables peuvent référencer d’autres variables (y compris des variables d’environnement) en utilisant le signe dollar + ($) comme préfixe :

- <!--#set var="modified" value="$LAST_MODIFIED" --> - + + +<!--#set var="modified" value="$LAST_MODIFIED" --> + + + +

Pour inclure un signe dollar littéral, protégez-le avec une + contre-oblique :

-

Pour insérer un caractère $ dans la valeur de votre variable, - vous devez l'échapper à l'aide d'un backslash.

- <!--#set var="cost" value="\$100" --> + +<!--#set var="cost" value="\$100" --> + -

Enfin, si vous voulez insérer une variable dans une chaîne, et - s'il y a une chance pour que le nom de la variable se confonde avec - le reste de la chaîne, vous pouvez l'entourer d'accolades pour - eviter toute confusion (Il est difficile de trouver un bon exemple - pour illustrer ceci, mais j'espère que vous comprendrez).

+

Lorsqu'un nom de variable risque d'être ambigu au sein d'une chaîne plus + longue, utilisez des accolades pour le délimiter :

+ - <!--#set var="date" value="${DATE_LOCAL}_${DATE_GMT}" --> + +<!--#set var="date" value="${DATE_LOCAL}_${DATE_GMT}" --> +
Expressions conditionnelles -

Maintenent que nous avons des variables, et que nous pouvons - définir et comparer leurs valeurs, nous sommes à même de les - utiliser dans des expressions conditionnelles. Ceci confère à SSI le - statut de petit langage de programmation. - mod_include fournit une structure if, - elif, else, endif pour la - construction d'expressions conditionnelles, ce qui vous permet de - générer plusieurs pages logiques à partir d'une seule vraie - page.

- -

La structure de l'expression conditionnelle est :

+

mod_include fournit les éléments if, + elif, else et endif permettant de + construire une logique conditionnelle. Cette fonctionnalité permet de + générer des sorties différentes à partir d’une seule page physique.

+ +

La structure est :

+ - <!--#if expr="condition" -->
- <!--#elif expr="condition" -->
- <!--#else -->
- <!--#endif --> + +<!--#if expr="test_condition" -->
+<!--#elif expr="test_condition" -->
+<!--#else -->
+<!--#endif --> + -

Une condition peut revêtir la forme de toute comparaison - logique - soit une comparaison de valeurs avec une autre, soit une - vérification de la "vérité" d'une valeur particulière (Une chaîne - donnée est vraie si elle n'est pas vide). Pour une liste exhaustive - des opérateurs de comparaison disponibles, voir la documentation du - module mod_include.

+

Une test_condition peut comparer des valeurs ou vérifier si une + variable n’est pas vide. Voir la documentation de + mod_include pour la liste complète des opérateurs de + comparaison.

-

Par exemple, spour insérer l'heure du jour dans votre page web, - vous pouvez ajouter ces lignes dans la page HTML :

+

Par exemple, pour afficher des salutations différentes en fonction de + l’heure du jour :

- - Good - <!--#if expr="%{TIME_HOUR} <12" -->
- morning!
- <!--#else -->
- afternoon!
- <!--#endif -->
- - -

Toute autre variable (que vous avez définie, ou une variable - d'environnement normale) peut être utilisée dans les expressions - conditionnelles. Voir le document Expressions - rationnelles dans le serveur HTTP Apache pour plus de détails à - propos du fonctionnement du moteur d'évaluation des expressions - rationnelles.

- -

Associée à la possibilité avec Apache de définir - des variables d'environnement à l'aide de directives - SetEnvIf, ainsi que d'autres directives en rapport, - cette fonctionnalité vous permet d'ajouter une grande variété - de contenus dynamiques côté serveur sans avoir à concevoir une - application web de A à Z.

+ + +Good +<!--#if expr="%{TIME_HOUR} <12" -->
+morning!
+<!--#else -->
+afternoon!
+<!--#endif -->
+ + + +

Toute variable — définie par l’utilisateur ou issue de l’environnement + — peut être utilisée dans les expressions conditionnelles. Voir Les expressions dans le Serveur HTTP Apache pour des + détails complets à propos du moteur d’évaluation des expressions.

+ +

Combinées avec la capacité de httpd à définir des variables + d’environnement en utilisant SetEnvIf et les directives apparentées, + les SSI conditionnelles peuvent traiter une grande variété de scénarios de + contenu dynamique sans nécessiter de cadriciel complet d’applications.

Conclusion -

SSI ne remplace certainement pas CGI, ou d'autres technologies - utilisées pour la génération de pages web dynamiques. Mais c'est une - bonne méthode pour ajouter des petits contenus dynamiques à vos - pages, sans devoir fournir un gros effort supplémentaire.

+

Pour les sites principalement statiques mais nécessitant quelques touches + dynamiques, les SSI évitent la surcharge de travail induite par la + configuration d’une pile complète d’applications. Elles ne requièrent que + mod_include et quelques lignes de configuration pour + fonctionner.