Manuel:Modèles HTML
| Version de MediaWiki : | ≥ 1.25 Gerrit change 187728 |
A partir de MediaWiki 1.25, MediaWiki peut générer du contenu HTML à partir de modèles Mustache sur le serveur et sur le client.
Le modèle d'analyse syntaxique côté serveur est implémenté en PHP via la classe TemplateParser , qui agit comme un conteneur de la bibliothèque lightncandy .
Les modèles côté client sont pris en charge par les modules ResourceLoader de mediawiki.template* et par la bibliothèque mustache.js .
Créer des modèles
Pour utiliser les modèles HTML dans votre code, créez d'abord un fichier de modèle Mustache ayant l'extension de fichier .mustache , par exemple, MyWidget.mustache.
Les modèles doivent contenir aussi peu de logique de programmation que possible pour être lus facilement et fournir une propre séparation des éléments.
Si votre modèle fait partie du coeur du logiciel MediaWiki, mettez-le dans le répertoire includes/templates du système.
S'il fait partie d'une extension, vous devez créer un dossier templates dédié dans le répertoire de votre extension pour le contenir.
Les modèles doivent suivre la spécification Mustache-5.
Classe TemplateParser (côté serveur)
| Fichier MediaWiki : TemplateParser.php | |
|---|---|
| Emplacement : | includes/Html/ |
| Code source : | master • 1.42.3 • 1.41.4 • 1.39.10 |
| Classes : | TemplateParser |
Before MW 1.40.1:
| Fichier MediaWiki : TemplateParser.php | |
|---|---|
| Emplacement : | includes/ |
| Code source : | master • 1.42.3 • 1.41.4 • 1.39.10 |
| Classes : | TemplateParser |
Cette classe recherche les fichiers des modèles, les lit, les compile en code PHP, et développe les balises en utilisant les données transmises afin de générer la sortie HTML. MediaWiki compile les modèles selon les besoins, et utilise le cache pour les y stocker s'il est disponible (voir le paragraphe mise en cache ci-dessous). Ceci évite aux développeurs de compiler les modèles en fichiers PHP pendant le développement ou comme une étape du build, ou au serveur de les écrire dans l'arborescence des fichiers pendant les opérations.
Pour utiliser TemplateParser, créez d'abord une nouvelle instance de la classe :
$templateParser = new TemplateParser();
Si vos modèles Mustache ne sont pas dans includes/templates du coeur, vous devez fournir le chemin de leur emplacement, dans le premier paramètre du constructeur (en relatif, soit par rapport à la racine de MediaWiki, soit par rapport au répertoire du fichier qui les appelle, avec __DIR__) :
$templateParser = new TemplateParser( __DIR__ . '/templates' );
Ensuite, vous analysez les modèles vers HTML en appelant la fonction processTemplate().
Le premier paramètre pour cela est le nom de votre modèle (la partie du nom de fichier avant .mustache).
Le second paramètre est un tableau contenant les valeurs utilisées par les balises Mustache de votre modèle.
Par exemple,
echo $templateParser->processTemplate(
'MyWidget',
[
'username' => $user->getName(),
'message' => 'Hello!'
]
);
Ceci remplace toutes les instances des balises {{username}} et {{message}} du modèle Mustache « MyWidget » par les valeurs fournies, et retourne le HTML résultant.
(le echo imprime simplement le HTML généré dans le contexte de sortie courant).
Comme exemple de modélisation HTML, voir includes/templates/NoLocalSettings.mustache tel qu'utilisé par includes/Output/NoLocalSettings.php.
Mise en cache
TemplateParser essaie de mettre en cache le modèle PHP compilé.
Il préfère utiliser CACHE_ACCEL (voir Manual:APC), et se replie sur CACHE_ANYTHING (un cache d'objet général comme Memcached ou Redis, voir Manual:Caching).
Eléments partiels
Le cache est basé sur des clés faites à partir d'un hachage du contenu de fichier, donc si vous modifiez un fichier de modèle, le modèle compilé sera mis à jour (vous devrez éventuellement vider le cache wiki de l'interface utilisateur en utilisant ?action=purge).
Néanmoins, cela ne prend pas en compte les modifications des modèles « partiels » que vous incluez avec {{>SubTemplateName}} (bogue T113095).
Donc si vous modifiez un partiel, vous devez faire des modifications cosmétiques sur les modèles parents qui l'incluent, ou redémarrer votre cache.
mw.template (côté client)
Pour utiliser un modèle Mustache du côté client, ajoutez le d'abord à votre définition de module ResourceLoader :
'ext.coolExtension.interface' => [
'templates' => [
'foo.mustache' => 'templates/foo.mustache',
],
'scripts' => [
'resources/interface.js',
],
],
La définition du modèle ci-dessus est faite de deux parties, un chemin de fichier (templates/foo.mustache) et un alias optionnel (foo.mustache).
L'alias doit être suffixé avec le nom du langage de modélisation (par exemple '.mustache') si bien qu'il connaît le compilateur à utiliser.
ResourceLoader dessert automatiquement les modules JavaScript mediawiki.template.xx pris en charge, donc vous n'avez rien à spécifier dans dependencies.
Une fois que vous avez ajouté le modèle à votre module, vous pouvez le récupérer par JavaScript en utilisant mw.template.get():
myTemplate = mw.template.get( 'ext.coolExtension.interface', 'foo.mustache' );
Pour générer le modèle et les données sous format HTML, appelez la fonction compilée render() du modèle.
data = {
username: mw.config.get( 'wgUserName' ),
message: 'Hello!'
};
$html = myTemplate.render( data );
Eléments partiels
| Version de MediaWiki : | ≥ 1.27 Gerrit change 206490 |
Les éléments partiels sont aussi pris en charge du côté client. Voir https://mustache.github.io/mustache.5.html#Partials pour plus d'informations.
Voir aussi
- Manuel:SkinMustache.php
- Manuel:Comment créer un habillage MediaWiki
- Skins:
- Extensions:
- Extension:SemanticMustacheFormat (unmaintained)
- Extension:Mustache i18n (unmaintained)
- Requests for comment/HTML templating library (closed)