This class is a collection of static functions that serve two purposes: More...

Static Public Member Functions
static	addClass (&$classes, string $class)
	Add a class to a 'class' attribute in a format accepted by Html::element().

static	buttonAttributes (array $attrs, array $modifiers=[])
	Modifies a set of attributes meant for button elements.

static	check ( $name, $checked=false, array $attribs=[])
	Convenience function to produce a checkbox (input element with type=checkbox)

static	closeElement ( $element)
	Returns "</$element>".

static	element ( $element, $attribs=[], $contents='')
	Identical to rawElement(), but HTML-escapes $contents (like Xml::element()).

static	encodeJsCall ( $name, $args, $pretty=false)
	Create a call to a JavaScript function.

static	encodeJsList ( $args, $pretty=false)
	Encode a JavaScript comma-separated list.

static	encodeJsVar ( $value, $pretty=false)
	Encode a variable of arbitrary type to JavaScript.

static	errorBox ( $html, $heading='', $className='')
	Return an error box.

static	expandAttributes (array $attribs)
	Given an associative array of element attributes, generate a string to stick after the element name in HTML output.

static	expandClassList ( $classes)
	Convert a value for a 'class' attribute in a format accepted by Html::element() and similar methods to a single string.

static	getTextInputAttributes (array $attrs)
	Modifies a set of attributes meant for text input elements.

static	hidden ( $name, $value, array $attribs=[])
	Convenience function to produce an input element with type=hidden.

static	htmlHeader (array $attribs=[])
	Constructs the opening html-tag with necessary doctypes depending on global variables.

static	inlineScript ( $contents, $nonce=null)
	Output an HTML script tag with the given contents.

static	inlineStyle ( $contents, $media='all', $attribs=[])
	Output a "<style>" tag with the given contents for the given media type (if any).

static	input ( $name, $value='', $type='text', array $attribs=[])
	Convenience function to produce an `<input>` element.

static	isXmlMimeType ( $mimetype)
	Determines if the given MIME type is xml.

static	label ( $label, $id, array $attribs=[])
	Convenience function for generating a label for inputs.

static	linkButton ( $text, array $attrs, array $modifiers=[])
	Returns an HTML link element in a string.

static	linkedScript ( $url, $nonce=null)
	Output a "<script>" tag linking to the given URL, e.g., "<script src=foo.js></script>".

static	linkedStyle ( $url, $media='all')
	Output a "<link rel=stylesheet>" linking to the given URL for the given media type (if any).

static	listDropdownOptions ( $list, $params=[])
	Build options for a drop-down box from a textual list.

static	listDropdownOptionsCodex ( $options)
	Convert options for a drop-down box into a format accepted by OOUI\DropdownInputWidget etc.

static	listDropdownOptionsOoui ( $options)
	Convert options for a drop-down box into a format accepted by OOUI\DropdownInputWidget etc.

static	namespaceSelector (array $params=[], array $selectAttribs=[])
	Build a drop-down box for selecting a namespace.

static	namespaceSelectorOptions (array $params=[])
	Helper for Html::namespaceSelector().

static	noticeBox ( $html, $className, $heading='', $iconClassName='')
	Return the HTML for a notice message box.

static	openElement ( $element, $attribs=[])
	Identical to rawElement(), but has no third parameter and omits the end tag (and the self-closing '/' in XML mode for empty elements).

static	radio ( $name, $checked=false, array $attribs=[])
	Convenience function to produce a radio button (input element with type=radio)

static	rawElement ( $element, $attribs=[], $contents='')
	Returns an HTML element in a string.

static	srcSet (array $urls)
	Generate a srcset attribute value.

static	submitButton ( $contents, array $attrs=[], array $modifiers=[])
	Returns an HTML input element in a string.

static	successBox ( $html, $className='')
	Return a success box.

static	textarea ( $name, $value='', array $attribs=[])
	Convenience function to produce a <textarea> element.

static	warningBox ( $html, $className='')
	Return a warning box.

Detailed Description

This class is a collection of static functions that serve two purposes:

