Html

Type

Class

Namespace

craft\helpers

Inherits

craft\helpers\Html » yii\helpers\Html » yii\helpers\BaseHtml

Since

3.0.0

Class Html

View source

Public Properties

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

dataAttributes

Type

array

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

Public Methods

Method	Description
a()	Generates a hyperlink tag.
actionInput()	Generates a hidden action input tag.
activeCheckbox()	Generates a checkbox tag together with a label for the given model attribute.
activeCheckboxList()	Generates a list of checkboxes.
activeDropDownList()	Generates a drop-down list for the given model attribute.
activeFileInput()	Generates a file input tag for the given model attribute.
activeHiddenInput()	Generates a hidden input tag for the given model attribute.
activeHint()	Generates a hint tag for the given model attribute.
activeInput()	Generates an input tag for the given model attribute.
activeLabel()	Generates a label tag for the given model attribute.
activeListBox()	Generates a list box.
activePasswordInput()	Generates a password input tag for the given model attribute.
activeRadio()	Generates a radio button tag together with a label for the given model attribute.
activeRadioList()	Generates a list of radio buttons.
activeTextInput()	Generates a text input tag for the given model attribute.
activeTextarea()	Generates a textarea tag for the given model attribute.
addCssClass()	Adds a CSS class (or several classes) to the specified options.
addCssStyle()	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()	Generates a start tag.
button()	Generates a button tag.
buttonInput()	Generates an input button.
checkbox()	Generates a checkbox input.
checkboxList()	Generates a list of checkboxes.
csrfInput()	Generates a hidden CSRF input tag.
csrfMetaTags()	Generates the meta tags containing CSRF token information.
cssFile()	Generates a link tag that refers to an external CSS file.
cssStyleFromArray()	Converts a CSS style array into a string representation.
cssStyleToArray()	Converts a CSS style string into an array representation.
dataUrl()	Generates a base64-encoded data URL for the given file path.
dataUrlFromString()	Generates a base64-encoded data URL based on the given file contents and MIME type.
decode()	Decodes special HTML entities back to the corresponding characters.
dropDownList()	Generates a drop-down list.
encode()	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()	Generates a form end tag.
endTag()	Generates an end tag.
error()	Generates a tag that contains the first validation error of the specified model attribute.
errorSummary()	Generates a summary of the validation errors.
escapeJsRegularExpression()	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()	Generates a file input field.
getAttributeName()	Returns the real attribute name from the given attribute expression.
getAttributeValue()	Returns the value of the specified attribute name or expression.
getInputId()	Generates an appropriate input ID for the specified attribute name or expression.
getInputIdByName()	Converts input name to ID.
getInputName()	Generates an appropriate input name for the specified attribute name or expression.
hiddenInput()	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()	Generates an image tag.
input()	Generates an input type of the given type.
jsFile()	Generates a script tag that refers to an external JavaScript file.
label()	Generates a label tag.
listBox()	Generates a list box.
mailto()	Generates a mailto hyperlink.
modifyTagAttributes()	Modifies a HTML tag’s attributes, supporting the same attribute definitions as renderTagAttributes().
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()	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()	Generates a password input field.
prependToTag()	Prepends HTML to the beginning of given tag.
radio()	Generates a radio button input.
radioList()	Generates a list of radio buttons.
redirectInput()	Generates a hidden redirect input tag.
removeCssClass()	Removes a CSS class from the specified options.
removeCssStyle()	Removes the specified CSS style from the HTML options.
renderSelectOptions()	Renders the option tags that can be used by dropDownList() and listBox().
renderTagAttributes()	Renders the HTML tag attributes.
resetButton()	Generates a reset button tag.
resetInput()	Generates a reset input button.
sanitizeSvg()	Sanitizes an SVG.
script()	Generates a script tag.
style()	Generates a style tag.
submitButton()	Generates a submit button tag.
submitInput()	Generates a submit input button.
successMessageInput()	Generates a hidden successMessage input tag.
svg()	Returns the contents of a given SVG file.
tag()	Generates a complete HTML tag.
textInput()	Generates a text input field.
textarea()	Generates a text area input.
ul()	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

Arguments

• $text (string) – 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() it to prevent XSS attacks.
• $url (array, string, null) – The URL for the hyperlink tag. This parameter will be processed by yii\helpers\Url::to() 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() yourself, before passing the URL to this method, like this:

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

• $options (array) – 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(). If a value is null, the corresponding attribute will not be rendered. See renderTagAttributes() for details on how attributes are being rendered.

Returns

string – The generated hyperlink

actionInput()

Since

3.3.0

Generates a hidden action input tag.

View source

Arguments

• $route (string) – The action route
• $options (array) – 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(). If a value is null, the corresponding attribute will not be rendered. See renderTagAttributes() for details on how attributes are being rendered.

Returns

string – The generated hidden input tag

appendToTag()

Since

3.3.0

Appends HTML to the end of the given tag.

View source

Arguments

• $tag (string) – The HTML tag that $html should be appended to
• $html (string) – The HTML to append to $tag.
• $ifExists (string, null) – 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 – The modified HTML

beginForm()

Generates a form start tag.

View source

Arguments

• $action (array, string) – The form action URL. This parameter will be processed by yii\helpers\Url::to().
• $method (string) – 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 for more details.
• $options (array) – 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(). If a value is null, the corresponding attribute will not be rendered. See renderTagAttributes() for details on how attributes are being rendered.

Special options:

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

Returns

string – The generated form start tag.

beginTag()

Generates a start tag.

View source

Arguments

• $name (string, boolean, null) – The tag name. If $name is null or false, the corresponding content will be rendered without any tag.
• $options (array) – 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(). If a value is null, the corresponding attribute will not be rendered. See renderTagAttributes() for details on how attributes are being rendered.

