-
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 Helper file contains functions that assist in working with HTML, 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>Build an arbitray HTML tag.
Html::tag($tag, $content = '', $attributes = []);$tag (string)
The HTML tag, this parameter allows some shorthands, similar to basic css selectors sintaxis.
$content (string)
Arbitrary content to put inside the tag. This parameter is ignored when is a void element.
$attrbutes (string|array)
Parse the HTML attributes to put in label, you can use query string or associative array.
// 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" />Build an ordered/unordered list.
Html::ol($list, $attributes = []);
Html::ul($list, $attributes = []);$list (array)
Array with elements to list in ul/ol tag. Nested arrays is allowed, see example.
$attrbutes (string|array)
Parse the HTML attributes to put in label, you can use query string or associative array.
$simple_list = [ 'red', 'blue', 'green', 'yellow' ];
echo Html::ul( $simple_list )
// Outputs
// <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 );
// Outputs
// <ol>
// <li>colors
// <ol>
// <li>red</li>
// <li>blue</li>
// <li>green</li>
// <li>yellow</li>
// </ol>
// </li>
// <li>numbers
// <ol>
// <li>one</li>
// <li>two</li>
// <li>three</li>
// <li>four</li>
// </ol>
// </li>
// </ol>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>Generates a complete HTML tag.
Html::tag( string $tag, string $content = '', array $attributes = [] );$tag (string)
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)
The content to be enclosed between the start and end tags. This parameter is ignored when is a void element.
$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(). See the documentation of the parse_attributes() method 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)
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 (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(). See the documentation of the parse_attributes() method 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 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 (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(). See the documentation of the parse_attributes() method 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>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)
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(). 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>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.
| Version | Description |
|---|---|
| 0.1.0 | Introduced |