Html

Type

Class

Namespace

craft\helpers

Inherits

craft\helpers\Html » yii\helpers\Html (opens new window) » yii\helpers\BaseHtml (opens new window)

Since

3.0.0

Class Html

View source (opens new window)

Public Properties

Property	Description
attributeOrder (opens new window)	array (opens new window) – The preferred order of attributes in a tag.
attributeRegex (opens new window)	string (opens new window) – Regular expression used for attribute name validation.
dataAttributes	array (opens new window) – List of tag attributes that should be specially handled when their values are of array type.
normalizeClassAttribute (opens new window)	boolean (opens new window) – Whether to removes duplicate class names in tag attribute class
voidElements (opens new window)	array (opens new window) – List of void elements (element name => 1)

dataAttributes

Type

array (opens new window)

Default value

[ 'aria', 'data', 'data-hx', 'data-ng', 'hx', 'ng', ]

Since

4.0.0

List of tag attributes that should be specially handled when their values are of array type. In particular, if the value of the data attribute is ['name' => 'xyz', 'age' => 13], two attributes will be generated instead of one: data-name="xyz" data-age="13".

View source (opens new window)

Public Methods

Method	Description
a()	Generates a hyperlink tag.
actionInput()	Generates a hidden action input tag.
activeCheckbox() (opens new window)	Generates a checkbox tag together with a label for the given model attribute.
activeCheckboxList() (opens new window)	Generates a list of checkboxes.
activeDropDownList() (opens new window)	Generates a drop-down list for the given model attribute.
activeFileInput() (opens new window)	Generates a file input tag for the given model attribute.
activeHiddenInput() (opens new window)	Generates a hidden input tag for the given model attribute.
activeHint() (opens new window)	Generates a hint tag for the given model attribute.
activeInput() (opens new window)	Generates an input tag for the given model attribute.
activeLabel() (opens new window)	Generates a label tag for the given model attribute.
activeListBox() (opens new window)	Generates a list box.
activePasswordInput() (opens new window)	Generates a password input tag for the given model attribute.
activeRadio() (opens new window)	Generates a radio button tag together with a label for the given model attribute.
activeRadioList() (opens new window)	Generates a list of radio buttons.
activeTextInput() (opens new window)	Generates a text input tag for the given model attribute.
activeTextarea() (opens new window)	Generates a textarea tag for the given model attribute.
addCssClass() (opens new window)	Adds a CSS class (or several classes) to the specified options.
addCssStyle() (opens new window)	Adds the specified CSS style to the HTML options.
appendToTag()	Appends HTML to the end of the given tag.
beginForm()	Generates a form start tag.
beginTag() (opens new window)	Generates a start tag.
button() (opens new window)	Generates a button tag.
buttonInput() (opens new window)	Generates an input button.
checkbox() (opens new window)	Generates a checkbox input.
checkboxList() (opens new window)	Generates a list of checkboxes.
csrfInput()	Generates a hidden CSRF input tag.
csrfMetaTags() (opens new window)	Generates the meta tags containing CSRF token information.
cssFile() (opens new window)	Generates a link tag that refers to an external CSS file.
cssStyleFromArray() (opens new window)	Converts a CSS style array into a string representation.
cssStyleToArray() (opens new window)	Converts a CSS style string into an array representation.
dataUrl()	Generates a base64-encoded data URL (opens new window) for the given file path.
dataUrlFromString()	Generates a base64-encoded data URL (opens new window) based on the given file contents and MIME type.
decode() (opens new window)	Decodes special HTML entities back to the corresponding characters.
dropDownList() (opens new window)	Generates a drop-down list.
encode() (opens new window)	Encodes special characters into HTML entities.
encodeInvalidTags()	Encodes invalid (unclosed) HTML tags so they appear as plain text.
encodeParams()	Will take an HTML string and an associative array of key=>value pairs, HTML encode the values and swap them back into the original string using the keys as tokens.
encodeSpaces()	Converts spaces into %20 entities.
endForm() (opens new window)	Generates a form end tag.
endTag() (opens new window)	Generates an end tag.
error() (opens new window)	Generates a tag that contains the first validation error of the specified model attribute.
errorSummary() (opens new window)	Generates a summary of the validation errors.
escapeJsRegularExpression() (opens new window)	Escapes regular expression to use in JavaScript.
explodeClass()	Explodes a class attribute into an array.
explodeStyle()	Explodes a style attribute into an array of property/value pairs.
failMessageInput()	Generates a hidden failMessage input tag.
fileInput() (opens new window)	Generates a file input field.
getAttributeName() (opens new window)	Returns the real attribute name from the given attribute expression.
getAttributeValue() (opens new window)	Returns the value of the specified attribute name or expression.
getInputId() (opens new window)	Generates an appropriate input ID for the specified attribute name or expression.
getInputIdByName() (opens new window)	Converts input name to ID.
getInputName() (opens new window)	Generates an appropriate input name for the specified attribute name or expression.
hiddenInput() (opens new window)	Generates a hidden input field.
hiddenLabel()	Returns a visually-hidden input label.
id()	Normalizes an element ID into only alphanumeric characters, underscores, and dashes, or generates one at random.
img() (opens new window)	Generates an image tag.
input() (opens new window)	Generates an input type of the given type.
jsFile() (opens new window)	Generates a script tag that refers to an external JavaScript file.
label() (opens new window)	Generates a label tag.
listBox() (opens new window)	Generates a list box.
mailto() (opens new window)	Generates a mailto hyperlink.
modifyTagAttributes()	Modifies a HTML tag’s attributes, supporting the same attribute definitions as renderTagAttributes() (opens new window).
namespaceAttributes()	Prepends a namespace to id attributes, and any of the following things that reference those IDs:
namespaceHtml()	Namespaces input names and other HTML attributes, as well as CSS selectors.
namespaceId()	Namespaces an ID.
namespaceInputName()	Namespaces an input name.
namespaceInputs()	Renames HTML input names so they belong to a namespace.
normalizeTagAttributes()	Normalizes attributes.
ol() (opens new window)	Generates an ordered list.
parseTag()	Parses an HTML tag and returns info about it and its children.
parseTagAttribute()	Parses the next HTML tag attribute in a given string.
parseTagAttributes()	Parses an HTML tag to find its attributes.
passwordInput() (opens new window)	Generates a password input field.
prependToTag()	Prepends HTML to the beginning of given tag.
radio() (opens new window)	Generates a radio button input.
radioList() (opens new window)	Generates a list of radio buttons.
redirectInput()	Generates a hidden redirect input tag.
removeCssClass() (opens new window)	Removes a CSS class from the specified options.
removeCssStyle() (opens new window)	Removes the specified CSS style from the HTML options.
renderSelectOptions() (opens new window)	Renders the option tags that can be used by dropDownList() (opens new window) and listBox() (opens new window).
renderTagAttributes() (opens new window)	Renders the HTML tag attributes.
resetButton() (opens new window)	Generates a reset button tag.
resetInput() (opens new window)	Generates a reset input button.
sanitizeSvg()	Sanitizes an SVG.
script() (opens new window)	Generates a script tag.
style() (opens new window)	Generates a style tag.
submitButton() (opens new window)	Generates a submit button tag.
submitInput() (opens new window)	Generates a submit input button.
successMessageInput()	Generates a hidden successMessage input tag.
svg()	Returns the contents of a given SVG file.
tag() (opens new window)	Generates a complete HTML tag.
textInput() (opens new window)	Generates a text input field.
textarea() (opens new window)	Generates a text area input.
ul() (opens new window)	Generates an unordered list.
unwrapCondition()	Unwraps an IE conditional comment from the given HTML.
unwrapNoscript()	Unwraps a <noscript> tag from the given HTML.
widont()	Inserts a non-breaking space between the last two words of a string.

