Skip to content

Commit b9698c7

Browse files
dgdg
committed
nette/mail 4.1.0
1 parent 2011fb4 commit b9698c7

2 files changed

Lines changed: 144 additions & 0 deletions

File tree

‎mail/cs/@home.texy‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -176,6 +176,78 @@ V šabloně potom vytváříme odkazy tak, jak jsme zvyklí. Všechny odkazy vyt
176176
```
177177

178178

179+
Inlinování CSS
180+
==============
181+
182+
[api:Nette\Mail\CssInliner] převádí CSS pravidla na inline atributy `style`, aby se e-maily zobrazovaly správně ve všech klientech. Zároveň generuje HTML atributy pro kompatibilitu s Outlookem.
183+
184+
.[note]
185+
Vyžaduje PHP 8.4 nebo novější a rozšíření `dom`.
186+
187+
Většina e-mailových klientů má omezenou podporu značky `<style>` nebo ji zcela ignoruje. Pro správné zobrazení je proto potřeba převést CSS pravidla na inline atributy `style` u jednotlivých elementů. Stačí HTML předat metodě `inline()`:
188+
189+
```php
190+
$inliner = new Nette\Mail\CssInliner;
191+
$html = $inliner->inline($html);
192+
```
193+
194+
Pokud HTML obsahuje například:
195+
196+
```html
197+
<style>
198+
p { margin: 0; color: #333; }
199+
a { color: #a0704e; }
200+
</style>
201+
<p>Hello <a href="#">world</a></p>
202+
```
203+
204+
Výsledek po inlinování bude (značka `<style>` se zachová, zde ji vynecháváme pro stručnost):
205+
206+
```html
207+
<p style="margin: 0; color: #333">Hello <a href="#" style="color: #a0704e">world</a></p>
208+
```
209+
210+
Značka `<style>` zůstane ve výstupu vždy zachována, takže `@media` dotazy a další pravidla, která nelze inlinovat, budou nadále fungovat.
211+
212+
Kromě extrakce stylů ze značek `<style>` lze CSS dodat i metodou `addCss()`. Inlinování je třeba provést před předáním HTML do `setHtmlBody()`:
213+
214+
```php
215+
$latte = new Latte\Engine;
216+
$params = [
217+
'orderId' => 123,
218+
];
219+
220+
$html = $latte->renderToString('/path/to/email.latte', $params);
221+
$html = (new Nette\Mail\CssInliner)
222+
->addCss(file_get_contents('/path/to/email.css'))
223+
->inline($html);
224+
225+
$mail = new Nette\Mail\Message;
226+
$mail->setHtmlBody($html);
227+
```
228+
229+
Pokud je stejná CSS vlastnost nastavena z více zdrojů, pozdější přepisují dřívější. Pravidla ze značek `<style>` mají nejnižší prioritu, následují pravidla přidaná přes `addCss()`. Pokud element již má inline atribut `style` v HTML, ten má vždy nejvyšší prioritu.
230+
231+
At-rules jako `@media` nebo `@font-face` se při inlinování přeskakují. Pseudo-třídy jako `:hover` nelze smysluplně inlinovat, protože inline styly nepodporují dynamické stavy.
232+
233+
234+
HTML atributy pro Outlook
235+
-------------------------
236+
237+
Desktopové verze Microsoft Outlooku používají vykreslovací jádro Wordu, které nerozumí mnoha CSS vlastnostem. Pro zajištění kompatibility `CssInliner` automaticky generuje odpovídající HTML atributy z CSS pravidel vedle inline stylů:
238+
239+
| CSS vlastnost | HTML atribut | Aplikuje se na
240+
|-----------------------------------------------------
241+
| `background-color` | `bgcolor` | `<table>`, `<td>`, `<th>`, `<body>`, `<tr>`
242+
| `width` | `width` | `<table>`, `<td>`, `<th>`, `<img>`
243+
| `height` | `height` | `<table>`, `<td>`, `<th>`, `<img>`
244+
| `border-spacing` | `cellspacing` | `<table>`
245+
246+
U `width`, `height` a `cellspacing` se automaticky odstraní jednotka `px` (např. `width: 600px` se převede na `width="600"`). Inline styl i HTML atribut se nastaví vždy společně, takže se e-mail zobrazí správně v moderních klientech i v Outlooku.
247+
248+
HTML atributy se generují pouze z CSS pravidel zpracovaných třídou `CssInliner`, nikoliv z atributů `style` již přítomných v původním HTML.
249+
250+
179251
Odeslání e-mailu
180252
================
181253

‎mail/en/@home.texy‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -176,6 +176,78 @@ In the template, you then create links as you are used to. All links created via
176176
```
177177

178178

179+
CSS Inlining
180+
============
181+
182+
[api:Nette\Mail\CssInliner] converts CSS rules into inline `style` attributes so that emails render consistently across all clients. It also generates HTML attributes for Outlook compatibility.
183+
184+
.[note]
185+
Requires PHP 8.4 or later and the `dom` extension.
186+
187+
Most email clients have limited support for `<style>` tags or ignore them entirely. To ensure correct rendering, CSS rules need to be converted to inline `style` attributes on individual elements. Simply pass your HTML through `inline()`:
188+
189+
```php
190+
$inliner = new Nette\Mail\CssInliner;
191+
$html = $inliner->inline($html);
192+
```
193+
194+
For example, if the HTML contains:
195+
196+
```html
197+
<style>
198+
p { margin: 0; color: #333; }
199+
a { color: #a0704e; }
200+
</style>
201+
<p>Hello <a href="#">world</a></p>
202+
```
203+
204+
The result after inlining will be (the `<style>` tag is preserved but omitted here for brevity):
205+
206+
```html
207+
<p style="margin: 0; color: #333">Hello <a href="#" style="color: #a0704e">world</a></p>
208+
```
209+
210+
The `<style>` tag is always preserved in the output, so `@media` queries and other rules that cannot be inlined keep working.
211+
212+
In addition to extracting styles from `<style>` tags, you can also provide CSS via the `addCss()` method. You need to inline CSS before passing the HTML to `setHtmlBody()`:
213+
214+
```php
215+
$latte = new Latte\Engine;
216+
$params = [
217+
'orderId' => 123,
218+
];
219+
220+
$html = $latte->renderToString('/path/to/email.latte', $params);
221+
$html = (new Nette\Mail\CssInliner)
222+
->addCss(file_get_contents('/path/to/email.css'))
223+
->inline($html);
224+
225+
$mail = new Nette\Mail\Message;
226+
$mail->setHtmlBody($html);
227+
```
228+
229+
When the same CSS property is set by multiple sources, later sources override earlier ones. Rules from `<style>` tags have the lowest priority, followed by rules added via `addCss()`. If an element already has an inline `style` attribute in the HTML, it always takes the highest precedence.
230+
231+
At-rules like `@media` or `@font-face` are skipped during inlining. Note that pseudo-classes like `:hover` cannot be meaningfully inlined, since inline styles do not support dynamic states.
232+
233+
234+
HTML Attributes for Outlook
235+
---------------------------
236+
237+
Desktop versions of Microsoft Outlook use the Word rendering engine, which doesn't understand many CSS properties. To ensure compatibility, `CssInliner` automatically generates corresponding HTML attributes from CSS rules alongside inline styles:
238+
239+
| CSS Property | HTML Attribute | Applied To
240+
|-----------------------------------------------------
241+
| `background-color` | `bgcolor` | `<table>`, `<td>`, `<th>`, `<body>`, `<tr>`
242+
| `width` | `width` | `<table>`, `<td>`, `<th>`, `<img>`
243+
| `height` | `height` | `<table>`, `<td>`, `<th>`, `<img>`
244+
| `border-spacing` | `cellspacing` | `<table>`
245+
246+
For `width`, `height`, and `cellspacing`, the `px` unit is automatically stripped (e.g., `width: 600px` becomes `width="600"`). Both the inline style and the HTML attribute are always set, so the email renders correctly in modern clients and Outlook alike.
247+
248+
HTML attributes are generated only from CSS rules processed by `CssInliner`, not from `style` attributes already present in the original HTML.
249+
250+
179251
Sending Emails
180252
==============
181253

0 commit comments

Comments
 (0)