1) Implement any algorithms specified by HTML5, or other HTML specifications, in a convenient and self-contained way.

2) Allow HTML elements to be conveniently and safely generated, like the current Xml class but a) less confused (Xml supports HTML-specific things, but only sometimes!) and b) not necessarily confined to XML-compatible output.

There are two important configuration options this class uses:

$wgMimeType: If this is set to an xml MIME type then output should be valid XHTML5.

This class is meant to be confined to utility functions that are called from trusted code paths. It does not do enforcement of policy like not allowing elements.

Since: 1.16

Definition at line 57 of file Html.php.

Member Function Documentation

◆ addClass()

static MediaWiki\Html\Html::addClass	(	&	$classes,
		string	$class )

static

Add a class to a 'class' attribute in a format accepted by Html::element().

This method may also be used for any other space-separated attribute, such as 'rel'.

Parameters

array \| string \| null	&$classes	Class list to modify in-place
string	$class	Class to add

Since: 1.44

Definition at line 146 of file Html.php.

References wfWarn().

◆ buttonAttributes()

static MediaWiki\Html\Html::buttonAttributes	(	array	$attrs,
		array	$modifiers = [] )

static

Modifies a set of attributes meant for button elements.

Parameters

array	$attrs	HTML attributes in an associative array
string[]	$modifiers	Unused

Returns: array Modified attributes array

Deprecated: since 1.42 No-op

Definition at line 119 of file Html.php.

References wfDeprecated().

◆ check()

static MediaWiki\Html\Html::check	(		$name,
			$checked = false,
		array	$attribs = [] )

static

Convenience function to produce a checkbox (input element with type=checkbox)

Parameters

string	$name	Name attribute
bool	$checked	Whether the checkbox is checked or not
array	$attribs	Array of additional attributes

Returns: string Raw HTML

Definition at line 714 of file Html.php.

◆ closeElement()

static MediaWiki\Html\Html::closeElement ( $element )

static

Returns "</$element>".

Since: 1.17

Parameters

string $element Name of the element, e.g., 'a'

Returns: string A closing tag

Definition at line 333 of file Html.php.

Referenced by MediaWiki\Site\SiteExporter\exportSites().

◆ element()

static MediaWiki\Html\Html::element	(	$element,
		$attribs = [],
		$contents = '' )

static

Identical to rawElement(), but HTML-escapes $contents (like Xml::element()).

Parameters

string	$element	Name of the element, e.g., 'a'
array	$attribs	Associative array of attributes, e.g., [ 'href' => 'https://www.mediawiki.org/' ]. See expandAttributes() for further documentation.
string	$contents

Returns: string

Definition at line 245 of file Html.php.

◆ encodeJsCall()

static MediaWiki\Html\Html::encodeJsCall	(	$name,
		$args,
		$pretty = false )

static

Create a call to a JavaScript function.

The supplied arguments will be encoded using Html::encodeJsVar().

Since: 1.41 (previously on Xml since 1.17)

Parameters

string	$name	The name of the function to call, or a JavaScript expression which evaluates to a function object which is called.
array	$args	The arguments to pass to the function.
bool	$pretty	If true, add non-significant whitespace to improve readability.

Returns: string|false String if successful; false upon failure

Definition at line 1179 of file Html.php.

◆ encodeJsList()

static MediaWiki\Html\Html::encodeJsList	(		$args,
			$pretty = false )

static

Encode a JavaScript comma-separated list.

The supplied items will be encoded using Html::encodeJsVar().

Since: 1.41.

Parameters

array	$args	The elements of the list.
bool	$pretty	If true, add non-significant whitespace to improve readability.

Returns: false|string String if successful; false upon failure

Definition at line 1196 of file Html.php.

◆ encodeJsVar()

static MediaWiki\Html\Html::encodeJsVar	(		$value,
			$pretty = false )

static

Encode a variable of arbitrary type to JavaScript.

If the value is an HtmlJsCode object, pass through the object's value verbatim.

Note: Only use this function for generating JavaScript code. If generating output for a proper JSON parser, just call FormatJson::encode() directly.

