tag() Twig function

CHANGELOG-v3.3.md

@@ -1,6 +1,7 @@
 # Running Release Notes for Craft CMS 3.3
 
 ## Added
+- Added the `tag()` Twig function, which renders a complete HTML tag.
 - Added the `|attr` Twig filter, which modifies the attributes on an HTML tag. ([#4660](https://github.com/craftcms/cms/issues/4660))
 - Added the `purgeStaleUserSessionDuration` config setting..
 - Control Panel subnav items can now have badge counts. ([#4756](https://github.com/craftcms/cms/issues/4756))

docs/dev/functions.md

@@ -358,6 +358,37 @@ Returns the content of a template without rendering it.
 
 This works identically to Twig’s core [`source`](https://twig.symfony.com/doc/2.x/functions/source.html) function.
 
+## `tag`
+
+Renders a complete HTML tag.
+
+```twig
+{{ tag('div', {
+    class: 'foo'
+}) }}
+{# Output: <div class="foo"></div> #}
+```
+
+If `text` is included in the attributes argument, its value will be HTML-encoded and set as the text contents of the tag.
+
+```twig
+{{ tag('div', {
+    text: 'Hello'
+}) }}
+{# Output: <div>Hello</div> #}
+```
+
+If `html` is included in the attributes argument (and `text` isn’t), its value will be set as the inner HTML of the tag (without getting HTML-encoded).
+
+```twig
+{{ tag('div', {
+    html: 'Hello<br>world'
+}) }}
+{# Output: <div>Hello<br>world</div> #}
+```
+
+All other keys passed to the second argument will be set as attributes on the tag, using <api:yii\helpers\BaseHtml::renderTagAttributes()>.
+
 ## `template_from_string`
 
 Loads a template from a string.

src/web/twig/Extension.php

@@ -526,6 +526,7 @@ public function atomFilter(TwigEnvironment $env, $date, $timezone = null): strin
      * @param string $tag The HTML tag whose attributes should be modified.
      * @param array $attributes The attributes to be added to the tag.
      * @return string The modified HTML tag.
+     * @since 3.3.0
      */
     public function attrFilter(string $tag, array $attributes): string
     {
@@ -793,6 +794,7 @@ public function getFunctions(): array
             new TwigFunction('shuffle', [$this, 'shuffleFunction']),
             new TwigFunction('siteUrl', [UrlHelper::class, 'siteUrl']),
             new TwigFunction('svg', [$this, 'svgFunction']),
+            new TwigFunction('tag', [$this, 'tagFunction'], ['is_safe' => ['html']]),
             new TwigFunction('url', [UrlHelper::class, 'url']),
             // DOM event functions
             new TwigFunction('head', [$this->view, 'head']),
@@ -1045,6 +1047,28 @@ public function svgFunction($svg, bool $sanitize = null, bool $namespace = null,
         return TemplateHelper::raw($svg);
     }
 
+    /**
+     * Generates a complete HTML tag.
+     *
+     * @param string $type the tag type ('p', 'div', etc.)
+     * @param array $attributes the HTML tag attributes in terms of name-value pairs.
+     * If `text` is supplied, the value will be HTML-encoded and included as the contents of the tag.
+     * If 'html' is supplied, the value will be included as the contents of the tag, without getting encoded.
+     * @return string
+     * @since 3.3.0
+     */
+    public function tagFunction(string $type, array $attributes = []): string
+    {
+        $html = ArrayHelper::remove($attributes, 'html', '');
+        $text = ArrayHelper::remove($attributes, 'text');
+
+        if ($text !== null) {
+            $html = Html::encode($text);
+        }
+
+        return Html::tag($type, $html, $attributes);
+    }
+
     /**
      * @inheritdoc
      */