Manuel:ContentHandler

La fonctionnalité ContentHandler est un mécanisme qui permet la prise en charge de types de contenu arbitraires sur les pages wiki, plutôt que de faire référence au wikicode à chaque fois. Elle a été développée comme partie du projet Wikidata et se trouve dans le noyau MediaWiki depuis la version 1.21.

Pour la présentation canonique de l'architecture du ContentHandler, voir ContentHandler dans la documentation du code de MediaWiki.

Gestionnaires de contenu donne la liste des gestionnaires de contenu disponibles.

À propos

Le raisonnement derrière ce changement radical est que, si l'on se réfère au wikicode pour chaque contenu, on en arrive a faire des choses assez lourdes dans MediaWiki. La nouvelle architecture greffable pour les types arbitraires de contenu de page va nous permettre nous l'espérons de :

• utiliser un language de balisage différent sur certaines ou sur toutes les pages, comme le tex ou le markdown.
• se débarasser des cas particuliers pour les pages CSS et les pages JavaScript
• enregistrer et mettre à jour les données de configuration structurées d'une manière plus facile que par exemple celle utilisée par les extensions de Gadget sur MediaWiki:Gadgets-definition, ou le LanguageConverter sur les pages MediaWiki:Conversiontable***.
• fournir des pièces jointes aux pages de wikicode, par exemple pour les coordonnées géographiques (en utilisant un modèle de contenu multiparties pour les pages, similaire aux pièces jointes des courriels, en utilisant le format multiparties des messages).
   Note : Ceci n'a jamais été concrétisé et maintenant est remplacé par les Multi-Content Revisions (MCR).
• faire la transition vers un système où les catégories, etc. ne sont pas maintenues dans le wikicode lui-même, bien qu'elles restent stockées et versionnées de manière habituelle (là aussi, en utilisant un modèle de contenu multiparties).
• enregistrer pour Wikidata les données structurées facilement et de manière native comme contenu de page.

Idée de conception

L'idée est de stocker les autres types de données exactement de la même manière que le wikicode aujourd'hui, mais en indiquant à MediaWiki le type du contenu qu'il rencontre sur chacune des pages. Ainsi, tout type de données peut être utilisé comme le contenu d'une page wiki et enregistré et versionné exactement comme avant. Pour réaliser ceci, le noyau MediaWiki a implémenté les éléments suivants :

• suivre le modèle de contenu de chaque page. Ceci est fait principalement dans la table page de la base de données (aussi dans les tables revision et archive), et rendu accessible au travers des classes du noyau telles que Title, Revision et WikiPage. Le modèle de contenu définit le format natif du contenu, sous forme de chaînes de caractères, dans une structure de tableaux imbriqués, ou un objet PHP. Toutes les opérations sur le contenu sont réalisées sur cette forme native.
• suivre le format du contenu (format de sérialisation) de chaque version. Ceci est fait principalement dans la table revision de la base de données (aussi dans la table archive mais pas dans page), et rendu accessible au travers des classes du noyau telles que Revision. Notez que le format de sérialisation est seulement significatif quand la révision est chargée ou enregistrée, aucune opération n'est réalisée sur la forme sérialisée du contenu.
  •  Note : Dans le cas d'un contenu à plat (tel que le wikicode), la forme native du contenu est la même chose que la forme sérialisée (en clair, c'est une chaîne). Néanmoins on peut concevoir que, à l'avenir, la forme native du wikicode soit une forme de AST ou de DOM.
  •  Note : La table page enregistre le modèle de contenu pour la version actuelle, alors que revision enregistre le modèle de contenu et le format de sérialisation. Le modèle et le format peuvent changer en théorie selon la version, mais cela ne serait pas compréhensible, ni significatif avec les diffs.

Cela signifie que tout code devant réaliser une opération sur le contenu doit connaître la forme native de ce contenu. Cette connaissance est encapsulée en utilisant un environnement greffable de gestionnaires et reposant sur deux classes :

