Příručka:ContentHandler

Prvek ContentHandler je mechanismus pro podporu libovolných typů obsahu na wiki stránkách, namísto ve všem se spoléhání na wikitext. Byl vyvinut jako součást projektu Wikidata a je součástí jádra MediaWiki od verze 1.21.

Základní přehled architektury ContentHandler naleznete na stránce ContentHandler v dokumentaci kódu MediaWiki.

Seznam dostupných obslužných programů obsahu viz Modely obsahu stránky .

Obecné informace

Důvodem této poměrně radikální změny je, že nucení spoléhat se na wikitext u veškerého obsahu dělá spoustu věcí v MediaWiki značně těžkopádnými. Nová zásuvná architektura pro libovolné typy obsahu stránek nám snad umožní:

• na některých nebo všech stránkách použít jiný značkovací jazyk, například TeX nebo Markdown.
• odstranit speciální případy pro stránky CSS a JavaScript.
• ukládat a upravovat strukturovaná konfigurační data citlivějším způsobem než např. co používá rozšíření Gadgets na MediaWiki:Gadgets-definition nebo LanguageConverter na MediaWiki:Conversiontable*** stránkách.
• poskytovat datové "přílohy" ke stránkám wikitextu, např. pro geodata (používá se "vícedílný" obsahový model pro stránku, podobně jako jsou implementovány e-mailové přílohy pomocí vícedílného formátu zprávy) (Poznámka: toto se nikdy neuskutečnilo a nyní bylo nahrazeno Multi-Content Revisions .)
• přechod na systém, kde kategorie atd. nejsou udržovány v samotném wikitextu, zatímco jsou stále ukládány a verzovány obvyklým způsobem (opět pomocí vícedílného modelu obsahu).
• ukládat strukturovaná data pro Wikidata snadno a nativně jako obsah stránky.

Vývojový nápad

Cílem je ukládat jiné druhy dat přesně stejným způsobem, jako je v současnosti ukládán wikitext, ale upozornit MediaWiki na typ obsahu, s nímž na každé stránce pracuje. Tímto způsobem lze jako obsah wiki stránky použít jakýkoli druh dat a ta by byla uložena a verzována přesně jako dříve. Za tímto účelem bylo do jádra MediaWiki implementováno následující:

• sledování modelu obsahu každé stránky. To se provádí primárně v tabulce page v databázi (také v tabulkách revision a archive) a zpřístupňuje se prostřednictvím příslušných základních tříd, jako jsou Title, Revision a WikiPage. Model obsahu definuje přirozenou formu obsahu, s jíž je řetězec obsahující text, vnořená struktura polí nebo objekt PHP. Všechny operace s obsahem se provádějí v jeho původní podobě.
• sledování formát obsahu (formát serializace) každé revize. To se provádí primárně v tabulce revision v databázi (také v tabulce archive, ale ne v tabulce page) a zpřístupňuje se prostřednictvím příslušných základních tříd, jako je Revision. Všimněte si, že formát serializace je relevantní pouze při načítání a ukládání revize, se serializovanou formou obsahu se neprovádějí žádné operace.
  • Poznámka: V případě plochého textového obsahu (jako je wikitext) je nativní forma obsahu stejná jako serializovaná forma (jmenovitě řetězec). Je však možné, že přirozenou (nativní) formou wikitextu by v budoucnu mohla být nějaká forma AST nebo DOM.
  • Poznámka: Tabulka page zaznamenává model obsahu pro aktuální revizi, zatímco tabulka revision zaznamenává model obsahu a formát serializace. Model a formát se teoreticky mohou měnit od revize k revizi, i když to může být matoucí a neumožňuje to smysluplné rozdíly.

To znamená, že veškerý kód, který potřebuje provést jakoukoli operaci s obsahem, si musí být vědom nativní formy obsahu. Tyto znalosti jsou zapouzdřeny pomocí vloženého rámce obslužných programů, založených na dvou třídách:

• Třída Content představuje obsah jako takový a poskytuje rozhraní pro všechny standardní operace, které se mají provádět v nativní formě obsahu. Nemá žádné znalosti o stránce nebo revizi obsahu, které patří. Objekty obsahu jsou obecně, ale ne nutně, neměnné.
• Třída ContentHandler představující znalosti o specifikách modelu obsahu bez přístupu ke konkrétnímu obsahu. Nejdůležitější je, že instance ContentHandler fungují jako továrna na objekty obsahu a poskytují serializaci/deserializaci. Objekty ContentHandler jsou bezstavové unikáty, jeden pro každý model obsahu.

ContentHandler se také používá ke generování vhodných instancí podtříd Article, EditPage, DifferenceEngine atd. Tímto způsobem lze snadno připojit specializované uživatelské rozhraní pro každý typ obsahu prostřednictvím rozhraní ContentHandler.

Veškerý kód, který jakýmkoli způsobem přistupuje k textu revize, by měl být změněn tak, aby místo toho používal metody poskytované objektem Content. Základní třídy, které poskytují přístup k textu revize (co je nejdůležitější, Revision a WikiPage), byly upraveny tak, aby poskytovaly přístup k příslušnému objektu Content namísto textu.

Zpětná kompatibilita

Předpoklad, že stránky obsahují wikitext, je rozšířený prostřednictvím kódové základny MediaWiki. Zůstat kompatibilní s částmi kódu, které to stále předpokládají, zejména s rozšířeními, je tedy docela důležité. Správným způsobem zajištění dobré kompatibility je samozřejmě neměnit veřejná rozhraní. Všechny metody poskytující přístup k obsahu revize (jako Revision::getText() atd.) tedy zůstávají na svém místě a jsou doplněny alternativní metodou, která místo toho umožňuje přístup k objektu obsahu (např. Revision::getContent()). Textové metody jsou nyní zastaralé, ale budou fungovat přesně jako dříve pro všechny stránky/revize, které obsahují wikitext. To platí také pro akční API.

K dispozici je pohodlný způsob, ContentHandler::getContentText(), který usnadňuje načtení textu stránky. U modelů plochého textového obsahu, jako je wikitext (ale také JS a CSS), getContentText() pouze vrátí text, takže stará textová metoda vrátí totéž, co dříve pro takové revize. V případě, že je však na stránce/revizi volána zpětně kompatibilní metoda založená na textu, která neobsahuje wikitext (nebo jiný model plochého textového obsahu, jako je CSS), chování závisí na nastavení $wgContentHandlerTextFallback: ignore způsobí, že vrátí hodnotu null, fail způsobí, že vyvolá výjimku a serialize způsobí, že vrátí výchozí serializaci obsahu. Výchozí hodnota je ignorovat, což je pravděpodobně nejkonzervativnější možnost ve většině scénářů.

Pro úpravy však není ve výchozím nastavení podporován netextový obsah. EditPage a příslušné obslužné rutiny v rozhraní API akce selžou pro netextový obsah.

Odkazy

třídy Content a ContentHandler

• Content.php
• ContentHandler.php

Nastavení

• $wgContentHandlers
• $wgContentHandlerTextFallback
• $wgNamespaceContentModels

Rozšíření použití ContentHandler

• Jak přidat nový model obsahu s rozšířením: Modely obsahu stránek
• Základní příklad: Extension:Markdown
• Kategorie:Rozšíření pro zpracování obsahu
• Rozšíření Examples
• Modely obsahu stránky — seznam všech modelů obsahu (jak v jádru, tak v rozšířeních)

Správce kódu

• Spravováno Unknown or Unassigned^{[‍Maintainers page]}.
• Nástroj pro sledování problémů: Phabricator MediaWiki-ContentHandler (nahlášení problému)