3 * This program is free software; you can redistribute it and/or modify
4 * it under the terms of the GNU General Public License as published by
5 * the Free Software Foundation; either version 2 of the License, or
6 * (at your option) any later version.
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * GNU General Public License for more details.
13 * You should have received a copy of the GNU General Public License along
14 * with this program; if not, write to the Free Software Foundation, Inc.,
15 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
16 * http://www.gnu.org/copyleft/gpl.html
21 use Wikimedia\WrappedString
;
22 use Wikimedia\WrappedStringList
;
25 * New base template for a skin's template extended from QuickTemplate
26 * this class features helper methods that provide common ways of interacting
27 * with the data stored in the QuickTemplate
29 abstract class BaseTemplate
extends QuickTemplate
{
32 * Get a Message object with its context set
34 * @param string $name Message name
35 * @param mixed $params,... Message params
38 public function getMsg( $name /* ... */ ) {
39 return $this->getSkin()->msg( ...func_get_args() );
42 function msg( $str ) {
43 echo $this->getMsg( $str )->escaped();
48 * @warning You should never use this method. I18n messages should be escaped
49 * @deprecated 1.32 Use ->msg() or ->getMsg() instead.
50 * @suppress SecurityCheck-XSS
51 * @return-taint exec_html
53 function msgHtml( $str ) {
54 wfDeprecated( __METHOD__
, '1.32' );
55 echo $this->getMsg( $str )->text();
59 * @deprecated since 1.33 Use ->msg() or ->getMsg() instead.
61 function msgWiki( $str ) {
62 // TODO: Add wfDeprecated( __METHOD__, '1.33' ) after 1.33 got released
63 echo $this->getMsg( $str )->parseAsBlock();
67 * Create an array of common toolbox items from the data in the quicktemplate
68 * stored by SkinTemplate.
69 * The resulting array is built according to a format intended to be passed
70 * through makeListItem to generate the html.
73 function getToolbox() {
75 if ( isset( $this->data
['nav_urls']['whatlinkshere'] )
76 && $this->data
['nav_urls']['whatlinkshere']
78 $toolbox['whatlinkshere'] = $this->data
['nav_urls']['whatlinkshere'];
79 $toolbox['whatlinkshere']['id'] = 't-whatlinkshere';
81 if ( isset( $this->data
['nav_urls']['recentchangeslinked'] )
82 && $this->data
['nav_urls']['recentchangeslinked']
84 $toolbox['recentchangeslinked'] = $this->data
['nav_urls']['recentchangeslinked'];
85 $toolbox['recentchangeslinked']['msg'] = 'recentchangeslinked-toolbox';
86 $toolbox['recentchangeslinked']['id'] = 't-recentchangeslinked';
87 $toolbox['recentchangeslinked']['rel'] = 'nofollow';
89 if ( isset( $this->data
['feeds'] ) && $this->data
['feeds'] ) {
90 $toolbox['feeds']['id'] = 'feedlinks';
91 $toolbox['feeds']['links'] = [];
92 foreach ( $this->data
['feeds'] as $key => $feed ) {
93 $toolbox['feeds']['links'][$key] = $feed;
94 $toolbox['feeds']['links'][$key]['id'] = "feed-$key";
95 $toolbox['feeds']['links'][$key]['rel'] = 'alternate';
96 $toolbox['feeds']['links'][$key]['type'] = "application/{$key}+xml";
97 $toolbox['feeds']['links'][$key]['class'] = 'feedlink';
100 foreach ( [ 'contributions', 'log', 'blockip', 'emailuser',
101 'userrights', 'upload', 'specialpages' ] as $special
103 if ( isset( $this->data
['nav_urls'][$special] ) && $this->data
['nav_urls'][$special] ) {
104 $toolbox[$special] = $this->data
['nav_urls'][$special];
105 $toolbox[$special]['id'] = "t-$special";
108 if ( isset( $this->data
['nav_urls']['print'] ) && $this->data
['nav_urls']['print'] ) {
109 $toolbox['print'] = $this->data
['nav_urls']['print'];
110 $toolbox['print']['id'] = 't-print';
111 $toolbox['print']['rel'] = 'alternate';
112 $toolbox['print']['msg'] = 'printableversion';
114 if ( isset( $this->data
['nav_urls']['permalink'] ) && $this->data
['nav_urls']['permalink'] ) {
115 $toolbox['permalink'] = $this->data
['nav_urls']['permalink'];
116 $toolbox['permalink']['id'] = 't-permalink';
118 if ( isset( $this->data
['nav_urls']['info'] ) && $this->data
['nav_urls']['info'] ) {
119 $toolbox['info'] = $this->data
['nav_urls']['info'];
120 $toolbox['info']['id'] = 't-info';
123 // Avoid PHP 7.1 warning from passing $this by reference
125 Hooks
::run( 'BaseTemplateToolbox', [ &$template, &$toolbox ] );
130 * Create an array of personal tools items from the data in the quicktemplate
131 * stored by SkinTemplate.
132 * The resulting array is built according to a format intended to be passed
133 * through makeListItem to generate the html.
134 * This is in reality the same list as already stored in personal_urls
135 * however it is reformatted so that you can just pass the individual items
136 * to makeListItem instead of hardcoding the element creation boilerplate.
139 function getPersonalTools() {
140 $personal_tools = [];
141 foreach ( $this->get( 'personal_urls' ) as $key => $plink ) {
142 # The class on a personal_urls item is meant to go on the <a> instead
143 # of the <li> so we have to use a single item "links" array instead
144 # of using most of the personal_url's keys directly.
147 [ 'single-id' => "pt-$key" ],
151 if ( isset( $plink['active'] ) ) {
152 $ptool['active'] = $plink['active'];
154 foreach ( [ 'href', 'class', 'text', 'dir', 'data', 'exists' ] as $k ) {
155 if ( isset( $plink[$k] ) ) {
156 $ptool['links'][0][$k] = $plink[$k];
159 $personal_tools[$key] = $ptool;
161 return $personal_tools;
164 function getSidebar( $options = [] ) {
165 // Force the rendering of the following portals
166 $sidebar = $this->data
['sidebar'];
167 if ( !isset( $sidebar['SEARCH'] ) ) {
168 $sidebar['SEARCH'] = true;
170 if ( !isset( $sidebar['TOOLBOX'] ) ) {
171 $sidebar['TOOLBOX'] = true;
173 if ( !isset( $sidebar['LANGUAGES'] ) ) {
174 $sidebar['LANGUAGES'] = true;
177 if ( !isset( $options['search'] ) ||
$options['search'] !== true ) {
178 unset( $sidebar['SEARCH'] );
180 if ( isset( $options['toolbox'] ) && $options['toolbox'] === false ) {
181 unset( $sidebar['TOOLBOX'] );
183 if ( isset( $options['languages'] ) && $options['languages'] === false ) {
184 unset( $sidebar['LANGUAGES'] );
188 foreach ( $sidebar as $boxName => $content ) {
189 if ( $content === false ) {
192 switch ( $boxName ) {
194 // Search is a special case, skins should custom implement this
197 'header' => $this->getMsg( 'search' )->text(),
198 'generated' => false,
203 $msgObj = $this->getMsg( 'toolbox' );
206 'header' => $msgObj->exists() ?
$msgObj->text() : 'toolbox',
207 'generated' => false,
208 'content' => $this->getToolbox(),
212 if ( $this->data
['language_urls'] !== false ) {
213 $msgObj = $this->getMsg( 'otherlanguages' );
216 'header' => $msgObj->exists() ?
$msgObj->text() : 'otherlanguages',
217 'generated' => false,
218 'content' => $this->data
['language_urls'] ?
: [],
223 $msgObj = $this->getMsg( $boxName );
225 'id' => "p-$boxName",
226 'header' => $msgObj->exists() ?
$msgObj->text() : $boxName,
228 'content' => $content,
234 // HACK: Compatibility with extensions still using SkinTemplateToolboxEnd
235 $hookContents = null;
236 if ( isset( $boxes['TOOLBOX'] ) ) {
238 // We pass an extra 'true' at the end so extensions using BaseTemplateToolbox
239 // can abort and avoid outputting double toolbox links
240 // Avoid PHP 7.1 warning from passing $this by reference
242 Hooks
::run( 'SkinTemplateToolboxEnd', [ &$template, true ] );
243 $hookContents = ob_get_contents();
245 if ( !trim( $hookContents ) ) {
246 $hookContents = null;
251 if ( isset( $options['htmlOnly'] ) && $options['htmlOnly'] === true ) {
252 foreach ( $boxes as $boxName => $box ) {
253 if ( is_array( $box['content'] ) ) {
255 foreach ( $box['content'] as $key => $val ) {
256 $content .= "\n " . $this->makeListItem( $key, $val );
258 // HACK, shove the toolbox end onto the toolbox if we're rendering itself
259 if ( $hookContents ) {
260 $content .= "\n $hookContents";
263 $content .= "\n</ul>\n";
264 $boxes[$boxName]['content'] = $content;
267 } elseif ( $hookContents ) {
268 $boxes['TOOLBOXEND'] = [
269 'id' => 'p-toolboxend',
270 'header' => $boxes['TOOLBOX']['header'],
271 'generated' => false,
272 'content' => "<ul>{$hookContents}</ul>",
274 // HACK: Make sure that TOOLBOXEND is sorted next to TOOLBOX
276 foreach ( $boxes as $key => $box ) {
277 if ( $key === 'TOOLBOXEND' ) {
280 $boxes2[$key] = $box;
281 if ( $key === 'TOOLBOX' ) {
282 $boxes2['TOOLBOXEND'] = $boxes['TOOLBOXEND'];
293 * @param string $name
295 protected function renderAfterPortlet( $name ) {
296 echo $this->getAfterPortlet( $name );
300 * Allows extensions to hook into known portlets and add stuff to them
302 * @param string $name
304 * @return string html
307 protected function getAfterPortlet( $name ) {
310 Hooks
::run( 'BaseTemplateAfterPortlet', [ $this, $name, &$content ] );
312 if ( $content !== '' ) {
313 $html = Html
::rawElement(
315 [ 'class' => [ 'after-portlet', 'after-portlet-' . $name ] ],
324 * Makes a link, usually used by makeListItem to generate a link for an item
325 * in a list used in navigation lists, portlets, portals, sidebars, etc...
327 * @param string $key Usually a key from the list you are generating this
329 * @param array $item Contains some of a specific set of keys.
331 * The text of the link will be generated either from the contents of the
332 * "text" key in the $item array, if a "msg" key is present a message by
333 * that name will be used, and if neither of those are set the $key will be
334 * used as a message name.
336 * If a "href" key is not present makeLink will just output htmlescaped text.
337 * The "href", "id", "class", "rel", and "type" keys are used as attributes
338 * for the link if present.
340 * If an "id" or "single-id" (if you don't want the actual id to be output
341 * on the link) is present it will be used to generate a tooltip and
342 * accesskey for the link.
344 * The keys "context" and "primary" are ignored; these keys are used
345 * internally by skins and are not supposed to be included in the HTML
348 * If you don't want an accesskey, set $item['tooltiponly'] = true;
350 * If a "data" key is present, it must be an array, where the keys represent
351 * the data-xxx properties with their provided values. For example,
356 * will render as element properties:
357 * data-foo='1' data-bar='baz'
359 * @param array $options Can be used to affect the output of a link.
360 * Possible options are:
361 * - 'text-wrapper' key to specify a list of elements to wrap the text of
362 * a link in. This should be an array of arrays containing a 'tag' and
363 * optionally an 'attributes' key. If you only have one element you don't
364 * need to wrap it in another array. eg: To use <a><span>...</span></a>
365 * in all links use [ 'text-wrapper' => [ 'tag' => 'span' ] ]
367 * - 'link-class' key can be used to specify additional classes to apply
369 * - 'link-fallback' can be used to specify a tag to use instead of "<a>"
370 * if there is no link. eg: If you specify 'link-fallback' => 'span' than
371 * any non-link will output a "<span>" instead of just text.
375 function makeLink( $key, $item, $options = [] ) {
376 $text = $item['text'] ??
wfMessage( $item['msg'] ??
$key )->text();
378 $html = htmlspecialchars( $text );
380 if ( isset( $options['text-wrapper'] ) ) {
381 $wrapper = $options['text-wrapper'];
382 if ( isset( $wrapper['tag'] ) ) {
383 $wrapper = [ $wrapper ];
385 while ( count( $wrapper ) > 0 ) {
386 $element = array_pop( $wrapper );
387 $html = Html
::rawElement( $element['tag'], $element['attributes'] ??
null, $html );
391 if ( isset( $item['href'] ) ||
isset( $options['link-fallback'] ) ) {
393 foreach ( [ 'single-id', 'text', 'msg', 'tooltiponly', 'context', 'primary',
394 'tooltip-params', 'exists' ] as $k ) {
398 if ( isset( $attrs['data'] ) ) {
399 foreach ( $attrs['data'] as $key => $value ) {
400 $attrs[ 'data-' . $key ] = $value;
402 unset( $attrs[ 'data' ] );
405 if ( isset( $item['id'] ) && !isset( $item['single-id'] ) ) {
406 $item['single-id'] = $item['id'];
410 if ( isset( $item['tooltip-params'] ) ) {
411 $tooltipParams = $item['tooltip-params'];
414 if ( isset( $item['single-id'] ) ) {
415 $tooltipOption = isset( $item['exists'] ) && $item['exists'] === false ?
'nonexisting' : null;
417 if ( isset( $item['tooltiponly'] ) && $item['tooltiponly'] ) {
418 $title = Linker
::titleAttrib( $item['single-id'], $tooltipOption, $tooltipParams );
419 if ( $title !== false ) {
420 $attrs['title'] = $title;
423 $tip = Linker
::tooltipAndAccesskeyAttribs(
428 if ( isset( $tip['title'] ) && $tip['title'] !== false ) {
429 $attrs['title'] = $tip['title'];
431 if ( isset( $tip['accesskey'] ) && $tip['accesskey'] !== false ) {
432 $attrs['accesskey'] = $tip['accesskey'];
436 if ( isset( $options['link-class'] ) ) {
437 if ( isset( $attrs['class'] ) ) {
438 $attrs['class'] .= " {$options['link-class']}";
440 $attrs['class'] = $options['link-class'];
443 $html = Html
::rawElement( isset( $attrs['href'] )
445 : $options['link-fallback'], $attrs, $html );
452 * Generates a list item for a navigation, portlet, portal, sidebar... list
454 * @param string $key Usually a key from the list you are generating this link from.
455 * @param array $item Array of list item data containing some of a specific set of keys.
456 * The "id", "class" and "itemtitle" keys will be used as attributes for the list item,
457 * if "active" contains a value of true a "active" class will also be appended to class.
459 * @param array $options
461 * If you want something other than a "<li>" you can pass a tag name such as
462 * "tag" => "span" in the $options array to change the tag used.
463 * link/content data for the list item may come in one of two forms
464 * A "links" key may be used, in which case it should contain an array with
465 * a list of links to include inside the list item, see makeLink for the
466 * format of individual links array items.
468 * Otherwise the relevant keys from the list item $item array will be passed
469 * to makeLink instead. Note however that "id" and "class" are used by the
470 * list item directly so they will not be passed to makeLink
471 * (however the link will still support a tooltip and accesskey from it)
472 * If you need an id or class on a single link you should include a "links"
473 * array with just one link item inside of it. You can also set "link-class" in
474 * $item to set a class on the link itself. If you want to add a title
475 * to the list item itself, you can set "itemtitle" to the value.
476 * $options is also passed on to makeLink calls
480 function makeListItem( $key, $item, $options = [] ) {
481 if ( isset( $item['links'] ) ) {
483 foreach ( $item['links'] as $linkKey => $link ) {
484 $links[] = $this->makeLink( $linkKey, $link, $options );
486 $html = implode( ' ', $links );
489 // These keys are used by makeListItem and shouldn't be passed on to the link
490 foreach ( [ 'id', 'class', 'active', 'tag', 'itemtitle' ] as $k ) {
493 if ( isset( $item['id'] ) && !isset( $item['single-id'] ) ) {
494 // The id goes on the <li> not on the <a> for single links
495 // but makeSidebarLink still needs to know what id to use when
496 // generating tooltips and accesskeys.
497 $link['single-id'] = $item['id'];
499 if ( isset( $link['link-class'] ) ) {
500 // link-class should be set on the <a> itself,
501 // so pass it in as 'class'
502 $link['class'] = $link['link-class'];
503 unset( $link['link-class'] );
505 $html = $this->makeLink( $key, $link, $options );
509 foreach ( [ 'id', 'class' ] as $attr ) {
510 if ( isset( $item[$attr] ) ) {
511 $attrs[$attr] = $item[$attr];
514 if ( isset( $item['active'] ) && $item['active'] ) {
515 if ( !isset( $attrs['class'] ) ) {
516 $attrs['class'] = '';
518 $attrs['class'] .= ' active';
519 $attrs['class'] = trim( $attrs['class'] );
521 if ( isset( $item['itemtitle'] ) ) {
522 $attrs['title'] = $item['itemtitle'];
524 return Html
::rawElement( $options['tag'] ??
'li', $attrs, $html );
527 function makeSearchInput( $attrs = [] ) {
531 'placeholder' => wfMessage( 'searchsuggest-search' )->text(),
533 $realAttrs = array_merge( $realAttrs, Linker
::tooltipAndAccesskeyAttribs( 'search' ), $attrs );
534 return Html
::element( 'input', $realAttrs );
537 function makeSearchButton( $mode, $attrs = [] ) {
544 'value' => wfMessage( $mode == 'go' ?
'searcharticle' : 'searchbutton' )->text(),
546 $realAttrs = array_merge(
548 Linker
::tooltipAndAccesskeyAttribs( "search-$mode" ),
551 return Html
::element( 'input', $realAttrs );
557 $buttonAttrs = array_merge(
559 Linker
::tooltipAndAccesskeyAttribs( 'search-fulltext' ),
562 unset( $buttonAttrs['src'] );
563 unset( $buttonAttrs['alt'] );
564 unset( $buttonAttrs['width'] );
565 unset( $buttonAttrs['height'] );
567 'src' => $attrs['src'],
568 'alt' => $attrs['alt'] ??
wfMessage( 'searchbutton' )->text(),
569 'width' => $attrs['width'] ??
null,
570 'height' => $attrs['height'] ??
null,
572 return Html
::rawElement( 'button', $buttonAttrs, Html
::element( 'img', $imgAttrs ) );
574 throw new MWException( 'Unknown mode passed to BaseTemplate::makeSearchButton' );
579 * Returns an array of footerlinks trimmed down to only those footer links that
581 * If you pass "flat" as an option then the returned array will be a flat array
582 * of footer icons instead of a key/value array of footerlinks arrays broken
583 * up into categories.
584 * @param string|null $option
585 * @return array|mixed
587 function getFooterLinks( $option = null ) {
588 $footerlinks = $this->get( 'footerlinks' );
590 // Reduce footer links down to only those which are being used
591 $validFooterLinks = [];
592 foreach ( $footerlinks as $category => $links ) {
593 $validFooterLinks[$category] = [];
594 foreach ( $links as $link ) {
595 if ( isset( $this->data
[$link] ) && $this->data
[$link] ) {
596 $validFooterLinks[$category][] = $link;
599 if ( count( $validFooterLinks[$category] ) <= 0 ) {
600 unset( $validFooterLinks[$category] );
604 if ( $option == 'flat' ) {
605 // fold footerlinks into a single array using a bit of trickery
606 $validFooterLinks = array_merge( ...array_values( $validFooterLinks ) );
609 return $validFooterLinks;
613 * Returns an array of footer icons filtered down by options relevant to how
614 * the skin wishes to display them.
615 * If you pass "icononly" as the option all footer icons which do not have an
616 * image icon set will be filtered out.
617 * If you pass "nocopyright" then MediaWiki's copyright icon will not be included
618 * in the list of footer icons. This is mostly useful for skins which only
619 * display the text from footericons instead of the images and don't want a
620 * duplicate copyright statement because footerlinks already rendered one.
621 * @param string|null $option
624 function getFooterIcons( $option = null ) {
625 // Generate additional footer icons
626 $footericons = $this->get( 'footericons' );
628 if ( $option == 'icononly' ) {
629 // Unset any icons which don't have an image
630 foreach ( $footericons as &$footerIconsBlock ) {
631 foreach ( $footerIconsBlock as $footerIconKey => $footerIcon ) {
632 if ( !is_string( $footerIcon ) && !isset( $footerIcon['src'] ) ) {
633 unset( $footerIconsBlock[$footerIconKey] );
637 // Redo removal of any empty blocks
638 foreach ( $footericons as $footerIconsKey => &$footerIconsBlock ) {
639 if ( count( $footerIconsBlock ) <= 0 ) {
640 unset( $footericons[$footerIconsKey] );
643 } elseif ( $option == 'nocopyright' ) {
644 unset( $footericons['copyright']['copyright'] );
645 if ( count( $footericons['copyright'] ) <= 0 ) {
646 unset( $footericons['copyright'] );
654 * Renderer for getFooterIcons and getFooterLinks
656 * @param string $iconStyle $option for getFooterIcons: "icononly", "nocopyright"
657 * @param string $linkStyle $option for getFooterLinks: "flat"
659 * @return string html
662 protected function getFooter( $iconStyle = 'icononly', $linkStyle = 'flat' ) {
663 $validFooterIcons = $this->getFooterIcons( $iconStyle );
664 $validFooterLinks = $this->getFooterLinks( $linkStyle );
668 if ( count( $validFooterIcons ) +
count( $validFooterLinks ) > 0 ) {
669 $html .= Html
::openElement( 'div', [
670 'id' => 'footer-bottom',
671 'role' => 'contentinfo',
672 'lang' => $this->get( 'userlang' ),
673 'dir' => $this->get( 'dir' )
675 $footerEnd = Html
::closeElement( 'div' );
679 foreach ( $validFooterIcons as $blockName => $footerIcons ) {
680 $html .= Html
::openElement( 'div', [
681 'id' => Sanitizer
::escapeIdForAttribute( "f-{$blockName}ico" ),
682 'class' => 'footer-icons'
684 foreach ( $footerIcons as $icon ) {
685 $html .= $this->getSkin()->makeFooterIcon( $icon );
687 $html .= Html
::closeElement( 'div' );
689 if ( count( $validFooterLinks ) > 0 ) {
690 $html .= Html
::openElement( 'ul', [ 'id' => 'f-list', 'class' => 'footer-places' ] );
691 foreach ( $validFooterLinks as $aLink ) {
692 $html .= Html
::rawElement(
694 [ 'id' => Sanitizer
::escapeIdForAttribute( $aLink ) ],
698 $html .= Html
::closeElement( 'ul' );
701 $html .= $this->getClear() . $footerEnd;
707 * Get a div with the core visualClear class, for clearing floats
709 * @return string html
712 protected function getClear() {
713 return Html
::element( 'div', [ 'class' => 'visualClear' ] );
717 * Get the suggested HTML for page status indicators: icons (or short text snippets) usually
718 * displayed in the top-right corner of the page, outside of the main content.
720 * Your skin may implement this differently, for example by handling some indicator names
721 * specially with a different UI. However, it is recommended to use a `<div class="mw-indicator"
722 * id="mw-indicator-<id>" />` as a wrapper element for each indicator, for better compatibility
723 * with extensions and user scripts.
725 * The raw data is available in `$this->data['indicators']` as an associative array (keys:
726 * identifiers, values: contents) internally ordered by keys.
728 * @return string HTML
731 public function getIndicators() {
732 $out = "<div class=\"mw-indicators mw-body-content\">\n";
733 foreach ( $this->data
['indicators'] as $id => $content ) {
734 $out .= Html
::rawElement(
737 'id' => Sanitizer
::escapeIdForAttribute( "mw-indicator-$id" ),
738 'class' => 'mw-indicator',
750 function printTrail() {
751 echo $this->getTrail();
755 * Get the basic end-page trail including bottomscripts, reporttime, and
756 * debug stuff. This should be called right before outputting the closing
757 * body and html tags.
759 * @return string|WrappedStringList HTML
762 public function getTrail() {
763 return WrappedString
::join( "\n", [
764 MWDebug
::getDebugHTML( $this->getSkin()->getContext() ),
765 $this->get( 'bottomscripts' ),
766 $this->get( 'reporttime' )