Since: 1.41 (previously on Xml)

Parameters

mixed	$value	The value being encoded. Can be any type except a resource.
bool	$pretty	If true, add non-significant whitespace to improve readability.

Returns: string|false String if successful; false upon failure

Definition at line 1158 of file Html.php.

Referenced by MediaWiki\Html\HtmlJsCode\encodeObject().

◆ errorBox()

static MediaWiki\Html\Html::errorBox	(	$html,
		$heading = '',
		$className = '' )

static

Return an error box.

This method produces HTML that requires CSS styles for the Codex MessageBox component that need to be supplied by mediawiki.codex.messagebox.styles or another suitable Codex style module.

Since: 1.31; 1.34 $className optional parameter added

Parameters

string	$html	of contents of error box
string	$heading	(optional)
string	$className	(optional) corresponding to box

Returns: string of HTML representing an error box.

Definition at line 812 of file Html.php.

◆ expandAttributes()

static MediaWiki\Html\Html::expandAttributes ( array $attribs )

static

Given an associative array of element attributes, generate a string to stick after the element name in HTML output.

Like [ 'href' => 'https://www.mediawiki.org/' ] becomes something like ' href="https://www.mediawiki.org"'. Again, this is like Xml::expandAttributes(), but it implements some HTML-specific logic.

Attributes that can contain space-separated lists ('class', 'accesskey' and 'rel') array values are allowed as well, which will automagically be normalized and converted to a space-separated string. In addition to a numerical array, the attribute value may also be an associative array. See the example below for how that works.

Numerical array: Html::element( 'em', [

'class' => [ 'foo', 'bar' ]

] );

// gives '<em class="foo bar"></em>'

Associative array: Html::element( 'em', [

'class' => [ 'foo', 'bar', 'foo' => false, 'quux' => true ]

] );

// gives '<em class="bar quux"></em>'

Parameters

array $attribs Associative array of attributes, e.g., [ 'href' => 'https://www.mediawiki.org/' ]. Values will be HTML-escaped. A value of false or null means to omit the attribute. For boolean attributes, you can omit the key, e.g., [ 'checked' ] instead of [ 'checked' => 'checked' ] or such.

Returns: string HTML fragment that goes between element name and '>' (starting with a space if at least one attribute is output)

Definition at line 534 of file Html.php.

◆ expandClassList()

static MediaWiki\Html\Html::expandClassList ( $classes )

static

Convert a value for a 'class' attribute in a format accepted by Html::element() and similar methods to a single string.

This method may also be used for any other space-separated attribute, such as 'rel'.

Parameters

array | string $classes

Returns: string

Since: 1.44

Definition at line 457 of file Html.php.

◆ getTextInputAttributes()

static MediaWiki\Html\Html::getTextInputAttributes ( array $attrs )

static

Modifies a set of attributes meant for text input elements.

Parameters

array $attrs An attribute array.

Returns: array Modified attributes array

Deprecated: since 1.42 No-op

Definition at line 131 of file Html.php.

References wfDeprecated().

◆ hidden()

static MediaWiki\Html\Html::hidden	(		$name,
			$value,
		array	$attribs = [] )

static

Convenience function to produce an input element with type=hidden.

Parameters

string	$name	Name attribute
mixed	$value	Value attribute
array	$attribs	Associative array of miscellaneous extra attributes, passed to Html::element()

Returns: string Raw HTML

Definition at line 883 of file Html.php.

◆ htmlHeader()

static MediaWiki\Html\Html::htmlHeader ( array $attribs = [] )

static

Constructs the opening html-tag with necessary doctypes depending on global variables.

Parameters

array $attribs Associative array of miscellaneous extra attributes, passed to Html::element() of html tag.

Returns: string Raw HTML

Definition at line 1052 of file Html.php.

◆ inlineScript()

static MediaWiki\Html\Html::inlineScript	(		$contents,
			$nonce = null )

static

Output an HTML script tag with the given contents.