a()

Since

3.3.0

Generates a hyperlink tag.

View source (opens new window)

Arguments

• $text (string (opens new window)) – Link body. It will NOT be HTML-encoded. Therefore you can pass in HTML code such as an image tag. If this is coming from end users, you should consider encode() (opens new window) it to prevent XSS attacks.
• $url (array (opens new window), string (opens new window), null (opens new window)) – The URL for the hyperlink tag. This parameter will be processed by yii\helpers\Url::to() (opens new window) and will be used for the "href" attribute of the tag. If this parameter is null, the "href" attribute will not be generated.

If you want to use an absolute url you can call yii\helpers\Url::to() (opens new window) yourself, before passing the URL to this method, like this:

Html::a('link text', Url::to($url, true))

• $options (array (opens new window)) – The tag options in terms of name-value pairs. These will be rendered as the attributes of the resulting tag. The values will be HTML-encoded using encode() (opens new window). If a value is null, the corresponding attribute will not be rendered. See renderTagAttributes() (opens new window) for details on how attributes are being rendered.

Returns

string (opens new window) – The generated hyperlink

actionInput()

Since

3.3.0

Generates a hidden action input tag.

View source (opens new window)

Arguments

• $route (string (opens new window)) – The action route
• $options (array (opens new window)) – The tag options in terms of name-value pairs. These will be rendered as the attributes of the resulting tag. The values will be HTML-encoded using encode() (opens new window). If a value is null, the corresponding attribute will not be rendered. See renderTagAttributes() (opens new window) for details on how attributes are being rendered.

