-
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 documentation of the tag() method 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 calls.
The code for generating a tag looks like the following:
// Load the namespace
use JPWPToolkit\Helpers\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. This method can be used for generate any tag, the following methods are shorthand of this.
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 sintaxis. If $tag is empty, the corresponding content will be rendered without any tag.
$content (string) (Optional)
The content to be enclosed between the start and end tags. This parameter is ignored when is a void element.
$attrbutes (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::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.
$attrbutes (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.
$attrbutes (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.
$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 ul tag. Nested arrays are allowed.
$attrbutes (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.
Generates an open HTML tag.
Html::open( string $tag, array|string $attributes = [] );$tag (string)
Required. The HTML tag, this parameter allows some shorthands, similar to basic css selectors sintaxis. If $tag is a void element will be generated with the trailing slash.
$attrbutes (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, this parameter allows some shorthands, similar to basic css selectors sintaxis. If $tag is a void element will be generated with the trailing slash.
return (string)
The generated close HTML tag.
echo Html::close( 'p' );The code above will generate the following HTML:
</p>// Usage of $tag parameter
echo Html::tag('div');
// Outputs <div></div>
echo Html::tag('span.class-name');
// Outputs <span class="class-name"></span>
echo Html::tag('p.class-name.other-class');
// Outputs <p class="class-name other-class"></p>
echo Html::tag('foo#id');
// Outputs <foo id="id"></foo>
echo Html::tag('bar#id.class-name');
// Outputs <bar id="id" class="class-name"></bar>
// Usage of $content parameter
echo Html::tag('div', 'My content');
// Outputs <div>My content</div>
// Usage of $attibutes parameters
echo Html::tag('div', 'My content', 'id=id&class=class-name&data-attr=custom-attr');
echo Html::tag('div', 'My content', ['id' => 'id', 'class' => 'class-name', 'data-attr' => 'custom-attr']);
// Both outputs <div id="id" class="class-name" data-attr="custom-attr">My content</div>
// Self closing tags
echo Html::tag('br');
// Outputs <br />
echo Html::tag('meta', '', 'charset=utf-8');
// Outputs <meta charset="utf-8" />
// Note that $content parameter is ignored
echo Html::tag('link', 'Any content', [ 'rel' => 'icon', 'href' => 'favicon.ico']);
// Outputs <link rel="icon" href="favicon.ico" />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($email, $content = '', $attributes = []);$email (string)
The email address.
$content (string)
Arbitrary content to put inside the tag, if is empty shows the $email value.
$attrbutes (string|array)
Parse the HTML attributes to put in label, you can use query string or associative array.
echo Html::mailto('mail@domain.com', 'My Email');
// Outputs <a href="[ofuscated email]">My Email</a>
echo Html::mailto('mail@domain.com');
// Outputs <a href="[ofuscated email]">[ofuscated email]</a>
// Note that when $content is an email is ofuscated but if is an
// string that contains more than an email is passed without ofuscate
echo Html::mailto('mail@domain.com', 'mail@domain.com');
// Outputs <a href="[ofuscated email]">[ofuscated email]</a>
echo Html::mailto('mail@domain.com', 'Write to mail@domain.com');
// Outputs <a href="[ofuscated email]">Write to mail@domain.com</a>Parse the query string or associative array to convert to html attributes
Html::parse_attributes( string|array $attributes = [] );$attrbutes (string|array)
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. 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.
Allows to you use a tag name as method aliases of HTML::tag()
Html::{$tag}(string|null $content = '', string|array $attributes = []);$tag (string)
Required. The HTML tag, this parameter allows some shorthands, similar to basic css selectors sintaxis. If $tag is a void element will be generated with the trailing slash.
$content (string)
The content to be enclosed between the start and end tags. This parameter is ignored when is a void element.
$attrbutes (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 magic 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 |