Add an `attr` function to make outputting HTML attributes easier #3930

mpdude · 2023-12-06T22:14:16Z

Closes #3907.

First, it adds a attr_merge filter. This filter is intended to be used with arrays that represent HTML attribute name-value pairs. Basically, it works like |merge, but for the special key names class, style and data it performs merging on the value level.

This is intended for the use case where you'd like to add to the attributes for an HTML element based on conditions, e. g. multiple subsequent {% if ... %} blocks.

Example:

{ class: 'foo' }|attr_merge({ class: 'bar' }) will be { class: ['foo', 'bar'] }
{ class: 'foo' }|attr_merge({ class: ['bar', 'baz'] }) will be { class: ['foo', 'bar', 'baz'] }
{ class: { special: 'foo' } }|attr_merge({ class: ['bar', 'baz'] })|attr_merge({ class: {special: 'qux' } }) will be { class: { special: 'qux', 0: 'bar', 1: 'baz' } }

or in Twig code:

{% set attr = attr ?? {} %}
{% if condition1 %}
  {% set attr = attr|attr_merge({ class: 'foo', data: { condition1: 'met' }) %}
{% endif %}
{% if condition2 %}
  {% set attr = attr|attr_merge({ class: 'bar', data: { condition2: 'met' }) %}
{% endif %}

Second, it adds a attr function. This function takes one or multiple attr arrays like above, and print them as a series of HTML attribute markup. All values from class will be concatenated with spaces. Key/value pairs from style will be treated as CSS property/value pairs. For data, keys will be used to construct data-{keyname} attributes.

Example:


    {% set id = 'id value' %}
    {% set href = 'href value' %}
    {% set disabled = true %}

    <div {{ attr(
        { id, href },
        disabled ? { 'aria-disabled': 'true' },
        not disabled ? { 'aria-enabled' : true },
        { class: ['zero', 'first'] },
        { class: 'second' },
        true ? { class: 'third' },
        { style: { color: 'red' } },
        { style: { 'background-color': 'green' } },
        { style: { color: 'blue' } },
        { 'data-test': 'some value' },
        { data: { test: 'other value', bar: 'baz' }},
        { 'dangerous=yes foo' : 'xss' },
        { style: 'font-weight: bold' },
        { style: ['text-decoration: underline'] },
    ) }}></div>

will generate HTML markup:

<div id="id value" href="href%20value" aria-disabled="true" data-test="other value" data-bar="baz" dangerous&#x3D;yes&#x20;foo="xss" class="zero first second third" style="color: red; background-color: green; color: blue; font-weight: bold; text-decoration: underline;"></div>

TODO:

Get initial feedback
Add tests
Add documentation
Add docblocks

fabpot

I like it a lot. Let's continue the work. Tell me of you need help @mpdude

extra/html-extra/HtmlExtension.php

fabpot · 2024-09-26T19:59:45Z

extra/html-extra/HtmlExtension.php

+
+    $result = '';
+    foreach ($attr as $name => $value) {
+        $result .= twig_escape_filter($env, $name, 'html_attr').'="'.htmlspecialchars($value).'" ';


Let's consider false as a way to disable the attribute? And true would not generate the value part?

I guess that makes sense. I'd have false omit the attribute output altogether. For true, I'd use something like name="name" for backwards compat with (X)HTML.

⚠️ "true" must be written "true" for some enumerated aria attributes.

Almost everywhere else, indeed, false should remove/hide the attribute.

"" should not happen, i guess, but should be dealt with attention, because the following have all the same meaning:

disabled=""

disabled

disabled="false"

disabled="disabled"

For the aria cases, if you want, there is some classic cases + docs here

https://github.com/symfony/ux/blob/647532ab688f79acfbcb1c895e88a8b2f1a502f6/src/Icons/src/Icon.php#L139-L162

with some test cases if you need too https://github.com/symfony/ux/blob/647532ab688f79acfbcb1c895e88a8b2f1a502f6/src/Icons/tests/Unit/IconTest.php#L226

(other similar in the TwigComponent / ComponentAttributes)

Except for aria-* attributes that support keyword and enumerated values. In some cases aria-* attributes support true and false string values.

https://hidde.blog/boolean-attributes-in-html-and-aria-whats-the-difference/

https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#keywords-and-enumerated-attributes

https://www.w3.org/TR/wai-aria-1.1/#typemapping

Fortunately, Twig and PHP have separate types for strings and booleans. Passing the string true or false will not trigger the special logic for boolean values.

@stof I guess what I was trying to say is that yes you could pass 'true' or 'false' as parameters but this would require string coercion when setting the value.

The previous comment stated that:

Almost everywhere else, indeed, false should remove/hide the attribute.

I was pointing out that aria-* attributes do accept a string value of 'false' and in those cases a coercion of bool false to string 'false' might be warranted. This could also apply to data-* attributes.

IMO:

null value always removes the attribute from the final string rendering.

true and false values for aria-* attributes should coerce boolean to their string values 'true' and 'false'

true and false values for all other attributes should act as boolean html attributes. ie true renders the attribute, false removes the attribute (as per @fabpot comment).

extra/html-extra/HtmlExtension.php

mpdude · 2024-09-30T21:19:51Z

@fabpot Regarding tests: I suppose the fixture-based tests (*.test) are necessary to do integration testing, e. g. including the escaping mechanism? Should I go for such tests or write plain PHPUnit tests instead?

What's the best way to cover lots of scenarios in the fixture-style tests? It's easy to get lost when there are lots of cases but just one --TEMPLATE-- and one --EXPECT-- section.

fabpot · 2024-10-04T06:00:27Z

@fabpot Regarding tests: I suppose the fixture-based tests (*.test) are necessary to do integration testing, e. g. including the escaping mechanism? Should I go for such tests or write plain PHPUnit tests instead?

You can write both, but .test tests are easier to write and read.

What's the best way to cover lots of scenarios in the fixture-style tests? It's easy to get lost when there are lots of cases but just one --TEMPLATE-- and one --EXPECT-- section.

That's indeed a current limitation.

fabpot · 2024-10-04T06:01:32Z

extra/html-extra/HtmlExtension.php

@@ -124,4 +130,85 @@ public static function htmlCva(array|string $base = [], array $variants = [], ar
    {
        return new Cva($base, $variants, $compoundVariants, $defaultVariant);
    }
+
+    public static function htmlAttrMerge(...$arrays): array


We can maybe have a @param to better describe $arrays?

extra/html-extra/HtmlExtension.php

fabpot · 2024-10-04T06:03:27Z

extra/html-extra/HtmlExtension.php

+        return $result;
+    }
+
+    public static function htmlAttr(Environment $env, ...$args): string


Maybe a @param for $args?

extra/html-extra/HtmlExtension.php

smnandre · 2024-10-04T22:31:53Z

extra/html-extra/HtmlExtension.php

+    {
+        $result = [];
+
+        foreach ($arrays as $argNumber => $array) {


Not guaranteed that we have a number here.

extra/html-extra/HtmlExtension.php

smnandre · 2024-10-04T22:36:03Z

extra/html-extra/HtmlExtension.php

+
+                    $value = CoreExtension::toArray($value);
+
+                    $result[$deepMergeKey] = array_merge($result[$deepMergeKey] ?? [], $value);


Can we use [... ] when we can ? As it's slightly more performant than array_merge

@smnandre Like this? 717f872

smnandre · 2024-10-04T22:38:02Z

extra/html-extra/HtmlExtension.php

+                if (is_numeric($name)) {
+                    $style .= $value.'; ';
+                } else {
+                    $style .= $name.': '.$value.'; ';
+                }


I'm not sure why this specific case for style.. i may have missed the reason earlier in the discussion ?

In case style is something like ['color: red', 'font-weight: bold'].

I have two other questions then (sorry)

What if "aria" is something like ['aria-disabled', 'aria-current'] ?

Does that mean i can do something like this ?

{{ html_attr( { style: ['color: red;'] }, { style: {'color': 'blue'} }, { style: {'color': 'green'} }, { style: ['', 'color: black;'] }, ) }}

I'm shared between "i understand each of these usages" and "this could be very un-predictable when/if args are assembled from different layers / templates :|

Yes, definetly many edge cases I haven't thought through. Make sure you don't miss the inital idea in #3907, fwiw.

I think we should aim for behaviour similar to array_merge and not try to do any kind of parsing/interpretation. For example:

html_attr_merge( { style: {'color': 'blue'} }, { style: {'color': 'green'} } } ) }} would be { style: {'color': 'green'} }

html_attr_merge( { style: ['color: blue'] }, { style: { ['color: green']} } } ) }} would be { style: ['color: blue', 'color: green'] } – if you want "real" overrides, use semantic keys