Returns

string (opens new window) – The generated hidden input tag

appendToTag()

Since

3.3.0

Appends HTML to the end of the given tag.

View source (opens new window)

Arguments

• $tag (string (opens new window)) – The HTML tag that $html should be appended to
• $html (string (opens new window)) – The HTML to append to $tag.
• $ifExists (string (opens new window), null (opens new window)) – What to do if $tag already contains a child of the same type as the element defined by $html. Set to 'keep' if no action should be taken, or 'replace' if it should be replaced by $tag.

Returns

string (opens new window) – The modified HTML

beginForm()

Generates a form start tag.

View source (opens new window)

Arguments

• $action (array (opens new window), string (opens new window)) – The form action URL. This parameter will be processed by yii\helpers\Url::to() (opens new window).
• $method (string (opens new window)) – The form submission method, such as "post", "get", "put", "delete" (case-insensitive). Since most browsers only support "post" and "get", if other methods are given, they will be simulated using "post", and a hidden input will be added which contains the actual method type. See yii\web\Request::$methodParam (opens new window) for more details.
• $options (array (opens new window)) – The tag options in terms of name-value pairs. These will be rendered as the attributes of the resulting tag. The values will be HTML-encoded using encode() (opens new window). If a value is null, the corresponding attribute will not be rendered. See renderTagAttributes() (opens new window) for details on how attributes are being rendered.

Special options:

• csrf: whether to generate the CSRF hidden input. Defaults to true.

Returns

string (opens new window) – The generated form start tag.

csrfInput()

Since

3.3.0

Generates a hidden CSRF input tag.

View source (opens new window)

Arguments

• $options (array (opens new window)) – The tag options in terms of name-value pairs. These will be rendered as the attributes of the resulting tag. The values will be HTML-encoded using encode() (opens new window). If a value is null, the corresponding attribute will not be rendered. See renderTagAttributes() (opens new window) for details on how attributes are being rendered.

Returns

string (opens new window) – The generated hidden input tag

dataUrl()

Since

3.5.13

Generates a base64-encoded data URL (opens new window) for the given file path.

View source (opens new window)

Arguments

• $file (string (opens new window)) – The file path
• $mimeType (string (opens new window), null (opens new window)) – The file’s MIME type. If null then it will be determined automatically.

Returns

string (opens new window) – The data URL

Throws

• yii\base\InvalidArgumentException (opens new window)
  if $file is an invalid file path

