Skip to content

Commit dd01f2c

Browse files
vranaclaude
andcommitted
latte: documented Extension::getAttributeContexts()
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 4442db6 commit dd01f2c

4 files changed

Lines changed: 54 additions & 0 deletions

File tree

‎latte/cs/extending-latte.texy‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -219,6 +219,25 @@ public function getProviders(): array
219219
```
220220

221221

222+
getAttributeContexts(): array .[method]{data-version:3.2.0}
223+
-----------------------------------------------------------
224+
225+
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:
226+
227+
```php
228+
public function getAttributeContexts(): array
229+
{
230+
return [
231+
'x-on:*' => Latte\ContentType::JavaScript, // obsluha událostí v Alpine.js
232+
'@*' => Latte\ContentType::JavaScript, // zkratka @click z Alpine.js
233+
'data-tippy-content' => Latte\ContentType::Html, // tooltip Tippy.js s volbou allowHTML
234+
];
235+
}
236+
```
237+
238+
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.
239+
240+
222241
getCacheKey(Latte\Engine $engine): mixed .[method]
223242
--------------------------------------------------
224243

‎latte/cs/html-attributes.texy‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -153,6 +153,14 @@ Chcete-li vložit důvěryhodné HTML, předejte ho jako objekt `Latte\Runtime\H
153153
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 `{...}`.
154154

155155

156+
Atributy JavaScriptových knihoven .{data-version:3.2.0}
157+
=======================================================
158+
159+
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.
160+
161+
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}`.
162+
163+
156164
Typová kontrola
157165
===============
158166

‎latte/en/extending-latte.texy‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -219,6 +219,25 @@ public function getProviders(): array
219219
```
220220

221221

222+
getAttributeContexts(): array .[method]{data-version:3.2.0}
223+
-----------------------------------------------------------
224+
225+
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:
226+
227+
```php
228+
public function getAttributeContexts(): array
229+
{
230+
return [
231+
'x-on:*' => Latte\ContentType::JavaScript, // Alpine.js event handlers
232+
'@*' => Latte\ContentType::JavaScript, // Alpine.js shorthand @click
233+
'data-tippy-content' => Latte\ContentType::Html, // Tippy.js tooltip with allowHTML
234+
];
235+
}
236+
```
237+
238+
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.
239+
240+
222241
getCacheKey(Latte\Engine $engine): mixed .[method]
223242
--------------------------------------------------
224243

‎latte/en/html-attributes.texy‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -153,6 +153,14 @@ To insert trusted HTML, pass it as a `Latte\Runtime\Html` object. Its markup is
153153
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.
154154

155155

156+
Attributes of JavaScript Libraries .{data-version:3.2.0}
157+
========================================================
158+
159+
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.
160+
161+
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}`.
162+
163+
156164
Type Checking
157165
=============
158166

0 commit comments

Comments
 (0)