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ří. Content objects are generally, but not necessarily, immutable.
 * The  class, representing the knowledge about the specifics of a content model without access to concrete Content. Most importantly, instances of ContentHandler act as a factory for Content objects and provide serialization/deserialization. ContentHandler objects are stateless singletons, one for each content model.

The ContentHandler is also used to generate suitable instances of subclasses of,  ,  , etc. This way, a specialized UI for each content type can easily be plugged in through the ContentHandler interface.

All code that accesses the revision text in any way should be changed to use the methods provided by the Content object instead. Core classes that provide access the revision text (most importantly,  and  ) have been adapted to provide access to the appropriate Content object instead of the text.

Backward compatibility
The assumption that pages contain wikitext is widespread through the MediaWiki code base. To remain compatible with parts of the code that still assume this, especially with extensions, is thus quite important. The right way to provide good compatibility is of course not to change public interfaces. Thus, all methods providing access to the revision content (like, etc.) remain in place, and are complemented with an alternative method that allows access to the content object instead (e.g. ). The text-based methods are now deprecated, but shall function exactly as before for all pages/revisions that contain wikitext. This is also true for the action API.

A convenience method,, is provided to make it easy to retrieve a page's text. For flat text-based content models such as wikitext (but also JS and CSS),  will just return the text, so the old text-based method will return the same as it did before for such revisions. However, in case a text-based backwards-compatible method is called on a page/revision that does not contain wikitext (or another flat text content model, such a CSS), the behavior depends on the setting of : ignore makes it return null, fail causes it to raise an exception, and serialize causes it to return the default serialization of the content. The default is ignore, which is probably the most conservative option in most scenarios.

For editing however, non-text content is not supported per default. and the respective handlers in the action API will fail for non-textual content.

Links

 * and  classes :


 * Settings :


 * Extensions using ContentHandler :
 * How to add a new content model with an extension:
 * Basic example: Extension:Markdown
 * The extension
 * — a list of all content models (both in core and extensions)
 * — a list of all content models (both in core and extensions)