1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
|
``html_attr``
=============
.. _html_attr:
.. versionadded:: 3.23
The ``html_attr`` function was added in Twig 3.24.
The ``html_attr`` function renders HTML attributes from one or more mappings,
taking care of proper escaping. The mappings contain the names of HTML
attributes as keys, and the corresponding values represent the attributes'
values.
.. note::
Attribute names are escaped using the ``html_attr_relaxed`` strategy.
.. code-block:: html+twig
<div {{ html_attr({class: ['foo', 'bar'], id: 'main'}) }}>
Content
</div>
{# Output: <div class="foo bar" id="main">Content</div> #}
The function accepts multiple attribute maps. Internally, it uses
:ref:`html_attr_merge` to combine the arguments:
.. code-block:: html+twig
{% set base_attrs = {class: ['btn']} %}
{% set variant_attrs = {class: ['btn-primary'], disabled: true} %}
<button {{ html_attr(base_attrs, variant_attrs) }}>
Click me
</button>
{# Output: <button class="btn btn-primary" disabled="">Click me</button> #}
.. note::
To make best use of the special merge behavior of ``html_attr_merge`` and
to avoid confusion, you should consistently use iterables (mappings or sequences)
for attributes that can take multiple values, like ``class``, ``srcset`` or ``aria-describedby``.
Use non-iterable values for attributes that contain a single value only, like
``id`` or ``href``.
Shorthand notation for mappings can be particularly helpful:
.. code-block:: html+twig
{% set id = 'user-123' %}
{% set href = '/profile' %}
<a {{ html_attr({id, href}) }}>Profile</a>
{# Output: <a id="user-123" href="/profile">Profile</a> #}
``null`` and Boolean Attribute Values
-------------------------------------
``null`` values always omit printing an attribute altogether.
The boolean ``false`` value also omits the attribute altogether, with an
exception for ``aria-*`` attribute names, see below.
.. code-block:: html+twig
{# null omits the attribute entirely, and so does false for non-"aria-*" #}
<input {{ html_attr({disabled: false, title: null}) }}>
{# Output: <input> #}
``true`` will print the attribute with the empty value ``""``. This is XHTML compatible,
and in HTML 5 equivalent to using the short attribute notation without a value. An exception
is made for ``data-*`` and ``aria-*`` attributes, see below.
.. code-block:: html+twig
{# true becomes an empty string value #}
<input {{ html_attr({required: true}) }}>
{# Output: <input required="">, which is equivalent to <input required> #}
Array Values
------------
Attribute values that are iterables are automatically converted to space-separated
token lists of the values. Exceptions apply for ``data-*`` and ``style`` attributes,
described further below.
.. code-block:: html+twig
<div {{ html_attr({class: ['btn', 'btn-primary', 'btn-lg']}) }}>
Button
</div>
{# Output: <div class="btn btn-primary btn-lg">Button</div> #}
.. note::
This is not bound to the ``class`` attribute name, but works for any attribute.
You can use the :ref:`html_attr_type` filter to specify a different strategy for
concatenating values (e.g., comma-separated for ``srcset`` attributes). This would
also override the special behavior for ``data-*`` and ``style``.
WAI-ARIA Attributes
-------------------
To make it more convenient to work with the `WAI-ARIA type mapping for HTML
<https://www.w3.org/TR/wai-aria-1.2/#typemapping>_`, boolean values for ``aria-*``
attributes are converted to strings ``"true"`` and ``"false"``.
.. code-block:: html+twig
<button {{ html_attr({'aria-pressed': true, 'aria-hidden': false}) }}>
Toggle
</button>
{# Output: <button aria-pressed="true" aria-hidden="false">Toggle</button> #}
Data Attributes
---------------
For ``data-*`` attributes, boolean ``true`` values will be converted to ``"true"``.
Values that are not scalars are automatically JSON-encoded.
.. code-block:: html+twig
<div {{ html_attr({'data-config': {theme: 'dark', size: 'large'}, 'data-bool': true, 'data-false': false}) }}>
Content
</div>
{# Output: <div data-config="{"theme":"dark","size":"large"}" data-bool="true">Content</div> #}
Style Attribute
----------------
The ``style`` attribute name has special handling when its value is iterable:
.. code-block:: html+twig
{# Non-numeric keys will be used as CSS properties and printed #}
<div {{ html_attr({style: {color: 'red', 'font-size': '16px'}}) }}>
Styled text
</div>
{# Output: <div style="color: red; font-size: 16px;">Styled text</div> #}
{# Numeric keys will be assumed to have values that are individual CSS declarations #}
<div {{ html_attr({style: ['color: red', 'font-size: 16px']}) }}>
Styled text
</div>
{# Output: <div style="color: red; font-size: 16px;">Styled text</div> #}
{# Merging style attributes #}
<div {{ html_attr({style: {color: 'red'}}, {style: {color: 'blue', background: 'white'}}) }}>
Styled text
</div>
{# Output: <div style="color: blue; background: white;">Styled text</div> #}
.. warning::
No additional escaping specific to CSS is applied to key or values from this array.
Do not use it to pass untrusted, user-provided data, neither as key nor as value.
``AttributeValueInterface`` Implementations
-------------------------------------------
For advanced use cases, attribute values can be objects that implement the ``AttributeValueInterface``.
These objects can define their own conversion logic for the ``html_attr`` function that will take
precedence over all rules described here. See the docblocks in that interface for details.
.. note::
The ``html_attr`` function is part of the ``HtmlExtension`` which is not
installed by default. Install it first:
.. code-block:: bash
$ composer require twig/html-extra
Then, on Symfony projects, install the ``twig/extra-bundle``:
.. code-block:: bash
$ composer require twig/extra-bundle
Otherwise, add the extension explicitly on the Twig environment::
use Twig\Extra\Html\HtmlExtension;
$twig = new \Twig\Environment(...);
$twig->addExtension(new HtmlExtension());
.. seealso::
:ref:`html_attr_merge`,
:ref:`html_attr_type`
|