dataUrlFromString()

Since

3.5.13

Generates a base64-encoded data URL (opens new window) based on the given file contents and MIME type.

View source (opens new window)

Arguments

• $contents (string (opens new window)) – The file path
• $mimeType (string (opens new window), null (opens new window)) – The file’s MIME type. If null then it will be determined automatically.

Returns

string (opens new window) – The data URL

Throws

• yii\base\InvalidArgumentException (opens new window)
  if $file is an invalid file path

encodeInvalidTags()

Since

3.7.27

Encodes invalid (unclosed) HTML tags so they appear as plain text.

View source (opens new window)

Arguments

• $html (string (opens new window))

Returns

string (opens new window)

encodeParams()

Will take an HTML string and an associative array of key=>value pairs, HTML encode the values and swap them back into the original string using the keys as tokens.

View source (opens new window)

Arguments

• $html (string (opens new window)) – The HTML string.
• $variables (array (opens new window)) – An associative array of key => value pairs to be applied to the HTML string using strtr.

Returns

string (opens new window) – The HTML string with the encoded variable values swapped in.

encodeSpaces()

Since

4.0.4

Converts spaces into %20 entities.

View source (opens new window)

Arguments

• $str (string (opens new window))

Returns

string (opens new window)

explodeClass()

Since

3.5.0

Explodes a class attribute into an array.

View source (opens new window)

Arguments

• $value (mixed)

Returns

string (opens new window)[]

explodeStyle()

Since

3.5.0

Explodes a style attribute into an array of property/value pairs.

View source (opens new window)

Arguments

• $value (mixed)

Returns

string (opens new window)[]

failMessageInput()

Since

3.6.6

Generates a hidden failMessage input tag.

View source (opens new window)

Arguments

• $message (string (opens new window)) – The flash message to shown on failure
• $options (array (opens new window)) – The tag options in terms of name-value pairs. These will be rendered as the attributes of the resulting tag. The values will be HTML-encoded using encode() (opens new window). If a value is null, the corresponding attribute will not be rendered. See renderTagAttributes() (opens new window) for details on how attributes are being rendered.

Returns

string (opens new window) – The generated hidden input tag

Throws

• yii\base\Exception (opens new window)
  if the validation key could not be written
• yii\base\InvalidConfigException (opens new window)
  when HMAC generation fails

hiddenLabel()

Since

4.0.0

Returns a visually-hidden input label.

View source (opens new window)

Arguments

• $content (string (opens new window))
• $for (string (opens new window), null (opens new window))
• $options (array (opens new window))

Returns

string (opens new window)

id()

Since

3.5.0

Normalizes an element ID into only alphanumeric characters, underscores, and dashes, or generates one at random.

View source (opens new window)

Arguments

• $id (string (opens new window))

Returns

string (opens new window)

modifyTagAttributes()

Since

3.3.0

Modifies a HTML tag’s attributes, supporting the same attribute definitions as renderTagAttributes() (opens new window).

View source (opens new window)

Arguments

• $tag (string (opens new window)) – The HTML tag whose attributes should be modified.
• $attributes (array (opens new window)) – The attributes to be added to the tag.

Returns

string (opens new window) – The modified HTML tag.

Throws

• yii\base\InvalidArgumentException (opens new window)
  if $tag doesn't contain a valid HTML tag

namespaceAttributes()

Since

3.5.0

Prepends a namespace to id attributes, and any of the following things that reference those IDs:

• for, list, href, aria-labelledby, aria-describedby, aria-controls, data-target, data-reverse-target, and data-target-prefix attributes
• ID selectors within <style> tags

For example, this:

<style>#summary { font-size: larger }</style>
<p id="summary">...</p>

would become this, if it were namespaced with foo:

<style>#foo-summary { font-size: larger }</style>
<p id="foo-summary">...</p>

See also:

• namespaceHtml()
• namespaceInputs()

View source (opens new window)

Arguments

