Extension:TemplateStyles

Manuel des extensions MediaWiki

TemplateStyles État de la version : stable
Implémentation	Balise , ContentHandler , Accroche
Description	Permet, à partir d'un modèle, de charger des feuilles de styles CSS normalisées (sanitized CSS).
Auteur(s)	Brad Jorsch Marc A. Pelletier
Dernière version	Mises à jour continues
Politique de compatibilité	Versions ponctuelles alignées avec MediaWiki. Le master n'est pas compatible arrière.
MediaWiki	1.30+
PHP	7.3+
Licence	Licence publique générale GNU v2.0 ou supérieur
Téléchargement	Télécharger l'extension Git [?]: Télécharger la branche master de Git parcourir le dépôt (Phabricator · GitHub) historique des validations (commits) contributeurs du dépôt (GitHub) relecture du code
Paramètres $wgTemplateStylesUseCodeEditor $wgTemplateStylesDisable $wgTemplateStylesDefaultNamespace $wgTemplateStylesDisallowedAtRules $wgTemplateStylesDisallowedProperties $wgTemplateStylesAllowedUrls $wgTemplateStylesAutoParseContent $wgTemplateStylesMaxStylesheetSize $wgTemplateStylesNamespaces
Balises <templatestyles src=... />
Accroches utilisées CodeEditorGetPageLanguage ContentHandlerDefaultModelFor ParserClearState ParserFirstCallInit
Accroches fournies TemplateStylesPropertySanitizer TemplateStylesStylesheetSanitizer
Téléchargements trimestriels	1,129 (Ranked 1st)
Utilisé par les wikis publics	1,977 (Ranked 199th)
Traduire l’extension TemplateStyles sur translatewiki.net si elle y est disponible
Problèmes	Tâches ouvertes · Signaler un bogue

TemplateStyles est une extension d'analyse syntaxique qui permet aux utilisateurs de stocker du code CSS personnalisé sur les pages wiki, et d'intégrer ces styles dans les articles via la balise ‎<templatestyles>. L'extension n'autorise à enregistrer qu'un ensemble sécurisé de syntaxes CSS dans les pages de style incluables. Ceci est propulsé par la bibliothèque css-sanitizer.

Les éditeurs sont encouragés à inclure les styles d'un modèle via TemplateStyles car cela permet aux mêmes utilisateurs de modifier à la fois le modèle et ses styles, et de cette façon les styles ne sont chargés que lorsque cela est nécessaire (à la différence de l'ajout sur l'ensemble du site MediaWiki:Common.css ).

Voir Aide:TemplateStyles pour les instructions concernant l'utilisation de l'extension en tant qu'éditeur sur un wiki.

Utilisation

D'abord la page CSS doit être créée. Par défaut toute sous-page de l'espace de noms Template: ayant un titre qui se termine par « .css » sera créée avec le content model CSS nettoyé si elle ne contient pas d'erreurs de syntaxe.

L'ensemble des espaces de noms peut être ajusté avec $wgTemplateStylesNamespaces, ou Special:ChangeContentModel peut être utilisé sur toute page. Puis dans le wikicode du modèle, ajoutez la balise <templatestyles src="..." /> pour charger les styles.

Le CSS savegardé en utilisant le modèle de contenu CSS nettoyé correspond strictement aux règles de validité : le CSS non valide, les règles 'at' non reconnues, et les propriétés, ou les valeurs de proriété non reconnues ou non prises en charge, ne pourront pas être sauvegardés. Si du CSS non valide est néanmoins sauvegardé, les constructions en faute seront retirées lorsque le CSS sera envoyé au navigateur.

La valeur de l'attribut src sur la balise est le titre de la page, par défaut dans l'espace de noms Template. (Cette valeur par défaut peut être modifiée par $wgTemplateStylesDefaultNamespace.) Par exemple, <templatestyles src="Example/styles.css" /> va charger la page Template:Example/styles.css. Ceci va échouer si cette page n'existe pas ou si elle a un modèle de contenu différent de CSS nettoyé.

Les styles peuvent être étendus dans la page en utilisant le paramètre facultatif wrapper dans la balise, par exemple <templatestyles src="Example/styles.css" wrapper="div.example" /> étend les styles chargés dans n'importe quel <div class="example"> à l'intérieur du contenu principal analysé. Toute séquence de sélection CSS simple peut être utilisée pour le paramètre wrapper. Ceci est fait pour permettre la comparaison côte à côte de la version courante d'un modèle avec celle du bac à sable.