It is unsupported for the contents to contain the sequence <script or </script (case-insensitive). This ensures the script can be terminated easily and consistently. It is the responsibility of the caller to avoid such character sequence by escaping or avoiding it. If found at run-time, the contents are replaced with a comment, and a warning is logged server-side.

Parameters

string	$contents	JavaScript
string \| null	$nonce	Unused

Returns: string Raw HTML

Definition at line 611 of file Html.php.

References wfLogWarning().

◆ inlineStyle()

static MediaWiki\Html\Html::inlineStyle	(	$contents,
		$media = 'all',
		$attribs = [] )

static

Output a "<style>" tag with the given contents for the given media type (if any).

TODO: do some useful escaping as well, like if $contents contains literal "</style>" (admittedly unlikely).

Parameters

string	$contents	CSS
string	$media	A media type string, like 'screen'
array	$attribs	(since 1.31) Associative array of attributes, e.g., [ 'href' => 'https://www.mediawiki.org/' ]. See expandAttributes() for further documentation.

Returns: string Raw HTML

Definition at line 651 of file Html.php.

◆ input()

static MediaWiki\Html\Html::input	(		$name,
			$value = '',
			$type = 'text',
		array	$attribs = [] )

static

Convenience function to produce an <input> element.

This supports the new HTML5 input types and attributes.

Parameters

string	$name	Name attribute
string	$value	Value attribute
string	$type	Type attribute
array	$attribs	Associative array of miscellaneous extra attributes, passed to Html::element()

Returns: string Raw HTML

Definition at line 699 of file Html.php.

◆ isXmlMimeType()

static MediaWiki\Html\Html::isXmlMimeType ( $mimetype )

static

Determines if the given MIME type is xml.

Parameters

string $mimetype

Returns: bool

Definition at line 1092 of file Html.php.

◆ label()

static MediaWiki\Html\Html::label	(		$label,
			$id,
		array	$attribs = [] )

static

Convenience function for generating a label for inputs.

Parameters

string	$label	Contents of the label
string	$id	ID of the element being labeled
array	$attribs	Additional attributes

Returns: string Raw HTML

Definition at line 867 of file Html.php.

◆ linkButton()

static MediaWiki\Html\Html::linkButton	(		$text,
		array	$attrs,
		array	$modifiers = [] )

static

Returns an HTML link element in a string.

Parameters

string	$text	The text of the element. Will be escaped (not raw HTML)
array	$attrs	Associative array of attributes, e.g., [ 'href' => 'https://www.mediawiki.org/' ]. See expandAttributes() for further documentation.
string[]	$modifiers	Unused

Returns: string Raw HTML

Definition at line 173 of file Html.php.

References MediaWiki\Html\element().

◆ linkedScript()

static MediaWiki\Html\Html::linkedScript	(		$url,
			$nonce = null )

static

Output a "<script>" tag linking to the given URL, e.g., "<script src=foo.js></script>".

Parameters

string	$url
string \| null	$nonce	Nonce for CSP header, from OutputPage->getCSP()->getNonce()

Returns: string Raw HTML

Definition at line 628 of file Html.php.

References $url, and wfWarn().

◆ linkedStyle()

static MediaWiki\Html\Html::linkedStyle	(		$url,
			$media = 'all' )

static

Output a "<link rel=stylesheet>" linking to the given URL for the given media type (if any).

Parameters

string	$url
string	$media	A media type string, like 'screen'

Returns: string Raw HTML

Definition at line 680 of file Html.php.

References $url.

◆ listDropdownOptions()

static MediaWiki\Html\Html::listDropdownOptions	(		$list,
			$params = [] )

static

Build options for a drop-down box from a textual list.

The result of this function can be passed to XmlSelect::addOptions() (to render a plain <select> dropdown box) or to Html::listDropdownOptionsOoui() and then OOUI\DropdownInputWidget() (to render a pretty one).

Parameters

string	$list	Correctly formatted text (newline delimited) to be used to generate the options.
array	$params	Extra parameters: string $params['other'] If set, add an option with this as text and a value of 'other'

Returns: array Array keys are textual labels, values are internal values

Definition at line 1223 of file Html.php.

