3
* Collection of methods to generate HTML content
5
* Copyright © 2009 Aryeh Gregor
6
* http://www.mediawiki.org/
8
* This program is free software; you can redistribute it and/or modify
9
* it under the terms of the GNU General Public License as published by
10
* the Free Software Foundation; either version 2 of the License, or
11
* (at your option) any later version.
13
* This program is distributed in the hope that it will be useful,
14
* but WITHOUT ANY WARRANTY; without even the implied warranty of
15
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16
* GNU General Public License for more details.
18
* You should have received a copy of the GNU General Public License along
19
* with this program; if not, write to the Free Software Foundation, Inc.,
20
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
21
* http://www.gnu.org/copyleft/gpl.html
27
* This class is a collection of static functions that serve two purposes:
29
* 1) Implement any algorithms specified by HTML5, or other HTML
30
* specifications, in a convenient and self-contained way.
32
* 2) Allow HTML elements to be conveniently and safely generated, like the
33
* current Xml class but a) less confused (Xml supports HTML-specific things,
34
* but only sometimes!) and b) not necessarily confined to XML-compatible
37
* There are two important configuration options this class uses:
39
* $wgHtml5: If this is set to false, then all output should be valid XHTML 1.0
41
* $wgWellFormedXml: If this is set to true, then all output should be
42
* well-formed XML (quotes on attributes, self-closing tags, etc.).
44
* This class is meant to be confined to utility functions that are called from
45
* trusted code paths. It does not do enforcement of policy like not allowing
51
# List of void elements from HTML5, section 8.1.2 as of 2011-08-12
52
private static $voidElements = array(
71
# Boolean attributes, which may have the value omitted entirely. Manually
72
# collected from the HTML5 spec as of 2011-08-12.
73
private static $boolAttribs = array(
104
private static $HTMLFiveOnlyAttribs = array(
118
* Returns an HTML element in a string. The major advantage here over
119
* manually typing out the HTML is that it will escape all attribute
120
* values. If you're hardcoding all the attributes, or there are none, you
121
* should probably just type out the html element yourself.
123
* This is quite similar to Xml::tags(), but it implements some useful
124
* HTML-specific logic. For instance, there is no $allowShortTag
125
* parameter: the closing tag is magically omitted if $element has an empty
126
* content model. If $wgWellFormedXml is false, then a few bytes will be
127
* shaved off the HTML output as well.
129
* @param $element string The element's name, e.g., 'a'
130
* @param $attribs array Associative array of attributes, e.g., array(
131
* 'href' => 'http://www.mediawiki.org/' ). See expandAttributes() for
132
* further documentation.
133
* @param $contents string The raw HTML contents of the element: *not*
135
* @return string Raw HTML
137
public static function rawElement( $element, $attribs = array(), $contents = '' ) {
138
global $wgWellFormedXml;
139
$start = self::openElement( $element, $attribs );
140
if ( in_array( $element, self::$voidElements ) ) {
141
if ( $wgWellFormedXml ) {
143
return substr( $start, 0, -1 ) . ' />';
147
return "$start$contents" . self::closeElement( $element );
152
* Identical to rawElement(), but HTML-escapes $contents (like
155
* @param $element string
156
* @param $attribs array
157
* @param $contents string
161
public static function element( $element, $attribs = array(), $contents = '' ) {
162
return self::rawElement( $element, $attribs, strtr( $contents, array(
163
# There's no point in escaping quotes, >, etc. in the contents of
171
* Identical to rawElement(), but has no third parameter and omits the end
172
* tag (and the self-closing '/' in XML mode for empty elements).
174
* @param $element string
175
* @param $attribs array
179
public static function openElement( $element, $attribs = array() ) {
180
global $wgHtml5, $wgWellFormedXml;
181
$attribs = (array)$attribs;
182
# This is not required in HTML5, but let's do it anyway, for
183
# consistency and better compression.
184
$element = strtolower( $element );
186
# In text/html, initial <html> and <head> tags can be omitted under
187
# pretty much any sane circumstances, if they have no attributes. See:
188
# <http://www.whatwg.org/specs/web-apps/current-work/multipage/syntax.html#optional-tags>
189
if ( !$wgWellFormedXml && !$attribs
190
&& in_array( $element, array( 'html', 'head' ) ) ) {
194
# Remove HTML5-only attributes if we aren't doing HTML5, and disable
195
# form validation regardless (see bug 23769 and the more detailed
196
# comment in expandAttributes())
197
if ( $element == 'input' ) {
198
# Whitelist of types that don't cause validation. All except
199
# 'search' are valid in XHTML1.
214
if ( isset( $attribs['type'] )
215
&& !in_array( $attribs['type'], $validTypes ) ) {
216
unset( $attribs['type'] );
219
if ( isset( $attribs['type'] ) && $attribs['type'] == 'search'
221
unset( $attribs['type'] );
225
if ( !$wgHtml5 && $element == 'textarea' && isset( $attribs['maxlength'] ) ) {
226
unset( $attribs['maxlength'] );
229
return "<$element" . self::expandAttributes(
230
self::dropDefaults( $element, $attribs ) ) . '>';
234
* Returns "</$element>", except if $wgWellFormedXml is off, in which case
235
* it returns the empty string when that's guaranteed to be safe.
238
* @param $element string Name of the element, e.g., 'a'
239
* @return string A closing tag, if required
241
public static function closeElement( $element ) {
242
global $wgWellFormedXml;
244
$element = strtolower( $element );
247
# http://www.whatwg.org/specs/web-apps/current-work/multipage/syntax.html#optional-tags
248
if ( !$wgWellFormedXml && in_array( $element, array(
261
return "</$element>";
265
* Given an element name and an associative array of element attributes,
266
* return an array that is functionally identical to the input array, but
267
* possibly smaller. In particular, attributes might be stripped if they
268
* are given their default values.
270
* This method is not guaranteed to remove all redundant attributes, only
271
* some common ones and some others selected arbitrarily at random. It
272
* only guarantees that the output array should be functionally identical
273
* to the input array (currently per the HTML 5 draft as of 2009-09-06).
275
* @param $element string Name of the element, e.g., 'a'
276
* @param $attribs array Associative array of attributes, e.g., array(
277
* 'href' => 'http://www.mediawiki.org/' ). See expandAttributes() for
278
* further documentation.
279
* @return array An array of attributes functionally identical to $attribs
281
private static function dropDefaults( $element, $attribs ) {
282
# Don't bother doing anything if we aren't outputting HTML5; it's too
283
# much of a pain to maintain two sets of defaults.
289
static $attribDefaults = array(
290
'area' => array( 'shape' => 'rect' ),
292
'formaction' => 'GET',
293
'formenctype' => 'application/x-www-form-urlencoded',
300
'command' => array( 'type' => 'command' ),
303
'autocomplete' => 'on',
304
'enctype' => 'application/x-www-form-urlencoded',
307
'formaction' => 'GET',
311
'keygen' => array( 'keytype' => 'rsa' ),
312
'link' => array( 'media' => 'all' ),
313
'menu' => array( 'type' => 'list' ),
314
# Note: the use of text/javascript here instead of other JavaScript
315
# MIME types follows the HTML5 spec.
316
'script' => array( 'type' => 'text/javascript' ),
319
'type' => 'text/css',
321
'textarea' => array( 'wrap' => 'soft' ),
324
$element = strtolower( $element );
326
foreach ( $attribs as $attrib => $value ) {
327
$lcattrib = strtolower( $attrib );
328
$value = strval( $value );
330
# Simple checks using $attribDefaults
331
if ( isset( $attribDefaults[$element][$lcattrib] ) &&
332
$attribDefaults[$element][$lcattrib] == $value ) {
333
unset( $attribs[$attrib] );
336
if ( $lcattrib == 'class' && $value == '' ) {
337
unset( $attribs[$attrib] );
342
if ( $element === 'link' && isset( $attribs['type'] )
343
&& strval( $attribs['type'] ) == 'text/css' ) {
344
unset( $attribs['type'] );
346
if ( $element === 'select' && isset( $attribs['size'] ) ) {
347
if ( in_array( 'multiple', $attribs )
348
|| ( isset( $attribs['multiple'] ) && $attribs['multiple'] !== false )
351
if ( strval( $attribs['size'] ) == '4' ) {
352
unset( $attribs['size'] );
356
if ( strval( $attribs['size'] ) == '1' ) {
357
unset( $attribs['size'] );
366
* Given an associative array of element attributes, generate a string
367
* to stick after the element name in HTML output. Like array( 'href' =>
368
* 'http://www.mediawiki.org/' ) becomes something like
369
* ' href="http://www.mediawiki.org"'. Again, this is like
370
* Xml::expandAttributes(), but it implements some HTML-specific logic.
371
* For instance, it will omit quotation marks if $wgWellFormedXml is false,
372
* and will treat boolean attributes specially.
374
* Attributes that should contain space-separated lists (such as 'class') array
375
* values are allowed as well, which will automagically be normalized
376
* and converted to a space-separated string. In addition to a numerical
377
* array, the attribute value may also be an associative array. See the
378
* example below for how that works.
380
* @par Numerical array
382
* Html::element( 'em', array(
383
* 'class' => array( 'foo', 'bar' )
385
* // gives '<em class="foo bar"></em>'
388
* @par Associative array
390
* Html::element( 'em', array(
391
* 'class' => array( 'foo', 'bar', 'foo' => false, 'quux' => true )
393
* // gives '<em class="bar quux"></em>'
396
* @param $attribs array Associative array of attributes, e.g., array(
397
* 'href' => 'http://www.mediawiki.org/' ). Values will be HTML-escaped.
398
* A value of false means to omit the attribute. For boolean attributes,
399
* you can omit the key, e.g., array( 'checked' ) instead of
400
* array( 'checked' => 'checked' ) or such.
401
* @return string HTML fragment that goes between element name and '>'
402
* (starting with a space if at least one attribute is output)
404
public static function expandAttributes( $attribs ) {
405
global $wgHtml5, $wgWellFormedXml;
408
$attribs = (array)$attribs;
409
foreach ( $attribs as $key => $value ) {
410
if ( $value === false || is_null( $value ) ) {
414
# For boolean attributes, support array( 'foo' ) instead of
415
# requiring array( 'foo' => 'meaningless' ).
417
&& in_array( strtolower( $value ), self::$boolAttribs ) ) {
421
# Not technically required in HTML5, but required in XHTML 1.0,
422
# and we'd like consistency and better compression anyway.
423
$key = strtolower( $key );
425
# Here we're blacklisting some HTML5-only attributes...
426
if ( !$wgHtml5 && in_array( $key, self::$HTMLFiveOnlyAttribs )
431
# Bug 23769: Blacklist all form validation attributes for now. Current
432
# (June 2010) WebKit has no UI, so the form just refuses to submit
433
# without telling the user why, which is much worse than failing
434
# server-side validation. Opera is the only other implementation at
435
# this time, and has ugly UI, so just kill the feature entirely until
436
# we have at least one good implementation.
438
# As the default value of "1" for "step" rejects decimal
439
# numbers to be entered in 'type="number"' fields, allow
440
# the special case 'step="any"'.
442
if ( in_array( $key, array( 'max', 'min', 'pattern', 'required' ) ) ||
443
$key === 'step' && $value !== 'any' ) {
447
// http://www.w3.org/TR/html401/index/attributes.html ("space-separated")
448
// http://www.w3.org/TR/html5/index.html#attributes-1 ("space-separated")
449
$spaceSeparatedListAttributes = array(
450
'class', // html4, html5
451
'accesskey', // as of html5, multiple space-separated values allowed
452
// html4-spec doesn't document rel= as space-separated
453
// but has been used like that and is now documented as such
454
// in the html5-spec.
458
# Specific features for attributes that allow a list of space-separated values
459
if ( in_array( $key, $spaceSeparatedListAttributes ) ) {
460
// Apply some normalization and remove duplicates
462
// Convert into correct array. Array can contain space-seperated
463
// values. Implode/explode to get those into the main array as well.
464
if ( is_array( $value ) ) {
465
// If input wasn't an array, we can skip this step
468
foreach ( $value as $k => $v ) {
469
if ( is_string( $v ) ) {
470
// String values should be normal `array( 'foo' )`
472
if ( !isset( $value[$v] ) ) {
473
// As a special case don't set 'foo' if a
474
// separate 'foo' => true/false exists in the array
475
// keys should be authoritive
479
// If the value is truthy but not a string this is likely
480
// an array( 'foo' => true ), falsy values don't add strings
484
$value = implode( ' ', $newValue );
486
$value = explode( ' ', $value );
488
// Normalize spacing by fixing up cases where people used
489
// more than 1 space and/or a trailing/leading space
490
$value = array_diff( $value, array( '', ' ' ) );
492
// Remove duplicates and create the string
493
$value = implode( ' ', array_unique( $value ) );
496
# See the "Attributes" section in the HTML syntax part of HTML5,
497
# 9.1.2.3 as of 2009-08-10. Most attributes can have quotation
498
# marks omitted, but not all. (Although a literal " is not
499
# permitted, we don't check for that, since it will be escaped
502
# See also research done on further characters that need to be
503
# escaped: http://code.google.com/p/html5lib/issues/detail?id=93
504
$badChars = "\\x00- '=<>`/\x{00a0}\x{1680}\x{180e}\x{180F}\x{2000}\x{2001}"
505
. "\x{2002}\x{2003}\x{2004}\x{2005}\x{2006}\x{2007}\x{2008}\x{2009}"
506
. "\x{200A}\x{2028}\x{2029}\x{202F}\x{205F}\x{3000}";
507
if ( $wgWellFormedXml || $value === ''
508
|| preg_match( "![$badChars]!u", $value ) ) {
514
if ( in_array( $key, self::$boolAttribs ) ) {
515
# In XHTML 1.0 Transitional, the value needs to be equal to the
516
# key. In HTML5, we can leave the value empty instead. If we
517
# don't need well-formed XML, we can omit the = entirely.
518
if ( !$wgWellFormedXml ) {
520
} elseif ( $wgHtml5 ) {
521
$ret .= " $key=\"\"";
523
$ret .= " $key=\"$key\"";
526
# Apparently we need to entity-encode \n, \r, \t, although the
527
# spec doesn't mention that. Since we're doing strtr() anyway,
528
# and we don't need <> escaped here, we may as well not call
529
# htmlspecialchars().
530
# @todo FIXME: Verify that we actually need to
531
# escape \n\r\t here, and explain why, exactly.
533
# We could call Sanitizer::encodeAttribute() for this, but we
534
# don't because we're stubborn and like our marginal savings on
535
# byte size from not having to encode unnecessary quotes.
543
if ( $wgWellFormedXml ) {
544
# This is allowed per spec: <http://www.w3.org/TR/xml/#NT-AttValue>
545
# But reportedly it breaks some XML tools?
546
# @todo FIXME: Is this really true?
550
$ret .= " $key=$quote" . strtr( $value, $map ) . $quote;
557
* Output a <script> tag with the given contents. TODO: do some useful
558
* escaping as well, like if $contents contains literal '</script>' or (for
559
* XML) literal "]]>".
561
* @param $contents string JavaScript
562
* @return string Raw HTML
564
public static function inlineScript( $contents ) {
565
global $wgHtml5, $wgJsMimeType, $wgWellFormedXml;
570
$attrs['type'] = $wgJsMimeType;
573
if ( $wgWellFormedXml && preg_match( '/[<&]/', $contents ) ) {
574
$contents = "/*<![CDATA[*/$contents/*]]>*/";
577
return self::rawElement( 'script', $attrs, $contents );
581
* Output a <script> tag linking to the given URL, e.g.,
582
* <script src=foo.js></script>.
585
* @return string Raw HTML
587
public static function linkedScript( $url ) {
588
global $wgHtml5, $wgJsMimeType;
590
$attrs = array( 'src' => $url );
593
$attrs['type'] = $wgJsMimeType;
596
return self::element( 'script', $attrs );
600
* Output a <style> tag with the given contents for the given media type
601
* (if any). TODO: do some useful escaping as well, like if $contents
602
* contains literal '</style>' (admittedly unlikely).
604
* @param $contents string CSS
605
* @param $media mixed A media type string, like 'screen'
606
* @return string Raw HTML
608
public static function inlineStyle( $contents, $media = 'all' ) {
609
global $wgWellFormedXml;
611
if ( $wgWellFormedXml && preg_match( '/[<&]/', $contents ) ) {
612
$contents = "/*<![CDATA[*/$contents/*]]>*/";
615
return self::rawElement( 'style', array(
616
'type' => 'text/css',
622
* Output a <link rel=stylesheet> linking to the given URL for the given
623
* media type (if any).
626
* @param $media mixed A media type string, like 'screen'
627
* @return string Raw HTML
629
public static function linkedStyle( $url, $media = 'all' ) {
630
return self::element( 'link', array(
631
'rel' => 'stylesheet',
633
'type' => 'text/css',
639
* Convenience function to produce an <input> element. This supports the
640
* new HTML5 input types and attributes, and will silently strip them if
643
* @param $name string name attribute
644
* @param $value mixed value attribute
645
* @param $type string type attribute
646
* @param $attribs array Associative array of miscellaneous extra
647
* attributes, passed to Html::element()
648
* @return string Raw HTML
650
public static function input( $name, $value = '', $type = 'text', $attribs = array() ) {
651
$attribs['type'] = $type;
652
$attribs['value'] = $value;
653
$attribs['name'] = $name;
655
return self::element( 'input', $attribs );
659
* Convenience function to produce an input element with type=hidden
661
* @param $name string name attribute
662
* @param $value string value attribute
663
* @param $attribs array Associative array of miscellaneous extra
664
* attributes, passed to Html::element()
665
* @return string Raw HTML
667
public static function hidden( $name, $value, $attribs = array() ) {
668
return self::input( $name, $value, 'hidden', $attribs );
672
* Convenience function to produce an <input> element. This supports leaving
673
* out the cols= and rows= which Xml requires and are required by HTML4/XHTML
674
* but not required by HTML5 and will silently set cols="" and rows="" if
675
* $wgHtml5 is false and cols and rows are omitted (HTML4 validates present
676
* but empty cols="" and rows="" as valid).
678
* @param $name string name attribute
679
* @param $value string value attribute
680
* @param $attribs array Associative array of miscellaneous extra
681
* attributes, passed to Html::element()
682
* @return string Raw HTML
684
public static function textarea( $name, $value = '', $attribs = array() ) {
687
$attribs['name'] = $name;
690
if ( !isset( $attribs['cols'] ) ) {
691
$attribs['cols'] = "";
694
if ( !isset( $attribs['rows'] ) ) {
695
$attribs['rows'] = "";
699
if (substr($value, 0, 1) == "\n") {
700
// Workaround for bug 12130: browsers eat the initial newline
701
// assuming that it's just for show, but they do keep the later
702
// newlines, which we may want to preserve during editing.
703
// Prepending a single newline
704
$spacedValue = "\n" . $value;
706
$spacedValue = $value;
708
return self::element( 'textarea', $attribs, $spacedValue );
711
* Build a drop-down box for selecting a namespace
713
* @param $params array:
714
* - selected: [optional] Id of namespace which should be pre-selected
715
* - all: [optional] Value of item for "all namespaces". If null or unset, no <option> is generated to select all namespaces
716
* - label: text for label to add before the field
717
* @param $selectAttribs array HTML attributes for the generated select element.
718
* - id: [optional], default: 'namespace'
719
* - name: [optional], default: 'namespace'
720
* @return string HTML code to select a namespace.
722
public static function namespaceSelector( Array $params = array(), Array $selectAttribs = array() ) {
725
// Default 'id' & 'name' <select> attributes
726
$selectAttribs = $selectAttribs + array(
728
'name' => 'namespace',
730
ksort( $selectAttribs );
732
// Is a namespace selected?
733
if ( isset( $params['selected'] ) ) {
734
// If string only contains digits, convert to clean int. Selected could also
735
// be "all" or "" etc. which needs to be left untouched.
736
// PHP is_numeric() has issues with large strings, PHP ctype_digit has other issues
737
// and returns false for already clean ints. Use regex instead..
738
if ( preg_match( '/^\d+$/', $params['selected'] ) ) {
739
$params['selected'] = intval( $params['selected'] );
741
// else: leaves it untouched for later processing
743
$params['selected'] = '';
746
// Array holding the <option> elements
749
if ( isset( $params['all'] ) ) {
750
// add an <option> that would let the user select all namespaces.
751
// Value is provided by user, the name shown is localized.
752
$options[$params['all']] = wfMsg( 'namespacesall' );
754
// Add defaults <option> according to content language
755
$options += $wgContLang->getFormattedNamespaces();
757
// Convert $options to HTML
758
$optionsHtml = array();
759
foreach ( $options as $nsId => $nsName ) {
760
if ( $nsId < NS_MAIN ) {
764
$nsName = wfMsg( 'blanknamespace' );
766
$optionsHtml[] = Xml::option( $nsName, $nsId, $nsId === $params['selected'] );
769
// Forge a <select> element and returns it
771
if ( isset( $params['label'] ) ) {
772
$ret .= Xml::label( $params['label'], $selectAttribs['id'] ) . ' ';
774
$ret .= Html::openElement( 'select', $selectAttribs )
776
. implode( "\n", $optionsHtml )
778
. Html::closeElement( 'select' );
783
* Constructs the opening html-tag with necessary doctypes depending on
786
* @param $attribs array Associative array of miscellaneous extra
787
* attributes, passed to Html::element() of html tag.
788
* @return string Raw HTML
790
public static function htmlHeader( $attribs = array() ) {
795
if ( self::isXmlMimeType( $wgMimeType ) ) {
796
$ret .= "<?xml version=\"1.0\" encoding=\"UTF-8\" ?" . ">\n";
799
global $wgHtml5, $wgHtml5Version, $wgDocType, $wgDTD;
800
global $wgXhtmlNamespaces, $wgXhtmlDefaultNamespace;
803
$ret .= "<!DOCTYPE html>\n";
805
if ( $wgHtml5Version ) {
806
$attribs['version'] = $wgHtml5Version;
809
$ret .= "<!DOCTYPE html PUBLIC \"$wgDocType\" \"$wgDTD\">\n";
810
$attribs['xmlns'] = $wgXhtmlDefaultNamespace;
812
foreach ( $wgXhtmlNamespaces as $tag => $ns ) {
813
$attribs["xmlns:$tag"] = $ns;
817
$html = Html::openElement( 'html', $attribs );
829
* Determines if the given mime type is xml.
831
* @param $mimetype string MimeType
834
public static function isXmlMimeType( $mimetype ) {
835
switch ( $mimetype ) {
837
case 'application/xhtml+xml':
838
case 'application/xml':
846
* Get HTML for an info box with an icon.
848
* @param $text String: wikitext, get this with wfMsgNoTrans()
849
* @param $icon String: icon name, file in skins/common/images
850
* @param $alt String: alternate text for the icon
851
* @param $class String: additional class name to add to the wrapper div
852
* @param $useStylePath
856
static function infoBox( $text, $icon, $alt, $class = false, $useStylePath = true ) {
859
if ( $useStylePath ) {
860
$icon = $wgStylePath.'/common/images/'.$icon;
863
$s = Html::openElement( 'div', array( 'class' => "mw-infobox $class") );
865
$s .= Html::openElement( 'div', array( 'class' => 'mw-infobox-left' ) ).
866
Html::element( 'img',
872
Html::closeElement( 'div' );
874
$s .= Html::openElement( 'div', array( 'class' => 'mw-infobox-right' ) ).
876
Html::closeElement( 'div' );
877
$s .= Html::element( 'div', array( 'style' => 'clear: left;' ), ' ' );
879
$s .= Html::closeElement( 'div' );
881
$s .= Html::element( 'div', array( 'style' => 'clear: left;' ), ' ' );