Returns

string – The generated start tag

csrfInput()

Since

3.3.0

Generates a hidden CSRF input tag.

View source

Arguments

• $options (array) – 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(). If a value is null, the corresponding attribute will not be rendered. See renderTagAttributes() for details on how attributes are being rendered.

Returns

string – The generated hidden input tag

dataUrl()

Since

3.5.13

Generates a base64-encoded data URL for the given file path.

View source

Arguments

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

Returns

string – The data URL

Throws

• yii\base\InvalidArgumentException
  if $file is an invalid file path

dataUrlFromString()

Since

3.5.13

Generates a base64-encoded data URL based on the given file contents and MIME type.

View source

Arguments

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

Returns

string – The data URL

Throws

• yii\base\InvalidArgumentException
  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

Arguments

• $html (string)

Returns

string

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

Arguments

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

Returns

string – The HTML string with the encoded variable values swapped in.

encodeSpaces()

Since

4.0.4

Converts spaces into %20 entities.

View source

Arguments

• $str (string)

Returns

string

explodeClass()

Since

3.5.0

Explodes a class attribute into an array.

View source

Arguments

• $value (mixed)

Returns

string[]

explodeStyle()

Since

3.5.0

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

View source

Arguments

• $value (mixed)

Returns

string[]

failMessageInput()

Since

3.6.6

Generates a hidden failMessage input tag.

View source

Arguments

• $message (string) – The flash message to shown on failure
• $options (array) – 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(). If a value is null, the corresponding attribute will not be rendered. See renderTagAttributes() for details on how attributes are being rendered.

Returns

string – The generated hidden input tag

Throws

• yii\base\Exception
  if the validation key could not be written
• yii\base\InvalidConfigException
  when HMAC generation fails

hiddenLabel()

Since

4.0.0

Returns a visually-hidden input label.

View source

Arguments

• $content (string)
• $for (string, null)
• $options (array)

Returns

string

id()

Since

3.5.0

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

View source

Arguments

• $id (string)

Returns

string

modifyTagAttributes()

Since

3.3.0

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

View source

Arguments

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

Returns

string – The modified HTML tag.

Throws

• yii\base\InvalidArgumentException
  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

Arguments

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

Returns

string – 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

Arguments

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

Returns

string – The HTML with namespaced attributes

namespaceId()

Since

3.5.0

Namespaces an ID.

View source

Arguments

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

Returns

string – The namespaced ID

namespaceInputName()

Since

3.5.0

Namespaces an input name.

View source

Arguments

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

Returns

string – 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

Arguments

• $html (string) – The HTML code
• $namespace (string) – The namespace

Returns

string – The HTML with namespaced input names

normalizeTagAttributes()

Since

3.3.0

Normalizes attributes.

View source

Arguments

• $attributes (array)

Returns

array

parseTag()

Since

3.3.0

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

View source

Arguments

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

Returns

array – 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

Arguments

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

Returns

array, null – The name and value of the attribute, or false if no complete attribute was found

Throws

• yii\base\InvalidArgumentException
  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

Arguments

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

Returns

array – 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

Arguments

• $tag (string) – The HTML tag that $html should be prepended to
• $html (string) – The HTML to prepend to $tag.
• $ifExists (string, null) – 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 – The modified HTML

redirectInput()

Since

3.3.0

Generates a hidden redirect input tag.

View source

Arguments

• $url (string) – The URL to redirect to
• $options (array) – 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(). If a value is null, the corresponding attribute will not be rendered. See renderTagAttributes() for details on how attributes are being rendered.

Returns

string – The generated hidden input tag

Throws

• yii\base\Exception
  if the validation key could not be written
• yii\base\InvalidConfigException
  when HMAC generation fails

sanitizeSvg()

Since

3.5.0

Sanitizes an SVG.

View source

Arguments

• $svg (string)

Returns

string

successMessageInput()

Since

3.6.6

Generates a hidden successMessage input tag.

View source

Arguments

• $message (string) – The flash message to shown on success
• $options (array) – 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(). If a value is null, the corresponding attribute will not be rendered. See renderTagAttributes() for details on how attributes are being rendered.

Returns

string – The generated hidden input tag

Throws

• yii\base\Exception
  if the validation key could not be written
• yii\base\InvalidConfigException
  when HMAC generation fails

svg()

Since

4.3.0

Returns the contents of a given SVG file.

View source

Arguments

• $svg (string, craft\elements\Asset) – An SVG asset, a file path, or raw SVG markup
• $sanitize (boolean, null) – 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, null) – 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.
• $throwException (boolean) – Whether to throw an exception on error

Returns

string

tag()

Generates a complete HTML tag.

View source

Arguments

• $name (string, boolean, null) – The tag name. If $name is null or false, the corresponding content will be rendered without any tag.
• $content (string) – The content to be enclosed between the start and end tags. It will not be HTML-encoded. If this is coming from end users, you should consider encode() it to prevent XSS attacks.
• $options (array) – The HTML tag attributes (HTML 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(). If a value is null, the corresponding attribute will not be rendered.

For example when using ['class' => 'my-class', 'target' => '_blank', 'value' => null] it will result in the html attributes rendered like this: class="my-class" target="_blank".

See renderTagAttributes() for details on how attributes are being rendered.

Returns

string – The generated HTML tag

unwrapCondition()

Since

4.0.0

Unwraps an IE conditional comment from the given HTML.

See also \craft\helpers\wrapIntoCondition()View source

Arguments

• $content (string)

Returns

array[] – 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

Arguments

• $content (string)

Returns

array[] – 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

Arguments

• $string (string)

Returns

string

Protected Methods

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