View source for Manual:ContentHandler

<languages/>
{{ContentHandler}}
<translate><!--T:1--> The '''ContentHandler''' facility is a mechanism for supporting arbitrary content types on wiki pages, instead of relying on wikitext for everything.</translate>
<translate><!--T:2--> It was developed as part of the [[<tvar name=1>m:Special:MyLanguage/Wikidata</tvar>|Wikidata]] project and is part of the MediaWiki core since version 1.21.</translate>

<translate>
<!--T:3-->
For the canonical overview of the ContentHandler's architecture, see [<tvar name=url>https://doc.wikimedia.org/mediawiki-core/master/php/contenthandler.html</tvar> ContentHandler] in the MediaWiki code documentation.

<!--T:4-->
For a list of available content handlers, see <tvar name=1>{{ll|Content handlers}}</tvar>.

== About == <!--T:5-->
</translate>
<translate><!--T:6--> The rationale behind this rather radical change is that being forced to rely on wikitext for all content makes a lot of things quite cumbersome in MediaWiki.</translate>
<translate><!--T:7--> The new pluggable architecture for arbitrary types of page content will allow us to hopefully:</translate>

* <translate><!--T:8--> use a different markup language on some or all pages, like TeX or Markdown.</translate>
* <translate><!--T:9--> do away with special cases for CSS and JavaScript pages.</translate>
* <translate><!--T:10--> store and edit structured configuration data in a more sensible way than e.g. what the Gadgets extension uses on <tvar name=1>[[MediaWiki:Gadgets-definition]]</tvar> or the LanguageConverter on <tvar name=2>[[:zh:Special:PrefixIndex/MediaWiki:Conversiontable|MediaWiki:Conversiontable***]]</tvar> pages.</translate>
* <translate><!--T:11--> provide data "attachments" to wikitext pages, e.g. for geodata (using a "multipart" content model for the page, similar to the way email attachments are implemented using the multipart message format).</translate> <translate><!--T:12--> (Note: this never materialized, and has now been superseded by <tvar name=1>{{ll|Multi-Content Revisions}}</tvar>.)</translate>
* <translate><!--T:13--> transition to a system where categories etc are not maintained in the wikitext itself, while still being stored and versioned in the usual way (again, using a multipart content model).</translate>
* <translate><!--T:14--> store structured data for [[<tvar name=1>m:Special:MyLanguage/Wikidata</tvar>|Wikidata]] easily and natively as page content.</translate>

<translate>
== Design idea == <!--T:15-->
</translate>
<translate><!--T:16--> The idea is to store other kinds of data in exactly the same way as wikitext is stored currently, but make MediaWiki aware of the type of content it is dealing with for every page.</translate>
<translate><!--T:17--> This way, any kind of data can be used as the content of a wiki page, and it would be stored and versioned exactly as before.</translate>
<translate><!--T:18--> To achieve this, the following was implemented in the MediaWiki core:</translate>

* <translate><!--T:19--> keep track of the ''content model'' of every page.</translate> <translate><!--T:20--> This is done primarily in the <tvar name=1>{{db table|page}}</tvar> table in the database (also in the <tvar name=2>{{db table|revision}}</tvar> and <tvar name=3>{{db table|archive}}</tvar> tables), and made accessible through the relevant core classes such as <tvar name=4><code>Title</code></tvar>, <tvar name=5><code>RevisionRecord</code></tvar>, and <tvar name=6><code>WikiPage</code></tvar>.</translate> <translate><!--T:21--> The ''content model'' defines the ''native form'' of the content, be it a string containing text, a nested structure of arrays, or a PHP object.</translate> <translate><!--T:22--> All operations on the content are performed on its ''native form''.</translate>
* <translate><!--T:23--> keep track of the ''content format'' (serialization format) of every revision.</translate> <translate><!--T:24--> This is done primarily in the <tvar name=1>{{db table|revision}}</tvar> table in the database (also in the <tvar name=2>{{db table|archive}}</tvar> table, but not in the <tvar name=3>{{db table|page}}</tvar> table), and made accessible through the relevant core classes such as <tvar name=4><code>RevisionRecord</code></tvar>.</translate> <translate><!--T:25--> Note that the serialization format is only relevant when loading and storing the revision, no operations are performed on the serialized form of the content.</translate>
** <translate><!--T:26--> Note: in case of flat text content (such as wikitext), the native form of the content is the same as the serialized form (namely, a string).</translate> <translate><!--T:27--> However, conceivably, the native form of wikitext could be some form of AST or DOM in the future.</translate>
** <translate><!--T:28--> Note: the <tvar name=1>{{db table|page}}</tvar> table records the content model for the current revision, while the <tvar name=2>{{db table|revision}}</tvar> records the content model and serialization format.</translate> <translate><!--T:29--> Model and format may in theory both change from revision to revision, though this may be confusing, and doesn't allow for meaningful diffs.</translate>

