Extension:Widgets

Prenez en compte également les widgets contributeurs que vous avez créés. Merci de partager !

Manuel des extensions MediaWiki

Widgets État de la version : stable
Implémentation	Fonction d'analyseur
Description	Permet d'ajouter au wiki, des widgets de type libre, en modifiant les pages de l'espace de noms Widget.
Auteur(s)	Sergey Chernyshev Yaron Koren
Maintenance	Yaron Koren
Dernière version	1.6.0 (2024-08-02)
MediaWiki	1.38+
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
Exemple	[1]
Paramètres $wgWidgetsCompileDir $wgWidgetsUseFlaggedRevs
Droits ajoutés editwidgets
Accroches utilisées ParserAfterTidy ParserFirstCallInit
Téléchargements trimestriels	149 (Ranked 37th)
Utilisé par les wikis publics	1,122 (Ranked 207th)
Traduire l’extension Widgets sur translatewiki.net si elle y est disponible
Rôle Vagrant	widgets
Problèmes	Tâches ouvertes · Signaler un bogue

L'extension Widgets permet de créer des pages en HTML brut pouvant être transcluses (comme les modèles) dans les pages de wiki standard. Cela est possible en créant des pages dans l'espace de noms Widget: . Elles évitent les problèmes de sécurité du HTML brut dans les pages modifiables du wiki par la restriction des droits d'édition dans l'espace de noms Widget. Beaucoup de widgets déjà écrits sont disponibles.

Téléchargement

Pour obtenir le code avec Git, entrez les commandes suivantes :

cd extensions
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/Widgets.git
cd Widgets
composer update --no-dev

Composer est un gestionnaire PHP de dépendances. Pour MediaWiki >= 1.35.2, vous devrez peut-être mettre à jour Composer à la version 2. Instructions ici.

Installation

Pour appeler cette extension, ajoutez ceci à LocalSettings.php  :

wfLoadExtension( 'Widgets' );

Droits sur les répertoires

De plus, il faut que le répertoire $IP/extensions/Widgets/compiled_templates/ soit accessible en écriture par le serveur Web. Voir Rendre un répertoire accessible en écriture par le serveur web. Le dossier des modèles compilés est celui où Smarty stocke les modèles pré-compilés.

Configuration

Les étapes de cette section sont facultatives : l'extension doit fonctionner correctement même sans ces modifications, mais ces dernières vous apporteront plus de flexibilité dans le cas d'une installation Médiawiki complexe.

Utiliser FlaggedRevs pour la relecture des widgets

Vous pouvez utiliser l'extension FlaggedRevs pour activer un processus de révision de sécurité des widgets. Voir cette version de la documentation pour intégrer l'extension.

Modifier le répertoire de stockage des widgets compilés

Vous pouvez utiliser la variable $wgWidgetsCompileDir pour modifier le répertoire de stockage des widgets compilés ($compile_dir dans le code). Le paramètre par défaut est

$wgWidgetsCompileDir = "$IP/extensions/Widgets/compiled_templates/";

Si vous modifiez l'emplacement en positionnant le paramètre sur un autre répertoire, assurez-vous que celui-ci existe et qu'il dispose des droits d'accès corrects.

Droits utilisateur

Cette extension ajoute l'espace de noms "Widget", mais à cause de conséquences potentielles sur la sécurité pouvant résulter de l'utilisation du code non sécurisé du widget, cet espace de noms ne peut être modifié que par les utilisateurs qui ont les droits editwidgets (le groupe widgeteditor est aussi créé pour lui ajouter des utilisateurs; voir la gestion des droits utilisateur pour plus de détails).

Utilisation