• $html (string (opens new window)) – The HTML code
• $namespace (string (opens new window)) – The namespace
• $withClasses (boolean (opens new window)) – Whether class names should be namespaced as well (affects both class attributes and class name CSS selectors)

Returns

string (opens new window) – The HTML with namespaced attributes

namespaceHtml()

Since

3.5.0

Namespaces input names and other HTML attributes, as well as CSS selectors.

This is a shortcut for calling namespaceInputs() and namespaceAttributes().

View source (opens new window)

Arguments

• $html (string (opens new window)) – The HTML code
• $namespace (string (opens new window)) – The namespace
• $withClasses (boolean (opens new window)) – Whether class names should be namespaced as well (affects both class attributes and class name CSS selectors)

Returns

string (opens new window) – The HTML with namespaced attributes

namespaceId()

Since

3.5.0

Namespaces an ID.

View source (opens new window)

Arguments

• $id (string (opens new window)) – The ID
• $namespace (string (opens new window), null (opens new window)) – The namespace

Returns

string (opens new window) – The namespaced ID

namespaceInputName()

Since

3.5.0

Namespaces an input name.

View source (opens new window)

Arguments

• $inputName (string (opens new window)) – The input name
• $namespace (string (opens new window), null (opens new window)) – The namespace

Returns

string (opens new window) – The namespaced input name

namespaceInputs()

Since

3.5.0

Renames HTML input names so they belong to a namespace.

This method will go through the passed-in HTML code looking for name attributes, and namespace their values.

For example, this:

<input type="text" name="title">
<textarea name="fields[body]"></textarea>

would become this, if it were namespaced with foo:

<input type="text" name="foo[title]">
<textarea name="foo[fields][body]"></textarea>

See also:

• namespaceHtml()
• namespaceAttributes()

View source (opens new window)

Arguments

• $html (string (opens new window)) – The HTML code
• $namespace (string (opens new window)) – The namespace

Returns

string (opens new window) – The HTML with namespaced input names

normalizeTagAttributes()

Since

3.3.0

Normalizes attributes.

View source (opens new window)

Arguments

• $attributes (array (opens new window))

Returns

array (opens new window)

parseTag()

Since

3.3.0

Parses an HTML tag and returns info about it and its children.

View source (opens new window)

Arguments

• $tag (string (opens new window)) – The HTML tag
• $offset (integer (opens new window)) – The offset to start looking for a tag

Returns

array (opens new window) – An array containing type, attributes, children, start, end, htmlStart, and htmlEnd properties. Nested text nodes will be represented as arrays within children with type set to 'text', and a value key containing the text value.

Throws

• craft\errors\InvalidHtmlTagException
  if $tag doesn't contain a valid HTML tag

parseTagAttribute()

Since

3.7.0

Parses the next HTML tag attribute in a given string.

View source (opens new window)

Arguments

• $html (string (opens new window)) – The HTML to parse
• $offset (integer (opens new window)) – The offset to start looking for an attribute
• $start (integer (opens new window), null (opens new window)) – The start position of the attribute in the given HTML
• $end (integer (opens new window), null (opens new window)) – The end position of the attribute in the given HTML

Returns

array (opens new window), null (opens new window) – The name and value of the attribute, or false if no complete attribute was found

Throws

• yii\base\InvalidArgumentException (opens new window)
  if $html doesn't begin with a valid HTML attribute

parseTagAttributes()

Since

3.3.0

Parses an HTML tag to find its attributes.

View source (opens new window)

Arguments

• $tag (string (opens new window)) – The HTML tag to parse
• $offset (integer (opens new window)) – The offset to start looking for a tag
• $start (integer (opens new window), null (opens new window)) – The start position of the first attribute in the given tag
• $end (integer (opens new window), null (opens new window)) – The end position of the last attribute in the given tag
• $decode (boolean (opens new window)) – Whether the attributes should be HTML decoded in the process

Returns

array (opens new window) – The parsed HTML tag attributes

Throws

