diff --git a/docs/manual/howto/ssi.html.fr b/docs/manual/howto/ssi.html.fr new file mode 100644 index 0000000000..5301816eab --- /dev/null +++ b/docs/manual/howto/ssi.html.fr @@ -0,0 +1,499 @@ + + + +Tutoriel Apache : Introduction aux "Inclusions Côté Serveur" +(Server Side Includes - SSI) - Serveur Apache HTTP + + + + + +

+Apache > Serveur HTTP > Documentation > Version 2.3 > Recettes et tutoriels

Tutoriel Apache : Introduction aux "Inclusions Côté Serveur" +(Server Side Includes - SSI)

Langues Disponibles: en | + fr | + ja | + ko

+ +

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

Introduction
Qu'est-ce que SSI ?
Configurer votre serveur pour permettre les SSI
Directives SSI de base
Exemples additionnels
Que puis-je configurer d'autre ?
Exécution de commandes
Techniques SSI avancées
Conclusion

Introduction

Modules Apparentés	Directives Apparentées
`mod_include` `mod_cgi` `mod_expires`	`Options` `XBitHack` `AddType` `SetOutputFilter` `BrowserMatchNoCase`

+ + +

Cet article traite des Inclusions Côté Serveur (Server Side + Includes), plus communément appelés SSI. Vous trouverez ici la + manière de configurer votre serveur pour permettre les SSI, ainsi + qu'une introduction à quelques techniques SSI de base permettant + d'ajouter du contenu dynamique à vos pages HTML préexistantes.

+ +

La dernière partie de cet article sera consacrée aux + configurations SSI plus avancées, telles que les expressions + conditionnelles dans les directives SSI.

+ +

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.

+ +

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. 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.

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 + :

+ Options +Includes +

+ +

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 :

+ 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.

+ +

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

+ XBitHack on +

+ +

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 +

+ +

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 :

+ +

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.
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.

Directives SSI de base

+ +

Les directives SSI adoptent la syntaxe suivante :

+  +

+ +

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.

+ +

"élément" 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.

+ +

La date courante

+ +

+  +

+ +

L'élément 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 l'élément set.

+ +

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

+ +

+  + Today is  +

+ + +

Date de modification du fichier

+ +

+ Dernière modification du document  +

+ +

Le format peut là aussi être modifié à l'aide de l'attribut + timefmt.

+ + +

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".

+ +

+  +

+ + +

Exemples additionnels

+ + +

Vous trouverez dans ce qui suit quelques exemples spécifiques de + ce que vous pouvez faire de vos documents HTML avec 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.

+  + Dernière modification du fichier  +

+ +

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 :

+  + This file last modified  +

+ +

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

+ + +

Inclusion d'un pied de page standard

+ + +

Si le site que vous gérez comporte plus que quelques pages, vous + allez vite vous apercevoir qu'effectuer des modifications sur toutes + ces pages peut devenir très contraignant, en particulier si vous + voulez qu'elles conservent un aspect homogène.

+ +

Inclure un fichier pour un en-tête et/ou un pied de page peut + simplifier cette corvée de mises à jour. Il vous suffit de + confectionner un fichier de pied de page, et de l'inclure dans + chaque page à l'aide de l'élément SSI include. Pour + définir le fichier à inclure, l'élément include peut + utiliser soit l'attribut file, soit l'attribut + virtual. L'attribut file est un chemin de + fichier relatif au répertoire courant. C'est à dire qu'il + ne peut ni avoir pour valeur un chemin absolu (commençant par /), ni + comporter "../" dans son chemin. L'attribut virtual est + probablement plus commode, et peut spécifier une URL relative au + document servi. Elle peut commencer par un /, mais le fichier inclus + et le fichier servi doivent résider sur le même serveur.

+  +

+ +

Je combinerai souvent ces deux derniers points, en ajoutant une + directive LAST_MODIFIED dans un fichier de pied de page + destiné à être inclus. Le fichier inclus peut contenir des + directives SSI, et les inclusions peuvent être imbriquées - à + savoir, le fichier inclus peut inclure un autre fichier, etc...

+ + +

Que puis-je configurer d'autre ?

+ + +

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

+ +

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

+ [an error occurred while processing this directive] +

+ +

Pour modifier ce message, vous pouvez utiliser l'attribut + errmsg avec l'élément config :

+  +

+ +

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.

Exécution de commandes

+ + +

J'ai pour projet, dans les prochains mois, d'écrire un article à + propos de l'utilisation des SSI avec des petits programmes CGI. Pour + l'instant, voici ce que vous pouvez faire avec l'élément + 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> +  + </pre> +

+ +

ou, sous Windows

+ <pre> +  + </pre> +

+ +

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.

+ +

Mise en garde

+ +