<translate><!--T:30--> This means that all code that needs to perform any operation on the content must be aware of the content's native form.</translate>
<translate><!--T:31--> This knowledge is encapsulated using a pluggable framework of handlers, based on two classes:</translate>

* <translate><!--T:32--> The <tvar name=1><code>Content</code></tvar> class represents the content as such, and provides an interface for all standard operations to be performed on the content's native form.</translate> <translate><!--T:33--> It does not have any knowledge of the page or revision the content belongs to.</translate> <translate><!--T:34--> Content objects are generally, but not necessarily, immutable.</translate>
* <translate><!--T:35--> The <tvar name=1><code>ContentHandler</code></tvar> class, representing the knowledge about the specifics of a content model without access to concrete Content.</translate> <translate><!--T:36--> Most importantly, instances of ContentHandler act as a factory for Content objects and provide serialization/deserialization.</translate> <translate><!--T:37--> ContentHandler objects are stateless singletons, one for each content model.</translate>

<translate><!--T:38--> The ContentHandler is also used to generate suitable instances of subclasses of <tvar name=1><code>Article</code></tvar>, <tvar name=2><code>EditPage</code></tvar>, <tvar name=3><code>SlotDiffRenderer</code></tvar>, etc.</translate>
<translate><!--T:39--> This way, a specialized UI for each content type can easily be plugged in through the ContentHandler interface.</translate>

<translate><!--T:40--> All code that accesses the revision text in any way should be changed to use the methods provided by the Content object instead.</translate>
<translate><!--T:41--> Core classes that provide access the revision text (most importantly, <tvar name=1><code>RevisionRecord</code></tvar> and <tvar name=2><code>WikiPage</code></tvar>) have been adapted to provide access to the appropriate Content object instead of the text.</translate>

<translate>
== Backward compatibility == <!--T:42-->
</translate>
<translate><!--T:43--> 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.</translate>
<translate><!--T:44--> The right way to provide good compatibility is of course not to change public interfaces.</translate>
<translate><!--T:45--> Thus, all methods providing access to the revision content (like <tvar name=1>{{phpi|Revision::getText()}}</tvar>, etc.) remained in place, and are complemented with an alternative method that allows access to the content object instead (e.g. <tvar name=2>{{phpi|Revision::getContent()}}</tvar>).</translate>
<translate><!--T:46--> The text-based methods are now deprecated, but shall function exactly as before for all pages/revisions that contain wikitext.</translate>
<translate><!--T:47--> This is also true for the [[<tvar name=1>Special:MyLanguage/API:Main page</tvar>|action API]].</translate>

<translate><!--T:48--> A convenience method, <tvar name=1>{{phpi|ContentHandler::getContentText()}}</tvar>, is provided to make it easy to retrieve a page's text.</translate>
<translate><!--T:49--> For flat text-based content models such as wikitext (but also JS and CSS), <tvar name=1><code>getContentText()</code></tvar> will just return the text, so the old text-based method will return the same as it did before for such revisions.</translate>
<translate><!--T:50--> 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 methods return null.</translate>

<translate><!--T:52--> For editing however, non-text content is not supported per default.</translate>
<translate><!--T:53--> <tvar name=1><code>EditPage</code></tvar> and the respective handlers in the action API will fail for non-textual content.</translate>

<translate>

== Links == <!--T:54-->
</translate>
; <translate><!--T:55--> <tvar name=1><code>Content</code></tvar> and <tvar name=2><code>ContentHandler</code></tvar> classes</translate> :
* {{git file|project=mediawiki/core|branch=HEAD|file=includes/content/Content.php|text=Content.php}}
* {{git file|project=mediawiki/core|branch=HEAD|file=includes/content/ContentHandler.php|text=ContentHandler.php}}

; <translate><!--T:56--> Settings</translate> :
* {{ll|Manual:$wgContentHandlers|$wgContentHandlers}}
* {{ll|Manual:$wgContentHandlerTextFallback|$wgContentHandlerTextFallback}}
* {{ll|Manual:$wgNamespaceContentModels|$wgNamespaceContentModels}}

; <translate><!--T:57--> Extensions using ContentHandler</translate> :
* <translate><!--T:58--> How to add a new content model with an extension:</translate> {{ll|Manual:Page content models|nsp=0}}
* <translate><!--T:59--> Basic example:</translate> [https://github.com/brightbyte/MWExtension-Markdown Extension:Markdown]
* {{ll|Category:ContentHandler extensions}}
* <translate><!--T:60--> The <tvar name=1>{{ll|Extension:Examples|nsp=0}}</tvar> extension</translate>
* {{ll|Content handlers}} — <translate><!--T:61--> a list of all content models (both in core and extensions)</translate>

<translate>
== Code stewardship == <!--T:62-->
</translate>
{{Component|mediawiki-contenthandler}}

[[Category:MediaWiki development{{#translation:}}]]
[[Category:Data exchange with other systems{{#translation:}}]]
[[Category:Metadata{{#translation:}}]]
[[Category:ContentHandler{{#translation:}}]]
[[Category:Markup languages{{#translation:}}]]