diff --git a/latte/cs/extending-latte.texy b/latte/cs/extending-latte.texy index 867d8813e8..5afc3ef335 100644 --- a/latte/cs/extending-latte.texy +++ b/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] -------------------------------------------------- diff --git a/latte/cs/html-attributes.texy b/latte/cs/html-attributes.texy index a527c29562..836a7c5d80 100644 --- a/latte/cs/html-attributes.texy +++ b/latte/cs/html-attributes.texy @@ -153,6 +153,14 @@ Chcete-li vložit důvěryhodné HTML, předejte ho jako objekt `Latte\Runtime\H 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 =============== diff --git a/latte/en/extending-latte.texy b/latte/en/extending-latte.texy index 27bb6cd8f0..f5fb4a3782 100644 --- a/latte/en/extending-latte.texy +++ b/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] -------------------------------------------------- diff --git a/latte/en/html-attributes.texy b/latte/en/html-attributes.texy index 136df96046..22c071ecbf 100644 --- a/latte/en/html-attributes.texy +++ b/latte/en/html-attributes.texy @@ -153,6 +153,14 @@ To insert trusted HTML, pass it as a `Latte\Runtime\Html` object. Its markup is 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 =============