html_attr_merge( { aria: { 'aria-label': 'that' }, {'label': 'this'} } ) would be { 'aria-label': 'this' } – I'd rewrite keys from the aria and data sub-array to the "flat" values first and then merge those.

I hope I can come up with reasonable test cases for all those situations so we can discuss them before merge.

mpdude · 2024-10-07T17:23:30Z

Added a first load of tests for the html_attr_merge function

Co-authored-by: Fabien Potencier <[email protected]>

leevigraham · 2024-10-21T23:25:00Z

For reference

Yii2 has a similar function: https://github.com/yiisoft/yii2/blob/master/framework/helpers/BaseHtml.php#L1966-L2046

The renderTagAttributes method has the following rules:

Attributes whose values are of boolean type will be treated as boolean attributes.
Attributes whose values are null will not be rendered.
aria and data attributes get special handling when they are set to an array value. In these cases, the array will be "expanded" and a list of ARIA/data attributes will be rendered. For example, 'aria' => ['role' => 'checkbox', 'value' => 'true'] would be rendered as aria-role="checkbox" aria-value="true".
If a nested data value is set to an array, it will be JSON-encoded. For example, 'data' => ['params' => ['id' => 1, 'name' => 'yii']] would be rendered as data-params='{"id":1,"name":"yii"}'.