L'utilisation du CSS normalisé se fait comme la transclusion des modèles, et apparaît comme une transclusion sur Special:WhatLinksHere .

Mises en garde

• Les styles ajoutés par TemplateStyles sont étendus dans .mw-parser-output pour éviter de falsifier l'interface utilisateur en dehors du contenu principal analysé.
  • Pour utiliser TemplateStyles pour mettre en forme quelque chose comme w:MediaWiki:Protectedpagetext, vous devrez inclure le contenu du message dans <div class="mw-parser-output">...</div>.
• Les styles doivent être écrits pour cibler des classes CSS spécifiques, et tout ce qui génère des éléments avec ces classes doit s'assurer d'inclure également les styles lui-même plutôt que de s'appuyer sur un autre modèle pour le faire.
  • Les styles inclus par un modèle peuvent actuellement affecter le contenu de la page en dehors du contenu généré par ce modèle, mais cette capacité peut être supprimée à l'avenir et ne doit pas être invoquée. (See discussion from phab:T155813#2996589 and in phab:T176272.)
  • L'inclusion de styles sur un modèle qui affecte le contenu en dehors de ce modèle entraînera la non-application de ces styles lors de la modification d'une section qui ne contient pas ce modèle. Exemple : inclure des styles sur une infobox qui affectent tous les tableaux de la page, lors de la modification d'une section qui ne contient pas l'infobox, ces tableaux ne seront pas stylisés lors de la prévisualisation de cette section.
• TemplateStyles ne prend pas en charge les variables CSS, voir phab:T320322.
• TemplateStyles autorisent certaines propriétés CSS non standard. Les demandes pour prendre en charge des propriétés supplémentaires doivent être faites dans les projets css-sanitizer et TemplateStyles de Phabricator.
  • Les demandes doivent inclure des liens vers des documents de suivi des normes (par exemple sur w3.org) décrivant la syntaxe des propriétés demandées, et une analyse de la prise en charge du navigateur actuel pour les propriétés (par exemple, un lien vers une page caniuse.com à propos des propriétés).
  • Les propriétés préfixées par le fournisseur (par exemple, tout élément commençant par -webkit-, -moz- ou -ms-) sont susceptibles d'être refusées si elles ne sont pas nécessaires pour les navigateurs modernes.
• Les règles @font-face doivent utiliser un font-family préfixé avec TemplateStyles. Ceci devrait grandement empêcher de redéfinir les fontes utilisées partout dans le document.
• Pour cibler des styles basés sur les habillages, utilisez un sélecteur tel que body.skin-vector .myClass; la spécification de l'élément body est nécessaire et doit être suivie d'un combinateur descendant (par exemple 'espace'). Les autres classes sur les éléments body ou html peuvent être ciblées de la même manière. See phab:T197617. 1.32+

Installation

• Téléchargez et placez le(s) fichier(s) dans un répertoire appelé TemplateStyles dans votre dossier extensions/.
  Les développeurs et les contributeurs au code doivent à la place installer l'extension à partir de Git en utilisant:cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/TemplateStyles
• Seulement lorsque vous installez à partir de Git, exécutez Composer pour installer les dépendances PHP, en entrant composer install --no-dev après vous être positionné dans le répertoire de l'extension. (Voir tâche T173141 pour des complications potentielles.)
• Ajoutez le code suivant à la fin de votre fichier LocalSettings.php  :

  wfLoadExtension( 'TemplateStyles' );
  

• Configurez selon les besoins.
•  Fait – Accédez à Special:Version sur votre wiki pour vérifier que l'extension a bien été installée.

Installation Vagrant :

• Si vous utilisez Vagrant , installez avec vagrant roles enable templatestyles --provision

Pour disposer d'un interface utilisateur plus agréable, avec une mise en valeur de la syntaxe et un éditeur de code faisant l'indentation automatique, installez les extensions suivantes :

• Extension:WikiEditor
• Extension:SyntaxHighlight
• Extension:CodeEditor

Configuration

Paramètres de configuration

