CustomData-Extension

From Tech

[edit] Goals

The CustomData extension provides an easy to use interface for other extensions that need to transfer data retrieved from the parser to the skin.

It doesn't make sense to install this extension without any client extension.

[edit] Download

Download from svn:mediawiki/trunk/extensions/CustomData.

Copy CustomData.php into the CustomData folder in the extensions folder of your MediaWiki installation. Since this extension is a pure backend for other extensions, no modifications of your LocalSettings.php file are required.

[edit] License

GPL.

[edit] ParserOutput class

After the Parser class has extracted all relevant data out of the wiki markup, it saves it's output in the ParserOutput object. The ParserOutput is cached either in the database or by an extern caching server. Thus, wiki markup only needs to be parsed once, usualy when an article is saved.

When you push the "save" button after having edited an article, your browser sends a POST request to the server. There, the edited wiki markup is parsed and saved in the database. The server responds with a 300 (Moved) HTTP code that tells your browser to send a new GET request that loads the new version of the edited article. It is important to understand that all information about a previously saved article comes out of the cache, not from the actual wiki markup.

This means that extensions that need to process additional data need to store them inside the ParserOutput object after having parsed the wiki markup. Unfortunately, there is (not yet) a custom data field in the ParserOutput object. That's what the CustomData extension does. It is a little hack that adds such a custom data field to the ParserOutput object and provides a handy API for other extensions.

[edit] OutputPage class

All cached ParserOutput data that is needed to build up the final HTML page are merged into the OutputPage. The CustomData API makes extraction of custom data from the OutputPage object easy.

[edit] SkinTemplate and QuickTemplate

Every Skin inherited from the SkinTemplate class, e.g. SkinMonobook, uses a data collection class inherited from QuickTemplate. If you want to modify the Skin in order to display your custom data, you need to store your data somewhere in the QuickTemplate object, first. Fortunately, there is a hook called 'SkinTemplateOutputPageBeforeExec' usefull to inject custom data into the QuickTemplate. Extensions that use the CustomData extension as backend should have a function or method triggered by this hook. From this function, you can call the CustomData object's getPageData() method for getting your data stored in the global OutputPage object (usualy $wgOut). After having processed your data, just call the setSkinData() method of the CustomData object in order to store your data in the QuickTemplate object.

Now you can hook into some of the Skin object hooks an call the getSkinData() method of the CustomData object for retrieving your data for HTML output.

[edit] Installation

• Copy extensions/CustomData/CustomData.php into your extensions folder
• Insert "require_once( "$IP/extensions/CustomData/CustomData.php" );" either in your LocalSettings.php or better in your extension that relies on the CustomData extension.

[edit] The API

[edit] Functions

 function setParserData( &$ParserOutput, $key, $value)

If your extension uses parser hooks, you need to store your custom data by invoking setParserData in order to make it survive the subsequent GET request. You can choose an arbitrary, but unique, string as $key. $value might be of mixed type.

 function &getPageData( &$OutputPage, $key)

This is how to get your custom data back.

 function setSkinData( &$QuickTmpl, $key, $value)

Save your custom data for final HTML output. You can use the SkinTemplateOutputPageBeforeExec hook for triggering your function. The $key need not to be (but might be) the same as used in setParserData.

 function &getSkinData( &$QuickTmpl, $key)

Call this from a function triggered by an appropriate Skin hook.