Objectifs

XEmb (XML Embedded) permet d'inclure un document XHTML externe (référencé par son url) dans un billet.

Le document étant référencé par son url, il peut être stocké sur n'importe quel autre serveur ! Par exemple, je l'utilise pour mon serveur Web personnel : dotclear est installé sur http://www.zeitoun.net alors que mes articles sont eux stockés sur http://kerphi.zeitoun.net/articles/

XEmb permet aussi d'inclure des feuilles de style particulières pour chaques articles, on peut ainsi personnaliser l'affichage de chaque articles : par exemple si on souhaite centrer une image ou faire flotter une image on peut le faire facilement et proprement en définissant sa propre feuille de style, elle sera automatiquement incluse par dotclear à la suite des siennes.

J'ai créé XEmb car je voulais pouvoir éditer mes articles avec un éditeurs XHTML externe (Amaya). XEmb me permet de conserver mes documents Web indépendamment de la base de donnée de dotclear, ainsi je peux les modifier très facilement avec Amaya sans passer par l'interface Web de dotclear : un simple clique sur le bouton save d'Amaya me permet de publier le document.

Installation

Installer le module php4-xslt (trouvez l'équivalent si vous utilisez php5) sur votre serveur dotclear. En effet, XEmb utilise des feuilles de style XSL pour extraire le contenu des documents et pour transformer les URLs des images et des liens.

Dotclear ne proposant pas de mécanismes pour surcharger ses méthodes d'affichage, l'installation se résume à préfixer dans le thème les appels à certaines fonction par XEmb::.

Éditez template.php :

• Insérez XEmb::dcPostMeta(); juste après dcPostTrackbackAutoDiscovery();
• Remplacez tous les dcPostTitle par XEmb::dcPostTitle
• Remplacez tous les dcSinglePostTitle par XEmb::dcSinglePostTitle

Éditez post.php :

• Remplacez tous les dcPostTitlepar XEmb::dcPostTitle
• Remplacez tous les dcPostChapo par XEmb::dcPostChapo
• Remplacez tous les dcPostContent par XEmb::dcPostContent

Éditez list.php :

• Remplacez tous les dcPostTitle par XEmb::dcPostTitle
• Remplacez tous les dcPostAbstract par XEmb::dcPostAbstract

Utilisation

Maintenant vous devez créer un document XHTML avec votre éditeur favoris et le stocker sur le serveur Web de votre choix. Attention, le code XHTML généré doit être valide ! Je vous conseil d'utiliser l'éditeur Amaya qui vous assure de créer des documents XHTML valides.

Remarque : votre page doit impérativement avoir une déclaration XML, c'est à dire que la première ligne de votre document doit être quelque chose du genre <?xml version="1.0" encoding="iso-8859-1"?>. Si vous ne mettez pas la déclaration XML, les transformation XSL ne pourront pas se faire et une erreur aura lieu.

Créez ensuite un billet, donnez lui un chapo (le titre n'a pas beaucoup d'importance, il est utile seulement pour la génération de l'url absolue du billet), et mettez ceci dans le corps du billet (cette chaîne de caractère sera automatiquement détectée par XEmb et remplacée par votre document XHTML) :

{XEmb url="http://kerphi.zeitoun.net/articles/xemb_un_plugin_pour_dotclear/index.html"}

(adaptez l'url à votre cas).

Vous pouvez maintenant visualiser le résultat sur la partie publique de votre site (XEmb ne fonctionne pas encore dans la partie administration)

Utilisation avancée

Vous pouvez facilement surcharger le style du thème dotclear pour chaque billet. Pour cela rajoutez une feuille de style dans votre document XHTML et ajoutez l'option meta="yes" dans le corps du billet de cette façon :

{XEmb url="http://kerphi.zeitoun.net/articles/xemb_un_plugin_pour_dotclear/index.html" meta="yes"}

XEmb va alors automatiquement inclure à la suite de la feuille de style de dotclear la votre. Vous pouvez ainsi personnaliser le style de chacun de vos articles!

Conseil : préfixer toutes vos règles de style par la classe .xemb, car sinon vous risquez d'altérer le style de la page entière (les menus, le header ...). Pour cela associez à votre document XHTML des règles CSS de cette forme : .xemb h2 { background-color: red; } et donnez la classe xemb à votre body.

Le télécharger

• Version 1.2 : plugin-xemb-1.2.pkg.gz, plugin-xemb-1.2.tar.gz
• Version 1.1 : plugin-xemb-1.1.pkg.gz, plugin-xemb-1.1.tar.gz
• Version 1.0 : plugin-xemb-1.0.pkg.gz

Historique des changements

• le ??/??/2005 - v?
  • La fonction XEmb::dcPostTitle retournait le contenu du titre de l'article sans remplacer les entitées necessaire, en particulier le double quote (") n'était pas encodé et donc les pages générés n'étaient pas valides.
• le 24/04/2005 - v1.2
  • Résolution d'un problème de cache sur l'inclusion des fichiers distants dynamiques (php) : le serveur ne renvoit pas d'attribut Last-Modified pour ces fichiers ce qui se traduisait par un cache qui n'était jamais vidé (merdi Daffys pour la mise en évidence).
  • Résolution d'un problème dans la fonction XEmb::dcPostAbstract, elle ne renvoyait rien pour les billets non XEmb (merci Daffys pour la mise en évidence).
  • Résolution d'un problème de path (include_path) sous windows (merci [RV] pour la mise en évidence)
  • Résolution d'un problème d'encoding dans le parser XSLT sous windows (merci [RV] pour la mise en évidence)
• le 18/04/2005 - v1.1
  • Première implémentation du système de cache pour éviter de charger à chaque fois le document externe depuis le réseau. Je me base sur l'attribut Last-Modified: ... que l'on peut trouver dans le http header pour les fichiers distants.
  • Résolution des problèmes de xmlns (namespace) dans les feuilles XSLT : les document générés étaient invalides. Maintenant il n'y a plus de restriction sur le faite de devoir mettre l'attribut xmlns sur la racine du document (<html xmlns="http://www.w3.org/1999/xhtml">).
  • Ajout d'un fichier de configuration et de son interface administrateur associée. Pour le moment les options suivantes sont disponibles : activer ou désactiver le cache, vider le cache, ajouter ou non les meta par défaut (c'est à dire les feuilles de style des documents externes).
• le 16/04/2005 - v1.0
  • Première version publique de XEmb

A faire

• Vérifier que le plugin fonctionne en mode UTF-8.
• Trouver une solution pour faire fonctionner la fonction Recherche de dotclear. En effet puisque les articles externes ne sont pas stockés dans la base de donnée de dotclear, la fonction Recherche ne peut pas fonctionner.
• Gérer les cas d'erreur. Si le document n'est pas valide, le parseur XSLT va sortir une erreur. Si le document distant n'est pas accessible (pas de reseau, mauvaise url ...), afficher une erreur ou bien la version la plus récente dans le cache.
• Trouver une solution pour se passer du mod php4-xslt qui n'est pas disponible chez la plupart des hébergeurs. Une solution serait d'utiliser des expressions régulieres pour extraire les parties interessantes du document mais cela poserait des problèmes quand l'encoding du document n'est pas le meme que celui de dotclear (d'où l'avantage de XSLT).
• Permettre la redirection des variables GET et POST quand le document externe est un script ayant pour but de traiter un résultat. (envoyer les informations au formulaire suppose de traiter le retour du forumlaire : l'afficher comme un document externe avec XEmb ? l'affiche autre part ?)
• Corriger les transformations XSLT pour qu'elles copient les espace de noms externes. Par exemple si on souhaite inclure du MathML dans un article, l'espace de nom xmlns="http://www.w3.org/1998/Math/MathML" doit être conservé.
• Ne pas utiliser la fonction ini_set car elle n'est pas disponible chez certains hebergeurs comme par exemple chez free. Chez free un repertoire à la racine nommé /include est automatiquement ajouté à la liste du include_path. On peut donc l'utiliser pour y placer les librairies utilisées par XEmb. J'ai fait un package contenant ces librairies, il suffit de le decompresser à la racine du FTP de free : xemblib-1.2-include.tar.gz. Ceci resoud tous les problèmes d'include mais n'est pas encore suffisant pour faire fonctionner XEmb chez free.