Latte attribute contexts

latte/cs/extending-latte.texy

@@ -219,6 +219,25 @@ public function getProviders(): array
 ```
 
 
+getAttributeContexts(): array .[method]{data-version:3.2.0}
+-----------------------------------------------------------
+
+Volá se před kompilací a vykreslením šablony. Latte escapuje hodnotu každého atributu podle toho, co s ní udělá prohlížeč: atributy `on*` jako `onclick` obsahují JavaScript, `style` obsahuje CSS a `srcdoc` celý HTML dokument. JavaScriptové knihovny přidávají vlastní atributy tohoto druhu, o nich ale Latte nemůže vědět, a tak je escapuje jako kterýkoliv jiný atribut. To nestačí: prohlížeč hodnotu atributu dekóduje a knihovna výsledek spustí jako kód nebo ho vloží do stránky jako HTML. Tato metoda Latte řekne, co takové atributy obsahují. Vrací pole, jehož klíči jsou názvy atributů a hodnotami `Latte\ContentType::JavaScript`, `Latte\ContentType::Css` nebo `Latte\ContentType::Html`. Název končící `*` pokryje všechny atributy začínající daným prefixem:
+
+```php
+public function getAttributeContexts(): array
+{
+	return [
+		'x-on:*' => Latte\ContentType::JavaScript, // obsluha událostí v Alpine.js
+		'@*' => Latte\ContentType::JavaScript, // zkratka @click z Alpine.js
+		'data-tippy-content' => Latte\ContentType::Html, // tooltip Tippy.js s volbou allowHTML
+	];
+}
+```
+
+Latte pak tyto atributy escapuje přesně jako jejich vestavěné protějšky: `x-on:click` jako `onclick` a `data-tippy-content` jako `srcdoc` (viz [HTML dokument v atributu srcdoc |html-attributes#HTML dokument v atributu srcdoc]). Platí to pro všechny způsoby zápisu atributu včetně `n:attr`. Na velikosti písmen v názvech nezáleží, a pokud stejný název zaregistruje více rozšíření, platí to poslední. Vestavěné atributy `on*`, `style` a `srcdoc` předefinovat nelze. Kontexty nemusíte zahrnovat do `getCacheKey()`, Latte s nimi počítá samo.
+
+
 getCacheKey(Latte\Engine $engine): mixed .[method]
 --------------------------------------------------
 

latte/cs/html-attributes.texy

@@ -133,6 +133,34 @@ Stejně jako `class` přijímají i atributy `aria-` pole. To se zpracuje jako s
 ```
 
 