• craft\errors\InvalidHtmlTagException
  if $tag doesn't contain a valid HTML tag

prependToTag()

Since

3.3.0

Prepends HTML to the beginning of given tag.

View source (opens new window)

Arguments

• $tag (string (opens new window)) – The HTML tag that $html should be prepended to
• $html (string (opens new window)) – The HTML to prepend to $tag.
• $ifExists (string (opens new window), null (opens new window)) – What to do if $tag already contains a child of the same type as the element defined by $html. Set to 'keep' if no action should be taken, or 'replace' if it should be replaced by $tag.

Returns

string (opens new window) – The modified HTML

redirectInput()

Since

3.3.0

Generates a hidden redirect input tag.

View source (opens new window)

Arguments

• $url (string (opens new window)) – The URL to redirect to
• $options (array (opens new window)) – The tag options in terms of name-value pairs. These will be rendered as the attributes of the resulting tag. The values will be HTML-encoded using encode() (opens new window). If a value is null, the corresponding attribute will not be rendered. See renderTagAttributes() (opens new window) for details on how attributes are being rendered.

Returns

string (opens new window) – The generated hidden input tag

Throws

• yii\base\Exception (opens new window)
  if the validation key could not be written
• yii\base\InvalidConfigException (opens new window)
  when HMAC generation fails

sanitizeSvg()

Since

3.5.0

Sanitizes an SVG.

View source (opens new window)

Arguments

• $svg (string (opens new window))

Returns

string (opens new window)

successMessageInput()

Since

3.6.6

Generates a hidden successMessage input tag.

View source (opens new window)

Arguments

• $message (string (opens new window)) – The flash message to shown on success
• $options (array (opens new window)) – The tag options in terms of name-value pairs. These will be rendered as the attributes of the resulting tag. The values will be HTML-encoded using encode() (opens new window). If a value is null, the corresponding attribute will not be rendered. See renderTagAttributes() (opens new window) for details on how attributes are being rendered.

Returns

string (opens new window) – The generated hidden input tag

Throws

• yii\base\Exception (opens new window)
  if the validation key could not be written
• yii\base\InvalidConfigException (opens new window)
  when HMAC generation fails

svg()

Since

4.3.0

Returns the contents of a given SVG file.

View source (opens new window)

Arguments

• $svg (string (opens new window), craft\elements\Asset) – An SVG asset, a file path, or raw SVG markup
• $sanitize (boolean (opens new window), null (opens new window)) – Whether the SVG should be sanitized of potentially malicious scripts. By default, the SVG will only be sanitized if an asset or markup is passed in. (File paths are assumed to be safe.)
• $namespace (boolean (opens new window), null (opens new window)) – Whether class names and IDs within the SVG should be namespaced to avoid conflicts with other elements in the DOM. By default, the SVG will only be namespaced if an asset or markup is passed in.

Returns

string (opens new window)

unwrapCondition()

Since

4.0.0

Unwraps an IE conditional comment from the given HTML.

See also \craft\helpers\wrapIntoCondition() View source (opens new window)

Arguments

• $content (string (opens new window))

Returns

array (opens new window)[] – An array containing the HTML content, and the condition (if there is one).

unwrapNoscript()

Since

4.0.0

Unwraps a <noscript> tag from the given HTML.

View source (opens new window)

Arguments

• $content (string (opens new window))

Returns

array (opens new window)[] – An array containing the HTML content, and whether a <noscript> tag was found.

widont()

Since

3.7.0

Inserts a non-breaking space between the last two words of a string.

View source (opens new window)

Arguments

• $string (string (opens new window))

Returns

string (opens new window)

Protected Methods

Method	Description
activeBooleanInput() (opens new window)	Generates a boolean input This method is mainly called by activeCheckbox() (opens new window) and activeRadio() (opens new window).
activeListInput() (opens new window)	Generates a list of input fields.
booleanInput() (opens new window)	Generates a boolean input.
setActivePlaceholder() (opens new window)	Generate placeholder from model attribute label.