◆ listDropdownOptionsCodex()

static MediaWiki\Html\Html::listDropdownOptionsCodex ( $options )

static

Convert options for a drop-down box into a format accepted by OOUI\DropdownInputWidget etc.

TODO Find a better home for this function.

Parameters

array $options Options, as returned e.g. by Html::listDropdownOptions()

Returns: array

Definition at line 1298 of file Html.php.

◆ listDropdownOptionsOoui()

static MediaWiki\Html\Html::listDropdownOptionsOoui ( $options )

static

Convert options for a drop-down box into a format accepted by OOUI\DropdownInputWidget etc.

TODO Find a better home for this function.

Parameters

array $options Options, as returned e.g. by Html::listDropdownOptions()

Returns: array

Definition at line 1273 of file Html.php.

◆ namespaceSelector()

static MediaWiki\Html\Html::namespaceSelector	(	array	$params = [],
		array	$selectAttribs = [] )

static

Build a drop-down box for selecting a namespace.

Parameters

array	$params	Params to set. selected: [optional] Id of namespace which should be pre-selected all: [optional] Value of item for "all namespaces". If null or unset, no "<option>" is generated to select all namespaces. label: text for label to add before the field. exclude: [optional] Array of namespace ids to exclude. disable: [optional] Array of namespace ids for which the option should be disabled in the selector.
array	$selectAttribs	HTML attributes for the generated select element. id: [optional], default: 'namespace'. name: [optional], default: 'namespace'.

Returns: string HTML code to select a namespace.

Definition at line 983 of file Html.php.

◆ namespaceSelectorOptions()

static MediaWiki\Html\Html::namespaceSelectorOptions ( array $params = [] )

static

Helper for Html::namespaceSelector().

Parameters

array $params See Html::namespaceSelector()

Returns: array

Definition at line 919 of file Html.php.

References $wgLang, NS_MAIN, and wfMessage().

◆ noticeBox()

static MediaWiki\Html\Html::noticeBox	(	$html,
		$className,
		$heading = '',
		$iconClassName = '' )

static

Return the HTML for a notice message box.

This method produces HTML that requires CSS styles for the Codex MessageBox component that need to be supplied by mediawiki.codex.messagebox.styles or another suitable Codex style module.

Since: 1.38

Parameters

string	$html	of contents of notice
string \| array	$className	corresponding to notice
string	$heading	(optional)
string \| array	$iconClassName	(optional) corresponding to notice icon

Returns: string of HTML representing the notice

Definition at line 771 of file Html.php.

◆ openElement()

static MediaWiki\Html\Html::openElement	(		$element,
			$attribs = [] )

static

Identical to rawElement(), but has no third parameter and omits the end tag (and the self-closing '/' in XML mode for empty elements).

Parameters

string	$element	Name of the element, e.g., 'a'
array	$attribs	Associative array of attributes, e.g., [ 'href' => 'https://www.mediawiki.org/' ]. See expandAttributes() for further documentation.

Returns: string

Definition at line 269 of file Html.php.

References wfWarn().

Referenced by MediaWiki\Site\SiteExporter\exportSites().

◆ radio()

static MediaWiki\Html\Html::radio	(		$name,
			$checked = false,
		array	$attribs = [] )

static

Convenience function to produce a radio button (input element with type=radio)

Parameters

string	$name	Name attribute
bool	$checked	Whether the radio button is checked or not
array	$attribs	Array of additional attributes

Returns: string Raw HTML

Definition at line 844 of file Html.php.

◆ rawElement()

static MediaWiki\Html\Html::rawElement	(	$element,
		$attribs = [],
		$contents = '' )

static

Returns an HTML element in a string.

The major advantage here over manually typing out the HTML is that it will escape all attribute values.

This is quite similar to Xml::tags(), but it implements some useful HTML-specific logic. For instance, there is no $allowShortTag parameter: the closing tag is magically omitted if $element has an empty content model.

Parameters