La plupart des fonctionnalités décrites dans cet article ne sont + disponibles que si vous utilisez la version 1.2 ou supérieure + d'Apache. Bien entendu, si ce n'est pas le cas, vous devez faire une + mise à jour immédiatement, et même plus tôt. Allez-y. Faites-le + maintenant. Nous attendrons.

+ + +

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 :

+  +

+ +

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.

+ +

 +

+ +

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

+  +

+ +

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).

+  +

+ + +

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 :

+  +  +  +  +

+ +

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. Voici quelques exemples + illustrant l'utilisation de ces expressions.

+ +

Vous pouvez ajouter les lignes suivantes dans votre fichier de + configuration :

+ BrowserMatchNoCase macintosh Mac + BrowserMatchNoCase MSIE InternetExplorer +

+ +

Ces lignes définissent les variables d'environnement "Mac" et + "InternetExplorer" à true, si le client utilise InternetExplorer sur + un Macintosh.

+ +

Puis, dans votre document où les SSI sont activées, vous ajoutez + ceci :

+  + Un texte d'excuses est inséré ici +  + Ici se trouve du code JavaScipt sympa +  +

+ +

Notez que je n'ai rien contre IE sur Macintosh - J'ai juste + phosphoré quelques heures la semaine dernière pour faire fonctionner + du JavaScript sous IE sur Macintosh, alors qu'il fonctionnait sous + tout autre environnement. Ce qui précède a constitué un + contournement provisoire.

+ +

Toute autre variable (que vous avez définie, ou une variable + d'environnement normale) peut être utilisée dans les expressions + conditionnelles. 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 des contenus dynamiques + assez évolués sans avoir recours aux programmes CGI.

+ +

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.

Langues Disponibles: en | + fr | + ja | + ko

+ \ No newline at end of file diff --git a/docs/manual/howto/ssi.xml.fr b/docs/manual/howto/ssi.xml.fr new file mode 100644 index 0000000000..68c5075c10 --- /dev/null +++ b/docs/manual/howto/ssi.xml.fr @@ -0,0 +1,501 @@ + + + + + + + + + + +Recettes et tutoriels + +Tutoriel Apache : Introduction aux "Inclusions Côté Serveur" +(Server Side Includes - SSI) + +

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

+ + + +

Qu'est-ce que SSI ? + +

+ +

+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 + :

+ + Options +Includes + + +

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.

+ +

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

+ +

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

+ + XBitHack on + + +

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 + + +

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.

+ +

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.
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.

+ +

Directives SSI de base + +

Les directives SSI adoptent la syntaxe suivante :

+ +  + + +

+ +

La date courante + + +  + + +

+ +

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

+ + + 
+ Today is  + +

+ +

Date de modification du fichier + + + Dernière modification du document  + + +

Le format peut là aussi être modifié à l'aide de l'attribut + timefmt.

+ +

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".

+ + +  + + +

+ +

+Exemples additionnels + +

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

+ +

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

+ + 
+ Dernière modification du fichier  + + +

+ + 
+ This file last modified  + + +

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

+ +

+Inclusion d'un pied de page standard + +

+ +

+ +  + + +

+ +

+Que puis-je configurer d'autre ? + +

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

+ +

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

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

Pour modifier ce message, vous pouvez utiliser l'attribut + errmsg avec l'élément config :

+ +  + + +

+ +

+ Exécution de commandes + +

+ + <pre>
+ 
+ </pre> + + +

ou, sous Windows

+ + <pre>
+ 
+ </pre> + + +

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.

+ +

+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.

+ +

Mise en garde + +

+ +

Définition de variables + +

+ +  + + +

+ +  + + +

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

+ +  + + +

+ +  + +

+ +

+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 :

+ + 
+ 
+ 
+  + + +

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. Voici quelques exemples + illustrant l'utilisation de ces expressions.

+ +

Vous pouvez ajouter les lignes suivantes dans votre fichier de + configuration :

+ + BrowserMatchNoCase macintosh Mac
+ BrowserMatchNoCase MSIE InternetExplorer + + +

Ces lignes définissent les variables d'environnement "Mac" et + "InternetExplorer" à true, si le client utilise InternetExplorer sur + un Macintosh.

+ +

Puis, dans votre document où les SSI sont activées, vous ajoutez + ceci :

+ + 
+ Un texte d'excuses est inséré ici
+ 
+ Ici se trouve du code JavaScipt sympa
+  + + +

+ +

Conclusion + +

+ + diff --git a/docs/manual/howto/ssi.xml.meta b/docs/manual/howto/ssi.xml.meta index d56f940fc1..f5e0c66572 100644 --- a/docs/manual/howto/ssi.xml.meta +++ b/docs/manual/howto/ssi.xml.meta @@ -8,6 +8,7 @@ en + fr ja ko

Apache Tutorial: Introduction to Server Side Includes

Tutoriel Apache : Introduction aux "Inclusions Côté Serveur" +(Server Side Includes - SSI)