+HTML dokument v atributu srcdoc .{data-version:3.2.0}
+=====================================================
+
+Atribut `srcdoc` elementu `<iframe>` obsahuje celý HTML dokument. Latte proto hodnotu escapuje dvakrát: nejprve jako HTML text a poté jako atribut. Řetězec se v rámu zobrazí jako prostý text a nemůže do něj vložit žádné značky:
+
+```latte
+<iframe srcdoc={$text}></iframe>
+```
+
+Pokud `$text` obsahuje `<b>Ahoj</b>`, vykreslí se:
+
+```latte
+<iframe srcdoc="&amp;lt;b&amp;gt;Ahoj&amp;lt;/b&amp;gt;"></iframe>
+```
+
+Chcete-li vložit důvěryhodné HTML, předejte ho jako objekt `Latte\Runtime\Html`. Jeho značky zůstanou zachovány a escapuje se jen jednou, jako atribut, takže stejný obsah se vykreslí jako `srcdoc="&lt;b&gt;Ahoj&lt;/b&gt;"`.
+
+Předchozí verze vkládaly řetězce jako HTML. Takové hodnoty odhalí [migrační varování |develop#Migrační varování], pokud je hodnotou atributu jediný výraz `{...}`.
+
+
+Atributy JavaScriptových knihoven .{data-version:3.2.0}
+=======================================================
+
+Latte ví, že atributy `on*` jako `onclick` obsahují JavaScript, `style` obsahuje CSS a `srcdoc` HTML dokument, a podle toho escapuje hodnoty v nich. Knihovny jako Alpine.js nebo Tippy.js přinášejí vlastní atributy tohoto druhu, např. `x-on:click` s JavaScriptovým kódem nebo `data-tippy-content` s HTML. Ve výchozím stavu je Latte escapuje jako kterýkoliv jiný atribut. To nestačí: prohlížeč hodnotu atributu dekóduje a knihovna výsledek spustí jako kód nebo ho vloží do stránky jako HTML.
+
+Co tyto atributy obsahují, můžete Latte sdělit v [rozšíření |extending-latte#getAttributeContexts]. Pak se `x-on:click="select({$item})"` escapuje přesně jako `onclick="select({$item})"` a `data-tippy-content={$help}` přesně jako `srcdoc={$help}`.
+
+
 Typová kontrola
 ===============
 

latte/en/extending-latte.texy

@@ -219,6 +219,25 @@ public function getProviders(): array
 ```
 
 
+getAttributeContexts(): array .[method]{data-version:3.2.0}
+-----------------------------------------------------------
+
+It is called before the template is compiled and rendered. Latte escapes each attribute value according to what the browser does with it: `on*` attributes such as `onclick` contain JavaScript, `style` contains CSS and `srcdoc` a whole HTML document. JavaScript libraries add their own attributes of this kind, but Latte cannot know about them and escapes them like any other attribute. That is not enough: the browser decodes the attribute, and the library then runs the result as code or inserts it into the page as HTML. This method tells Latte what such attributes contain. It returns an array whose keys are attribute names and whose values are `Latte\ContentType::JavaScript`, `Latte\ContentType::Css` or `Latte\ContentType::Html`. A name ending with `*` covers all attributes starting with that prefix:
+
+```php
+public function getAttributeContexts(): array
+{
+	return [
+		'x-on:*' => Latte\ContentType::JavaScript, // Alpine.js event handlers
+		'@*' => Latte\ContentType::JavaScript, // Alpine.js shorthand @click
+		'data-tippy-content' => Latte\ContentType::Html, // Tippy.js tooltip with allowHTML
+	];
+}
+```
+
+Latte then escapes these attributes exactly like their built-in counterparts: `x-on:click` like `onclick` and `data-tippy-content` like `srcdoc` (see [HTML documents in srcdoc |html-attributes#HTML Documents in srcdoc]). This applies to every way of writing an attribute, including `n:attr`. Names are case-insensitive, and if several extensions register the same name, the last one wins. The built-in attributes `on*`, `style` and `srcdoc` cannot be redefined. You don't have to include the contexts in `getCacheKey()` because Latte takes them into account itself.
+
+
 getCacheKey(Latte\Engine $engine): mixed .[method]
 --------------------------------------------------
 

latte/en/html-attributes.texy

@@ -133,6 +133,34 @@ Just like `class`, `aria-` attributes also accept an array. It is treated as a s
 ```
 
 
+HTML Documents in srcdoc .{data-version:3.2.0}
+==============================================
+
+The `srcdoc` attribute of `<iframe>` contains a whole HTML document. Latte therefore escapes a value twice: first as HTML text and then as an attribute. A string is displayed in the frame as plain text and cannot inject any markup:
+
+```latte
+<iframe srcdoc={$text}></iframe>
+```
+
+If `$text` is `<b>Hi</b>`, it renders:
+
+```latte
+<iframe srcdoc="&amp;lt;b&amp;gt;Hi&amp;lt;/b&amp;gt;"></iframe>
+```
+
+To insert trusted HTML, pass it as a `Latte\Runtime\Html` object. Its markup is kept and escaped only once, as an attribute, so the same content renders as `srcdoc="&lt;b&gt;Hi&lt;/b&gt;"`.
+
+Previous versions inserted strings as HTML. The [migration warnings |develop#Migration Warnings] point out such values when the entire attribute value is a single `{...}` expression.
+
+
+Attributes of JavaScript Libraries .{data-version:3.2.0}
+========================================================
+
+Latte knows that `on*` attributes such as `onclick` contain JavaScript, `style` contains CSS and `srcdoc` an HTML document, and escapes values in them accordingly. Libraries such as Alpine.js or Tippy.js bring their own attributes of this kind, e.g. `x-on:click` with JavaScript code or `data-tippy-content` with HTML. By default, Latte escapes them like any other attribute. That is not enough: the browser decodes the attribute, and the library then runs the result as code or inserts it into the page as HTML.
+
+You can tell Latte what these attributes contain in an [extension |extending-latte#getAttributeContexts]. Then `x-on:click="select({$item})"` is escaped exactly like `onclick="select({$item})"`, and `data-tippy-content={$help}` exactly like `srcdoc={$help}`.
+
+
 Type Checking
 =============