• La classe Content représente le contenu comme tel, et fournit une interface pour toutes les opérations standard à réaliser sur la forme native du contenu. Elle n'a aucune connaissance de la page ni de la version à laquelle le contenu appartient. Les objets de contenu sont généralement non mutables, mais pas nécessairement.
• La classe ContentHandler, représente la connaissance sur les spécificités d'un modèle de contenu sans accéder concrètement à la partie Content. Le plus important est que les instances de ContentHandler agissent en tant que factory pour les objets Content et fournissent la sérialisation et la désérialisation. Les objets ContentHandler sont des singletons sans état, un singleton par modèle de contenu.

ContentHandler est également utilisé pour générer des instances compatibles des sous-classes de Article, EditPage, DifferenceEngine, etc. De cette façon, une interface utilisateur spécialisée pour chaque type de contenu peut être facilement greffée via l'interface ContentHandler.

Tout code qui accède au texte de la révision de quelque manière que ce soit, doit être remplacé pour utiliser les méthodes fournies par l'objet Content. Les classes du noyau qui fournissent l'accès au texte de la révision (principalement Revision et WikiPage) ont été adaptées pour donner accès à l'objet Content approprié plutôt qu'au texte.

Compatibilité arrière

La supposition que les pages contiennent du wikicode est largement connue dans la base de code de MediaWiki. Ceci est très important pour rester compatible avec les parties de code qui supposent encore cela, particulièrement les extensions. La bonne manière de fournir une bonne compatibilité est bien sûr de ne pas modifier les interfaces publiques. Ainsi toutes les méthodes qui donnent accès au contenu de la révision (comme Revision::getText(), etc.) restent en place, et sont complétées par une méthode alternative permettant à la place, d'accéder à l'objet Content (comme Revision::getContent()). Les méthodes basées sur le texte sont maintenant obsolètes, mais elles fonctionnent exactement comme avant pour toutes les pages et les versions qui contiennent du wikicode. Ceci est vrai aussi pour l'API action.

Une méthode pratique ContentHandler::getContentText(), est fournie pour faciliter la récupération du texte des pages. Pour les modèles de contenu basés sur du texte à plat tel que le wikicode (mais aussi JS et CSS), getContentText() va simplement renvoyer le texte, donc l'ancienne méthode basée sur le texte va renvoyer la même chose qu'avant pour ces révisions. Néanmoins dans le cas d'une méthode basée sur le texte et compatible arrière, si elle est appelée pour une page ou une révision qui ne contient pas de wikicode (ou tout autre modèle de contenu textuel à plat, tel que CSS), le comportement dépend de la valeur de $wgContentHandlerTextFallback : ignore fait qu'elle renverra 'null', fail fait qu'elle lèvera une exception, et avec serialize elle va renvoyer le contenu sérialisé par défaut. La valeur par défaut est ignore, qui est probablement l'option la plus conservative dans la plupart des scenarios.

Néanmoins pour les modifications, le contenu non textuel n'est pas pris en charge par défaut. EditPage et les gestionnaires respectifs de l'API Action vont échouer si le contenu n'est pas textuel.

Liens

Classes Content et ContentHandler

• Content.php
• ContentHandler.php

Paramètres

• $wgContentHandlers
• $wgContentHandlerTextFallback
• $wgNamespaceContentModels

Extensions qui utilisent ContentHandler

• Comment ajouter un nouveau modèle de contenu avec une extension : Modèles de pages de contenu
• Exemple de base : Extension:Markdown
• Catégorie:Extensions liées à ContentHandler
• Extension Examples
• Gestionnaires de contenu — liste de tous les modèles de contenu (y compris dans le noyau et dans les extensions)

Support du code

• Maintenu par Unknown or Unassigned^{[‍Maintainers page]}.
• Suivi des problèmes : Phabricator MediaWiki-ContentHandler (rapporter un problème)