Pour ajouter un widget à votre installation MediaWiki, il suffit de créer une page dans l'espace de noms Widget:. Vous pouvez ensuite utiliser la fonction d'analyse {{#widget:...}} pour l'inclure dans n'importe quelle page du wiki.

Fonction d'analyseur {{#widget}}

Pour ajouter un widget défini aux pages, les utilisateurs peuvent utiliser la fonction d'analyse {{#widget}}. La syntaxe est la suivante :

{{#widget:WidgetName|param1=value1|param2=value2}}

où WidgetName est un nom de page dans l'espace de noms Widget (par exemple Widget:WidgetName) et les paires param=valeur sont les paramètres initialisables définis dans le code du widget.

Les paramètres peuvent être développés à l'intérieur d'un widget en utilisant la syntaxe Smarty, comme suit :

<a href="<!--{$param1|escape:'url'}-->"><!--{$param2|escape:'html'}--></a>

Les options escape spécifient la manière dont le paramètre sera échappé ou encodé dans le widget résultant. Il est essentiel que tous les paramètres soient échappés pour empêcher l'attaque des scripts intersites. Certaines méthodes d'échappement sont inefficaces. En général, vous devez utiliser une valeur parmi escape:html, escape:url, escape:urlpathinfo ou escape:javascript. Voir http://www.smarty.net/docsv2/en/language.modifier.escape pour plus d'informations à ce sujet.

Pages de l'espace de noms Widget

Tous les widgets du wiki sont définis en créant leur page dans l'espace de noms spécial Widget: comme par exemple Widget:WidgetName.

Pour voir tous les Widgets définis dans votre système, vous pouvez simplement aller à la page "Special:AllPages", sélectionner "Widget" dans l'espace de noms déroulant et cliquer sur "Go".

Pour des raisons de sécurité, ces pages ne peuvent être éditées que par les administrateurs du wiki - voir les droits utilisateur ci-dessus pour plus d'informations.

Vous trouverez de nombreux widgets prédéfinis à installer dans votre wiki sur MediaWikiWidgets.org. Si vous souhaitez créer vous-même des widgets, consultez la section suivante.

Syntaxe de la page Widget

L'extension Widgets utilise le moteur de modèle PHP Smarty pour fournir de simples fonctionnalité de modèle dans les pages de widget. Tous les paramètres passés à un widget sont convertis en paramètres Smarty.

Important : Utilisez les modificateurs d'échappement sur tous les paramètres passés, pour empêcher les utilisateurs de soumettre du HTML brut venant des pages wiki standard. Si vous ne protégez pas contre cela, le site d'hébergement sera exposé à des attaques XSS (et autres).

Tableaux

Si vous utilisez le même paramètre plusieurs fois, le widget recevra un tableau de valeurs. Vous pouvez utiliser foreach pour progresser dans le tableau.

Booléens (true/false)

En plus de la gestion par défaut des conversions booléennes PHP, vous pouvez (contrairement à PHP) utiliser les valeurs true ou false pour définir la valeur Boolean. Ceci initialisera par exemple le paramètre $popup à false :

{{#widget:WidgetName|popup=false}}

En outre, vous pouvez définir les paramètres Boolean à true en utilisant simplement un nom de paramètre sans valeur, comme ceci :

{{#widget:WidgetName|popup}}

Notation à points

Le nom des paramètres peut comporter des points, et Smarty les interprète alors comme des tableaux associatifs, vous pouvez donc utiliser foreach avec à la fois les attributs key et item pour passer, ou utiliser simplement le même nom avec des points si vous souhaitez référencer le paramètre directement.

Exemple

Widget:AssocTest pourrait ressembler à :

<includeonly><ul>
<!--{foreach from=$arg key=key item=item}-->
   <li><!--{$key|escape:'html'}-->: set to <!--{$item|escape:'html'}--></li>
<!--{/foreach}-->
</ul></includeonly>

...et vous pourriez appeler ce Widget ainsi :

{{#widget:AssocTest|arg.foo=bar|arg.bar=oni}}

...qui sera affiché comme :

• foo initialisé à bar
• bar initialisé à oni

Modificateur validate

En plus des modifieurs Smarty classiques (comme escape qui est utilisé intensément), l'extension Widgets implémente le modifieur validate, qui utilise le filtrage PHP des données permettant ainsi de valider les paramètres du widget. La validation d'un paramètre ne remplace pas l'échappement de celui-ci. Vous devez toujours utiliser un caractère d'échappement même lors de la validation. Pour la validation, les valeurs suivantes sont prises en charge (correspondance avec les filtres PHP de validation) :

• url — Valider en tant qu'URL. Ceci ne permet d'avoir que des schémas d'URL tels qu'ils figurent dans $wgUrlProtocols et à la différence de la validation PHP, les URL avec des caractères dangereux en HTML sont exclues.
• url-php (FILTER_VALIDATE_URL) — Attention : valider en tant qu'URL permet encore aux URL JavaScript d'accéder au XSS. Autorise également les URL avec des caractères non sécurisés en HTML.
• int (FILTER_VALIDATE_INT) — valide la valeur en tant qu'entier, optionnellement à partir de la plage spécifiée, et convertit en int.
• boolean or bool (FILTER_VALIDATE_BOOLEAN) — Renvoie true pour 1, true, on et yes. Renvoie false sinon.
• float (FILTER_VALIDATE_FLOAT) — valide la valeur en tant que flottant, optionnellement à partir de la plage spécifiée, et la convertit en flottant.
• email (FILTER_VALIDATE_EMAIL) — Attention : une adresse courriel valide peut toujours contenir des caractères dangereux en HTML; assurez-vous d'échapper les caractères en plus de la validation
• ip (FILTER_VALIDATE_IP) — valide la valeur en tant qu'adresse IP, optionnellement uniquement en IPv4 ou en IPv6 ou non, à partir de plages privées ou réservées.
• domain (FILTER_VALIDATE_DOMAIN) — Attention : les domaines valides peuvent toujours contenir des caractères qui ne sont pas sûrs en HTML; assurez-vous d'échapper les caractères en plus de la validation.
• mac (FILTER_VALIDATE_MAC) — valide la valeur en tant qu'adresse MAC.

Undefined parameters

If the widget expects a parameter but that parameter remains undefined in the parser function, a PHP error will be thrown. They're hidden by default, but if they're visible on your wiki, it might say something like Attempting to read property "value" on null in [...]. One way to prevent an error from showing despite undefined parameters is to add default:'' to widget parameters that are at risk of remaining undefined. For an example, see param2 below:

<a href="<!--{$param1|escape:'url'}-->" class="<!--{$param2|default:''|escape:'html'}-->"><!--{$param3|escape:'html'}--></a>

Rafraîchir une page de widget

Si vous faites appel au widget dans la page du widget lui-même, vous ne verrez pas le widget mis à jour (ni aucun autre widget, si vous venez de créer une page). Cela se produit parce que le contenu de la page n'est pas disponible pour l'extension Widgets tant que la page n'est pas sauvegardée, mais l'appel à la fonction d'analyse {{#widget}} est réalisé avant que la page ne soit enregistrée. Une fois la page sauvegardée, elle est mise en cache par MediaWiki, vous ne verrez donc pas le résultat même si vous chargez la page via le navigateur. Pour rendre effectifs les dernières modifications du code du widget, vous devez rafraîchir la page dans le cache; pour cela, il suffit d'utiliser l'action purger (voir aussi l'extension Purge), ou attendre un certain temps (jusqu'à 24 heures).

Widgets et modèles

Placer les widgets dans des modèles en fait un outil inestimable pour créer des affichages complexes de données avec un nombre de lignes de code minimal.

C'est particulièrement utile si vous souhaitez préinitialiser des paramètres du widget tout en permettant aux utilisateurs de modifier les autres (par exemple l'identifiant vidéo du widget YouTube ou le nom d'utilisateur du widget Twitter).

Auteurs

L'extension widgets a été créée et conçue par Sergey Chernyshev. Il est actuellement maintenue par Yaron Koren, qui a également contribué à la base de code.

D'autres contributions importantes ont été apportées par Alexandre Emsenhuber, Jeroen De Dauw, Joshua Lerner, Majr, Sam Reed et Tim Starling.

Historique des versions

L'extension Widgets est actuellement en version 1.6.0. Voir l'intégralité de l'historique des versions.

Widgets contributeurs

Si vous avez créé un widget et que vous souhaitez le partager, n'hésitez pas à le publier sur le site web MediaWikiWidgets.org et à y ajouter sur cette page, sa référence dans la bibliothèque de widget.

Bogues et demandes de fonctionnalités

Si vous rencontrez un problème, ou voulez contribuer à une correction, ou encore demander une nouvelle fonctionnalité, n'hésitez pas à rédiger une demande dans l'outil Wikimedia de suivi des bogues :

https://phabricator.wikimedia.org/maniphest/task/create/?projects=MediaWiki-extensions-Widgets

Résolution des problèmes

Il existe quelques problèmes communs que les utilisateurs rencontrent lorsqu'ils commencent à utiliser l'extension Widgets - nous allons essayer de les documenter ici :

• Sur une page de widget, juste après l'avoir créé (ou copié à partir de MediaWikiWidgets.org) vous voyez le message :

Warning: Smarty error: unable to read resource: "Widget:<your-widget-name>" /../extensions/Widgets/
smarty/Smarty.class.php on line 1095

Ceci est le plus souvent causé par le widget qui n'existe pas encore au moment où la page du widget elle-même est traitée - pour résoudre cela, il suffit de purger la page, par exemple, d'ajouter &action=purge (ou ?action=purge si vous avez des URL courtes) à l'URL.

Il est également possible que le Widget n'ait pas été appelé de la bonne façon. Les noms des pages de widget sont sensibles à la casse et doivent correspondre au nom du widget que vous appelez. Par exemple, n'utilisez pas {{#widget:Youtube|...}} quand le widget s'appelle Widget:YouTube, et vice versa.

• Si la page ne se charge pas et que vous voyez le message d'erreur suivant dans le fichier journal :

PHP Fatal error:  Smarty error: unable to write to $compile_dir '/../extensions/Widgets/compiled_templates'.
Be sure $compile_dir is writable by the web server user. in /../extensions/Widgets/smarty/Smarty.class.php on line 1095,
referer: https://your-wiki.com/Widget:<your-widget-name>

Vérifiez si vous avez modifié les droits et le propriétaire pour que Smarty puisse y stocker les modèles compilés. Voir aussi ce billet pour plus de détails.

• Si votre wiki envoie des pages totalement vides ou des erreurs 500 après une mise à jour vers MediaWiki 1.20 ou une version ultérieure, essayez de définir les autorisations sur /../extensions/Widgets/compiled_templates à 777.

Bibliothèque de widgets

MediaWikiWidgets.org contient une bibliothèque complète de widgets déjà prêts à l'emploi, avec le support pour la plupart des principaux sites vidéo. Tout widget peut être utilisé en copiant simplement le contenu sur la page.

Pour obtenir la liste la plus récente des widgets par fonction, par exemple par médiz social, par vidéo, images, etc. [$url cliquez ici]. click here.

Extensions qui peuvent être remplacées par des widgets

Nous rassemblons une liste d'extensions qui peuvent être remplacées par des widgets parce qu'elles ne font que produire du HTML/JS/CSS avec des paramètres et une logique simple pouvant être réalisée à l'aide de modèles Smarty.

Peut-être quelqu'un viendra créer un widget pour cela qui simplifiera le déploiement. En outre, ces listes d'extensions sont une bonne source d'action :

• Extension:YouTube
• Extension:PDFEmbed

Foire aux questions

Comment aligner une vidéo à droite avec les autres images ?

Utilisez quelque chose comme ceci. Notez que les balises de rupture de ligne ‎<br /> doivent être ajoutées manuellement. 180px est utilisé pour la largeur car c'est la valeur par défaut pour les vignettes. 150px est utilisé pour la hauteur parce que cela garde le même ratio que pour le 350x420 par défaut.

<div class="thumb tright">
<div class="thumbinner">
{{#widget: YouTube |width=180px |height=150px |id=qRhitIPEr0Y }}<br>
<div class="thumbcaption">
Seeing bad acting sully a good<br>
script can upset some people<br>
who place a high value on<br>
natural-seeming performances.<br>
</div>
</div>
</div>

Voir aussi

• Restrictions HTML - liste des extensions qui permettent l'inclusion de HTML brut