-
Notifications
You must be signed in to change notification settings - Fork 0
Html class
Important: This documentation is still under construction, methods and/or properties may be missing or not fully documented
The Html class is a helper that provides a set of static methods for generating commonly used HTML tags.
Nearly all of the methods in this class allow setting additional attributes for the HTML tags they generate. You can specify, for example, class, style or id for an HTML element using the $attributes parameter. See the HTML::tag() for more details.
Note: If your markup is nearly static, it's better to use HTML directly. There's no need to wrap absolutely everything in Html helper class.
The code for generating a tag looks like the following:
// Load the namespace
use JPToolkit\HtmlHelper\Html;
echo Html::tag( 'p', 'Lorem ipsum dolor sit amet', ['class' => 'text-justify'] );The first argument is the tag name. The second one is the content to be enclosed between the start and end tags. The third one is an array of HTML attributes. In this array the key is the name of the attribute (such as class, href or target), and the value is its value. You can also use a query string to set the tag attributes.
The code above will generate the following HTML:
<p class="text-justify">Lorem ipsum dolor sit amet</p>Generates a complete HTML tag. Can be used for generate any tag, some of the other methods in this class are partially a shorthand of this method.
Html::tag( string $tag, string $content = '', array|string $attributes = [] )$tag (string) (Required)
The HTML tag, this parameter allows some shorthands, similar to basic css selectors syntax. See Html::parse_shorthand() for more details.
$content (string) (Optional)
The content to be enclosed between the start and end tags. This parameter is ignored when is a void element.
$attributes (array|string) (Optional)
Associative array of attributes with name-value pairs. These will be rendered as HTML attributes of the resulting tag. See Html::parse_attributes() for more details.
return (string)
The generated HTML tag. If $tag is empty, the corresponding content will be rendered without any tag.
echo Html::tag( 'p', 'Lorem ipsum dolor sit amet', ['class' => 'text-justify'] );The code above will generate the following HTML:
<p class="text-justify">Lorem ipsum dolor sit amet</p>Generates an img tag. Note that it is not the intention of this method to replace WordPress functions such as get_post_thumbnail() or wp_get_attachment_image().
Html::img( string $src, array|string $attributes = [] )$src (string) (Required)
The $src parameter allow a url or data:image, however in this parameter you can add filters to allows use of shorthands, please refer to pixel, not_available or placeholder shorthand documentation for more information.
$attributes (array|string) (Optional)
Associative array of attributes with name-value pairs. These will be rendered as HTML attributes of the resulting tag. See Html::parse_attributes() for more details.
return (string)
The generated HTML tag
echo Html::img( 'http://path/to/image.jpg', [ 'class' => 'img-fluid' ] );The code above will generate the following HTML:
<img src="http://path/to/image.jpg" class="img-fluid" />Generates an unordered list.
Html::ul( array $list, array|string $attributes = []);$list (array) (Required)
An array with elements to list in ul tag. Nested arrays are allowed.
$attributes (array|string) (Optional)
Associative array of attributes with name-value pairs. These will be rendered as HTML attributes of the root ul tag. See Html::parse_attributes() for more details.
$simple_list = [ 'red', 'blue', 'green', 'yellow' ];
echo Html::ul( $simple_list );The code above will generate a simple list:
<ul>
<li>red</li>
<li>blue</li>
<li>green</li>
<li>yellow</li>
</ul>$nested_list = [
'colors' => [ 'red', 'blue', 'green', 'yellow' ],
'numbers' => [ 'one', 'two', 'three', 'four', ]
];
echo Html::ol( $nested_list );The code above will generate a nested list:
<ul>
<li>colors
<ul>
<li>red</li>
<li>blue</li>
<li>green</li>
<li>yellow</li>
</ul>
</li>
<li>numbers
<ul>
<li>one</li>
<li>two</li>
<li>three</li>
<li>four</li>
</ul>
</li>
</ul>Generates an ordered list. See Html::ul() for more details.
Html::ul( array $list, array|string $attributes = []);$list (array) (Required)
An array with elements to list in ol tag. Nested arrays are allowed.
$attributes (array|string) (Optional)
Associative array of attributes with name-value pairs. These will be rendered as HTML attributes of the root ul tag. See Html::parse_attributes() for more details.
Generates an open HTML tag.
Html::open( string $tag, array|string $attributes = [] );$tag (string) (Required)
The HTML tag, if $tag is a void element will be generated with the trailing slash. See the HTML::tag() for more details.
$attributes (array|string) (Optional)
Associative array of attributes with name-value pairs. These will be rendered as HTML attributes of the resulting tag. See Html::parse_attributes() for more details.
return (string)
The generated open HTML tag.
echo Html::open( 'p', ['class' => 'text-justify'] );The code above will generate the following HTML:
<p class="text-justify">Generates a close HTML tag.
Html::close( string $tag );$tag (string) (Required)
The HTML tag.
return (string)
The generated close HTML tag. if $tag is a void element returns an empty string.
echo Html::close( 'p' );The code above will generate the following HTML:
</p>Builds a mailto link with converted email addresses characters to HTML entities to block spam bots. This function uses the WordPress' function antispambot().
Html::mailto( string $email, string $content = '', array|string $attributes = []);$email (string) (Required)
The email address.
$content (string) (Optional)
Arbitrary content to put inside the tag, if is empty shows the encoded $email value. If $content is an email it's also encoded.
$attributes (array|string) (Optional)
Associative array of attributes with name-value pairs. These will be rendered as HTML attributes of the resulting tag. See Html::parse_attributes() for more details.
return (string)
The generated open HTML tag.
echo Html::mailto('mail@domain.com', 'Write to me');The code above will generate the following HTML:
<a href="[encoded email]">Write to me</a>echo Html::mailto('mail@domain.com', 'mail@domain.com');
echo Html::mailto('mail@domain.com', 'Write to mail@domain.com');The code above will generate the following HTML:
<!-- The first one encode $email and $content -->
<a href="[encoded email]">[encoded email]</a>
<!-- The second one encode only $email -->
<a href="[encoded email]">Write to mail@domain.com</a>Parse the query string or associative array to convert to HTML attributes
Note: This method is still in beta, the behavior of this method may be change in the future for make this method more consistent when an array or a query string is passed as
$attributes. Please read the know issues of this method for more details.
Html::parse_attributes( array|string $attributes = [] );$attributes (array|string)
The HTML tag attributes in terms of name-value pairs. These will be rendered as the attributes of the resulting tag, you can use query string or associative array. This will be parsed using wp_parse_args() and the values will be escaped using the esc_attr().
return (string)
The generated attributes for HTML tag
$attributes = [
// defined, will be generated as pair key/value
'attribute_defined' => 'value',
// empty string, will be generated as pair key/value
'attribute_empty' => '',
// null, will be generated as key only
'attribute_null' => null,
// false, will not be generated
'attribute_false' => false,
// true, will be generated as key only
'attribute_true' => true,
// value only, will be generated as key only
'only_value',
];
echo Html::parse_attributes( $attributes );The code above will generate the following string:
attribute_defined="value" attribute_empty="" attribute_null attribute_true only_valueNote that the attribute with value false is omitted, when the value is true, null or don't have a name, then is rendered as boolean attribute. A practical example for this behavior like the following:
$attributes = [
'class' => 'form-control',
'type' => 'text',
'readonly' => false,
'value' => '',
'disabled' => null,
'required',
];
echo Html::tag( 'input', '', $attributes );The code above will generate the following string:
<input class="form-control" type="text" value="" disabled required />Note that, in this example, the readonly attribute is not rendered but the disabled and required does as boolean attribute.
Some issues may occur when uses a query string instead an array as $attributes, see the next example passing the same $attributes of the previous example as query string:
$attributes = 'class=form-control&type=text&readonly=false&value=&disabled=null&required';
echo Html::tag( 'input', '', $attributes );This will generate the following code
<input class="form-control" type="text" readonly="false" value="" disabled="null" required="" />Note that all attributes are rendered, this is because $attributes is a query string that is parsed using wp_parse_args() and all values are interpreted as string, even empty ones.
Parse a shorthand for a HTML tag, this allow to the Html::tag() method to use shorthands similar to the CSS selectors to define a tag with attributes, the attributes allowed are class and id.
Note: This method is still in beta, the behavior of visibility of this method may be change in the future for allow override or concatenate when an attribute exists in the
$attributesargument. Please read the know issues of this method for more details.
Html::parse_shorthand(string &$tag, array &$attributes)$tag (string) (Required)
The HTML tag, this parameter allows some shorthands, similar to basic CSS selectors syntax.
$attributes (array) (Required)
Associative array of attributes with name-value pairs.
echo Html::tag( 'h1#page-title.text-center', 'My page title' );This will generate the following code
<h1 id="page-title" class="text-center">My page title</h1>Some issues may occur when class and/or id exists in the $attributes array:
$attributes = [
'id' => 'page-subtitle',
'class' => 'text-center'
];
echo Html::tag( 'h1#page-title.text-center', 'My page title', $attributes );This will generate the following code
<h1 id="page-subtitle" class="text-center">My page title</h1>Note that id and class are defined in the $attributes argument, then these attributes aren't updated, the behavior of this method may be change in the future.
Allows to you use a tag name as method aliases of HTML::tag()
Html::{tag}( string $content = '', array|string $attributes = []);$content (string)
The content to be enclosed between the start and end tags. This parameter is ignored when is a void element.
$attributes (string|array)
Associative array of attributes with name-value pairs. These will be rendered as HTML attributes of the resulting tag, you can also use a query string. The values will be escaped using the esc_attr(). See the documentation of the parse_attributes() method for more details.
return (string)
The generated HTML tag
// Using tag() method
echo Html::tag( 'p', 'Lorem ipsum dolor sit amet', ['class' => 'text-justify'] );
// Using overloaded method
echo Html::p( 'Lorem ipsum dolor sit amet', ['class' => 'text-justify'] );Both codes above will generate the following HTML:
<p class="text-justify">Lorem ipsum dolor sit amet</p>| Version | Description |
|---|---|
| 0.1.0 | Introduced |