Manual:ContentHandler/cs

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.

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 .)
 * 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 v databázi (také v tabulkách  a ) a zpřístupňuje se prostřednictvím příslušných základních tříd, jako jsou ,   a  . 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 v databázi (také v tabulce, ale ne v tabulce ) a zpřístupňuje se prostřednictvím příslušných základních tříd, jako je  . 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řizozenou (nativní) formou wikitextu by v budoucnu mohla být nějaká forma AST nebo DOM.
 * Poznámka: Tabulka zaznamenává model obsahu pro aktuální revizi, zatímco tabulka  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  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  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,  ,   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ší,  a  ), 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 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ř. ). 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,, který usnadňuje načtení textu stránky. U modelů plochého textového obsahu, jako je wikitext (ale také JS a CSS),  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í : 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. a příslušné obslužné rutiny v rozhraní API akce selžou pro netextový obsah.

Odkazy

 * třídy  a   :


 * Nastavení :


 * Rozšíření použití ContentHandler :
 * Jak přidat nový model obsahu s rozšířením:
 * Základní příklad: Extension:Markdown
 * Rozšíření
 * — seznam všech modelů obsahu (jak v jádru, tak v rozšířeních)
 * — seznam všech modelů obsahu (jak v jádru, tak v rozšířeních)