string	$element	The element's name, e.g., 'a'
array	$attribs	Associative array of attributes, e.g., [ 'href' => 'https://www.mediawiki.org/' ]. See expandAttributes() for further documentation.
string	$contents	The raw HTML contents of the element: not escaped!

Returns: string Raw HTML

Definition at line 219 of file Html.php.

Referenced by MediaWiki\Html\ListToggle\getHTML().

◆ srcSet()

static MediaWiki\Html\Html::srcSet ( array $urls )

static

Generate a srcset attribute value.

Generates a srcset attribute value from an array mapping pixel densities to URLs. A trailing 'x' in pixel density values is optional.

Note: srcset width and height values are not supported.

See also: https://html.spec.whatwg.org/#attr-img-srcset

Example:: Html::srcSet( [

'1x' => 'standard.jpeg',

'1.5x' => 'large.jpeg',

'3x' => 'extra-large.jpeg',

] );

// gives 'standard.jpeg 1x, large.jpeg 1.5x, extra-large.jpeg 2x'

Parameters

string[] $urls

Returns: string

Definition at line 1123 of file Html.php.

References $url.

◆ submitButton()

static MediaWiki\Html\Html::submitButton	(		$contents,
		array	$attrs = [],
		array	$modifiers = [] )

static

Returns an HTML input element in a string.

Parameters

string	$contents	Plain text label for the button value
array	$attrs	Associative array of attributes, e.g., [ 'href' => 'https://www.mediawiki.org/' ]. See expandAttributes() for further documentation.
string[]	$modifiers	Unused

Returns: string Raw HTML

Definition at line 191 of file Html.php.

References MediaWiki\Html\element().

◆ successBox()

static MediaWiki\Html\Html::successBox	(		$html,
			$className = '' )

static

Return a success box.

This method produces HTML that requires CSS styles for the Codex MessageBox component that need to be supplied by mediawiki.codex.messagebox.styles or another suitable Codex style module.

Since: 1.31; 1.34 $className optional parameter added

Parameters

string	$html	of contents of box
string	$className	(optional) corresponding to box

Returns: string of HTML representing a success box.

Definition at line 831 of file Html.php.

◆ textarea()

static MediaWiki\Html\Html::textarea	(		$name,
			$value = '',
		array	$attribs = [] )

static

Convenience function to produce a <textarea> element.

This supports leaving out the cols= and rows= which Xml requires and are required by HTML4/XHTML but not required by HTML5.

Parameters

string	$name	Name attribute
string	$value	Value attribute
array	$attribs	Associative array of miscellaneous extra attributes, passed to Html::element()

Returns: string Raw HTML

Definition at line 899 of file Html.php.

◆ warningBox()

static MediaWiki\Html\Html::warningBox	(		$html,
			$className = '' )

static

Return a warning box.

This method produces HTML that requires CSS styles for the Codex MessageBox component that need to be supplied by mediawiki.codex.messagebox.styles or another suitable Codex style module.

Since: 1.31; 1.34 $className optional parameter added

Parameters

string	$html	of contents of box
string	$className	(optional) corresponding to box

Returns: string of HTML representing a warning box.

Definition at line 792 of file Html.php.

The documentation for this class was generated from the following file:

includes/Html/Html.php

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ addClass()

◆ buttonAttributes()

◆ check()

◆ closeElement()

◆ element()

◆ encodeJsCall()

◆ encodeJsList()

◆ encodeJsVar()

◆ errorBox()

◆ expandAttributes()

◆ expandClassList()

◆ getTextInputAttributes()

◆ hidden()

◆ htmlHeader()

◆ inlineScript()

◆ inlineStyle()

◆ input()

◆ isXmlMimeType()

◆ label()

◆ linkButton()

◆ linkedScript()

◆ linkedStyle()

◆ listDropdownOptions()

◆ listDropdownOptionsCodex()

◆ listDropdownOptionsOoui()

◆ namespaceSelector()

◆ namespaceSelectorOptions()

◆ noticeBox()

◆ openElement()

◆ radio()

◆ rawElement()

◆ srcSet()

◆ submitButton()

◆ successBox()

◆ textarea()

◆ warningBox()