CraftCMS uses twig and provides an attr() twig method that implements renderTagAttributes. I've used this helper many times and the rules above are great. Especially the "Attributes whose values are null will not be rendered".

Vuejs v2 -> v3 also went through some changes for false values https://v3-migration.vuejs.org/breaking-changes/attribute-coercion.html. This aligns with "Attributes whose values are null will not be rendered." above.

leevigraham · 2024-10-22T04:27:11Z

extra/html-extra/HtmlExtension.php

+            }
+
+            if (!is_iterable($array)) {
+                throw new RuntimeError(sprintf('The "attr_merge" filter only works with mappings or "Traversable", got "%s" for argument %d.', \gettype($array), $argNumber + 1));


Should this be " The html_attr_merge filter only…" . What if the exception is thrown when using the html_attr function.

leevigraham · 2024-10-22T08:32:28Z

How will merging of attributes that support multiple values work? Eg aria-labelledby value is an ID reference list.

Example:

<div {{ attr(
        {'aria-labelledby': 'id1 id2'},
        {'aria-labelledby': 'id3'},
    ) }}></div>

Should the result be:

First value set: {'aria-labelledby': 'id1 id2'}
Last value set: {'aria-labelledby': 'id3'}
Concatenated (like class): {'aria-labelledby': 'id1 id2 id3'}

This could also apply to data-controller which is used by stimulusjs and Symfony ux components.

leevigraham · 2024-10-23T00:05:54Z

@mpdude @fabpot @smnandre I've combined my comments above into a POC here: #4405

mpdude marked this pull request as draft December 6, 2023 22:15

mpdude force-pushed the add-attr-function branch from b680b5f to 9c29c4d Compare December 7, 2023 08:25

This was referenced Dec 7, 2023

Add "html_attributes" twig filter for easiely write attributes as objects twigphp/html-extra#4

Closed

Add "html_attributes" twig filter for easiely write attributes as objects #3760

Closed

Helper function to make dealing with HTML attributes easier #3907

Open

kbond mentioned this pull request Jan 23, 2024

[Twig] Add attributes() twig function symfony/ux#1414

Open

fabpot requested changes Sep 26, 2024

View reviewed changes

fabpot mentioned this pull request Sep 26, 2024

added html_attr function to the HtmlExtension extension #3199

Closed

fabpot reviewed Sep 26, 2024

View reviewed changes

jdreesen reviewed Sep 26, 2024

View reviewed changes

extra/html-extra/HtmlExtension.php Outdated Show resolved Hide resolved

mpdude force-pushed the add-attr-function branch from f65ee8f to c9acca6 Compare September 30, 2024 20:56

fabpot reviewed Sep 30, 2024

View reviewed changes

extra/html-extra/HtmlExtension.php Outdated Show resolved Hide resolved

mpdude force-pushed the add-attr-function branch from f7c3b7a to c7bacfd Compare September 30, 2024 21:10

Add an attr function to make outputting HTML attributes easier

03a5de1

mpdude force-pushed the add-attr-function branch from c7bacfd to 03a5de1 Compare September 30, 2024 21:10

mpdude commented Sep 30, 2024

View reviewed changes

extra/html-extra/HtmlExtension.php Show resolved Hide resolved

mpdude added 2 commits September 30, 2024 23:21

Support boolean attribute values

e3a74bd

Add a first test POC

aef2551

fabpot requested changes Oct 4, 2024

View reviewed changes

fabpot force-pushed the 3.x branch from 6df7e6d to 1876635 Compare October 4, 2024 18:59

smnandre reviewed Oct 4, 2024

View reviewed changes

extra/html-extra/HtmlExtension.php Outdated Show resolved Hide resolved

smnandre reviewed Oct 4, 2024

View reviewed changes

Add tests for key merging

9722108

mpdude force-pushed the add-attr-function branch from cf673c1 to 9722108 Compare October 7, 2024 17:23

Use [... ] instead of array_merge#

717f872

mpdude and others added 3 commits October 7, 2024 19:27

Update extra/html-extra/HtmlExtension.php

09ff3b4

Co-authored-by: Fabien Potencier <[email protected]>

Fix CS

799fb28

Add initial functional test for the html_attr_merge filter

0f694fd

leevigraham reviewed Oct 22, 2024

View reviewed changes

leevigraham mentioned this pull request Oct 22, 2024

RFC / WIP - html_attributes function #4405

Draft

3 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add an `attr` function to make outputting HTML attributes easier #3930

Add an `attr` function to make outputting HTML attributes easier #3930

mpdude commented Dec 6, 2023 •

edited by fabpot

Loading

fabpot left a comment

fabpot Sep 26, 2024

mpdude Sep 30, 2024

smnandre Oct 4, 2024

smnandre Oct 5, 2024

leevigraham Oct 22, 2024

stof Oct 23, 2024

leevigraham Oct 23, 2024

mpdude commented Sep 30, 2024

fabpot commented Oct 4, 2024

fabpot Oct 4, 2024

fabpot Oct 4, 2024

smnandre Oct 4, 2024

smnandre Oct 4, 2024

mpdude Oct 7, 2024

smnandre Oct 4, 2024

mpdude Oct 5, 2024

smnandre Oct 5, 2024

mpdude Oct 7, 2024

mpdude commented Oct 7, 2024

leevigraham commented Oct 21, 2024 •

edited

Loading

leevigraham Oct 22, 2024 •

edited

Loading

leevigraham commented Oct 22, 2024 •

edited

Loading

leevigraham commented Oct 23, 2024


		$value = CoreExtension::toArray($value);

		$result[$deepMergeKey] = array_merge($result[$deepMergeKey] ?? [], $value);

Add an attr function to make outputting HTML attributes easier #3930

Are you sure you want to change the base?

Add an attr function to make outputting HTML attributes easier #3930

Conversation

mpdude commented Dec 6, 2023 • edited by fabpot Loading

TODO:

fabpot left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mpdude commented Sep 30, 2024

fabpot commented Oct 4, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mpdude commented Oct 7, 2024

leevigraham commented Oct 21, 2024 • edited Loading

leevigraham Oct 22, 2024 • edited Loading

Choose a reason for hiding this comment

leevigraham commented Oct 22, 2024 • edited Loading

leevigraham commented Oct 23, 2024

Add an `attr` function to make outputting HTML attributes easier #3930

Add an `attr` function to make outputting HTML attributes easier #3930

mpdude commented Dec 6, 2023 •

edited by fabpot

Loading

leevigraham commented Oct 21, 2024 •

edited

Loading

leevigraham Oct 22, 2024 •

edited

Loading

leevigraham commented Oct 22, 2024 •

edited

Loading