Manual:QuickTemplate.php
- Maybe you were looking for help on wiki templates instead?
| MediaWiki file: QuickTemplate.php | |
|---|---|
| Location: | includes/skins/ |
| Source code: | master • 1.41.1 • 1.40.3 • 1.39.7 |
| Classes: | QuickTemplate |
The QuickTemplate class separates the front-end user interface (UI) from backend stuff.
It has an abstract execute() function which shows the actual HTML of the page.
The SkinTemplate class, which is the parent class of most skins, sets up a QuickTemplate instance with many key-value pairs, such as 'articlepath', 'loggedin', and 'titletxt', and invokes execute().
Most skins define their own template class that extends BaseTemplate which extends QuickTemplate; BaseTemplate defines additional useful functions for skins, such as getIndicators(), makeSearchInput(), etc.
Using QuickTemplate in extensions
Let's say that you're writing a new special page with a pretty UI and all that. It can prove quite difficult to do that with MediaWiki's Xml and Html classes. It is possible to use QuickTemplate in such cases.
MySpecialPage.php
You need to register the template class with MediaWiki's autoloader in your extension's setup file.
$wgAutoloadClasses['MySpecialPageTemplate'] = __DIR__ . '/MySpecialPageTemplate.php';
MySpecialPage.body.php
<?php
/**
* Main class for MySpecialPage example extension.
*
* @file
* @ingroup Extensions
*/
class SpecialMySpecialPage extends SpecialPage {
/**
* @var string $userName The current user's username
*/
private $userName;
/**
* Constructor -- set up the new special page
*/
public function __construct() {
$this->userName = $this->getUser()->getName(); // Define the private class member variable
parent::__construct( 'MySpecialPage' );
}
/**
* Show the special page
*
* @param mixed|null $par Parameter passed to the special page or null
*/
public function execute( $par ) {
global $wgArticlePath;
// Maybe check for user block/DB lock state and permissions here...
// It's up to you, really.
// Set page title etc. stuff
$this->setHeaders();
// Begin actual template stuff
$template = new MySpecialPageTemplate();
// Here we set the template variable 'foo', which in this case is a
// string ($wgArticlePath with '$1' being replaced by 'Foo')
$template->set( 'foo', str_replace( '$1', 'Foo', $wgArticlePath ) );
// $this is SpecialMySpecialPage object
$template->set( 'mySpecialClass', $this );
// Template variable 'randomKey' is a randomly generated method that
// the getRandomKey() method here defines for us.
// getRandomKey() is a private class method, so this is pretty much
// the only way we can use it outside this file/class
$template->set( 'randomKey', $this->getRandomKey() );
// In the template class, all the variables we define here can be
// accessed by using $this->data['variable_name']
// et voilà!
$this->getOutput()->addTemplate( $template );
}
/**
* Gets a randomly generated key.
*
* @return string
*/
private function getRandomKey() {
$key = md5( 'superRandomString-' . $this->userName );
return $key;
}
}
MySpecialPageTemplate.php
<?php
/**
* @file
*/
if ( !defined( 'MEDIAWIKI' ) ) {
die( -1 );
}
/**
* HTML template for Special:MySpecialPage
* @ingroup Templates
*/
class MySpecialPageTemplate extends QuickTemplate {
/**
* Main processing is done here.
*
* For proper i18n, use $this->getMsg( 'message-key' ) with the appropriate
* parameters (see [[Manual:Messages API]] on MediaWiki.org for further
* details).
* Because this is just an example, we're using hard-coded English text
* here. In your production-grade code, you obviously should be using the
* proper internationalization functions instead.
*/
public function execute() {
?>
<div id="MySpecialPageTemplate">
Your randomly generated secret key is: <?php echo $this->data['randomKey'] ?>
If you need to generate a new key, you can do so <a href="<?php echo htmlspecialchars( $this->data['mySpecialClass']->getPageTitle()->getFullURL() ) ?>">here</a>
</div>
<?php
} // execute()
} // class
We can use $this->data['mySpecialClass']->getPageTitle()->getFullURL() in the template class, because $this->data['mySpecialClass'] is a reference to the SpecialMySpecialPage object which extends the SpecialPage class (and SpecialPage class has the getPageTitle() method, which in turn returns a Title object, and the getFullURL() is a Title method).
Limitations
- This class does not provide a way to load ResourceLoader modules. For an example of a workaround, see the Chameleon skin.
Historical background
Ages ago, MediaWiki's skins weren't purely PHP, they required PHPTal.
When Brion Vibber rewrote the skin system to remove PHPTal dependency, SkinTemplate and QuickTemplate classes were introduced.
The QuickTemplate class became a "generic wrapper for template functions, with interface compatible with what we use of PHPTAL 0.7".