Paramètre	Valeur par défaut	Commentaire
$wgTemplateStylesAllowedUrls	[ "audio" => [ "<^https://upload\\.wikimedia\\.org/wikipedia/commons/>" ], "image" => [ "<^https://upload\\.wikimedia\\.org/wikipedia/commons/>" ], "svg" => [ "<^https://upload\\.wikimedia\\.org/wikipedia/commons/[^?#]*\\.svg(?:[?#]|$)>" ], "font" => [], "namespace" => [ "<.>" ], ]	expressions régulières compatibles Perl (PCRE) correspondant aux URLs autorisées pour les différents types de références externes. Les clés sont des types de références externes , les valeurs sont des tableaux d'expressions régulières (comprenant les délimiteurs) correspondant aux URLs autorisées. Les types de références externes actuels sont : audio fichier son, pour les propriétés cue du module CSS Speech. image fichier image, pour les propriétés telles que background. svg fichier SVG, pour les modules CSS Masking et Filter effects. font pour les src de @font-face. namespace pour @namespace.
$wgTemplateStylesNamespaces	[ NS_TEMPLATE => true ]	Espaces de noms dans lesquels déclarer le modèle de contenu CSS nettoyé pour les titres se terminant par .css. Activer ceci pour 2 (utilisateur) ou 8 (MediaWiki) est une mauvaise idée, car cela produira un conflit avec les fichiers CSS normaux dans ces espaces de noms.
$wgTemplateStylesPropertyBlacklist	[]	propriétés à mettre en liste noire en règles de style CSS. L'accroche TemplateStylesPropertySanitizer permet un contrôle plus fin.
$wgTemplateStylesAtRuleBlacklist	[]	règles 'at' à mettre en liste noire dans les feuilles de style. Accroche TemplateStylesStylesheetSanitizer pour un contrôle plus fin.
$wgTemplateStylesUseCodeEditor	true	indique s'il faut activer Extension:CodeEditor pour le type de contenu CSS nettoyé.
$wgTemplateStylesAutoParseContent	true	S'il est à true, le modèle de contenu CSS nettoyé sera ajouté à $wgTextModelsToParse si le modèle de contenu CSS est déjà présent dans ce tableau. S'il est à false, ajoutez 'sanitized-css' manuellement à ce tableau si vous voulez que les catégories et équivalents soient analysés syntaxiquement en dehors de la page CSS.
$wgTemplateStylesMaxStylesheetSize	102400	taille maximale (en octets) d'une feuile de style; illimité si null .
$wgTemplateStylesDefaultNamespace	NS_TEMPLATE	Espace de noms par défaut pour l'attribut src de la balise ‎<templatestyles>.

Autres dépendances

$wgTidyConfig doit être configuré pour ne pas utiliser le rangement ou RemexHtml. Si utilisé avec l'un des pilotes Raggett, une balise ‎<templatestyles /> au milieu d'un paragraphe (y compris dans un modèle en ligne) provoquera la rupture du paragraphe à ce point. Les autres pilotes n'ont pas été testés pour ce problème.

Erreurs possibles

Vous pouvez essayer d'activer $wgShowExceptionDetails dans votre LocalSettings.php pour voir si vous vous êtes dans l'un des cas d'erreur ci-dessous.

• Class 'Wikimedia\CSS\Parser\Parser' not found

  Cela signifie qu'une bibliothèque nécessaire n'a pas été installée. L'erreur peut apparaître lorsque l'on essaie d'importer une page CSS du wiki ou lorsque l'on modifie le modèle de contenu d'une page avec le sanitized-css. C'était courant dans le passé en raison d'un bogue dans le distributeur d'extensions ; ne devrait plus arriver.
  There is a generally method is update composer under the extension's directory.

• Import failed: The content model 'sanitized-css' is not registered on this wiki.

  Se produit lorsque vous importez une page wiki créée via TemplateStyles et que celui-ci n'est pas installé sur votre wiki.

Voir aussi

• Aide:TemplateStyles
• css-sanitizer - utilisé pour la normalisation du CSS.
• phab:T483 « Appel à commentaires pour autoriser la mise en forme à partir de modèles » (concerne la possibilité de déployer cette extension sur les wikis Wikimedia)
  • Requests for comment/Allow styling in templates
• phab:T56864 « ResourceLoader: implémente la prise en charge de LESS dans les modules wiki (utilisateur et site), pour supporter par exemple MediaWiki:Common.less »
• phab:T155813 « Décide des méthodes de stockage et de diffusion pour le CSS de TemplateStyles »
• Il est maintenant plus facile de fabriquer du contenu pour les appareils mobiles : architecture du web dynamique à l'échelle de Wikipedia sur le blog Wikimedia.
• Extension:TemplateStylesExtender/fr