latte 3.0.18

latte/cs/develop.texy

@@ -166,6 +166,22 @@ try {
 ```
 
 
+Národní prostředí .{data-version:3.0.18}{toc: Locale}
+=====================================================
+
+Latte umožňuje nastavit národní prostředí, které ovlivňuje formátování čísel, datumů a řazení. Nastavuje se pomocí metody `setLocale()` a jeho název vychází ze standardní knihovny `intl` a skládá se z kódu jazyka a případně kódu země (např. `en_US` pro angličtinu ve Spojených státech, `de_DE` pro němčinu v Německu).
+
+```php
+$latte = new Latte\Engine;
+$latte->setLocale('cs');
+```
+
+Nastavení locale ovlivňuje filtry [localDate|filters#localDate], [sort|filters#sort], [number|filters#number] a [bytes|filters#bytes].
+
+.[note]
+Vyžaduje PHP rozšíření `intl`. Nastavení locale v Latte neovlivňuje globální nastavení locale v PHP.
+
+
 Striktní režim .{data-version:3.0.8}
 ====================================
 

latte/cs/filters.texy

@@ -11,7 +11,7 @@ V šablonách můžeme používat funkce, které pomáhají upravit nebo přefor
 | `bytes`      | [formátuje velikost v bajtech |#bytes]
 | `clamp`      | [ohraničí hodnotu do daného rozsahu |#clamp]
 | `dataStream` | [konverze pro Data URI protokol |#datastream]
-| `date`       | [formátuje datum |#date]
+| `date`       | [formátuje datum a čas|#date]
 | `explode`    | [rozdělí řetězec na pole podle oddělovače |#explode]
 | `first`      | [vrací první prvek pole nebo znak řetězce |#first]
 | `group`      | [seskupí data podle různých kritérií |#group]
@@ -20,6 +20,7 @@ V šablonách můžeme používat funkce, které pomáhají upravit nebo přefor
 | `join`       | [spojí pole do řetězce |#implode]
 | `last`       | [vrací poslední prvek pole nebo znak řetězce |#last]
 | `length`     | [vrací délku řetězce ve znacích nebo pole |#length]
+| `localDate`  | [formátuje datum a čas|#localDate]
 | `number`     | [formátuje číslo |#number]
 | `padLeft`    | [doplní řetězec zleva na požadovanou délku |#padLeft]
 | `padRight`   | [doplní řetězec zprava na požadovanou délku |#padRight]
@@ -168,7 +169,7 @@ Přidává před každý znak nového řádku HTML značku `<br>`
 
 bytes(int precision = 2) .[filter]
 ----------------------------------
-Formátuje velikost v bajtech do lidsky čitelné podoby.
+Formátuje velikost v bajtech do lidsky čitelné podoby. Pokud je nastavené [národní prostředí |develop#locale], použijí se odpovídající oddělovače desetinných míst a tisíců.
 
 ```latte
 {$size|bytes}     0 B, 10 B, …
@@ -255,13 +256,14 @@ Vyžaduje PHP rozšíření `fileinfo`.
 
 date(string format) .[filter]
 -----------------------------
-Formátuje datum podle masky buď ve tvaru používaném PHP funkcí [php:strftime] nebo [php:date]. Filtr přijímá datum buď ve formátu UNIX timestamp, v podobě řetězce nebo jako objekt `DateTime`.
+Formátuje datum a čas podle masky používané PHP funkcí [php:date]. Filtr přijímá datum ve formátu UNIX timestamp, jako řetězec nebo objekt `DateTimeInterface`.
 
 ```latte
-{$today|date:'%d.%m.%Y'}
 {$today|date:'j. n. Y'}
 ```
 
+Viz také [#localDate].
+
 
 escapeUrl .[filter]
 -------------------
@@ -418,6 +420,41 @@ Vrátí délku řetězce nebo pole.
 ```
 
 
+localDate(string format = null, string date = null, string time = null) .[filter]
+---------------------------------------------------------------------------------
+Formátuje datum a čas podle aktuálního [národního prostředí |develop#locale], což zajišťuje konzistentní a lokalizované zobrazení časových údajů napříč různými jazyky a regiony. Filtr přijímá datum jako UNIX timestamp, řetězec nebo objekt `DateTimeInterface`.
+
+**a) použití vlastního formátu**
+
+Formát určuje, které časové složky se mají zobrazit. Používá písmenné kódy, jejichž počet opakování ovlivňuje šířku výstupu:
+
+- `y` vs `yyyy`: rok jako `23` vs `2023`
+- `M` vs `MM` vs `MMM` vs `MMMM`: měsíc jako `7` vs `07` vs `čvc` vs `červenec`
+- `d` vs `dd`: den jako `1` vs `01`
+- `j`: hodina v preferovaném formátu pro prostředí (12 nebo 24hodinový formát)
+- `m` vs `mm`: minuta jako `5` vs `05`
+- `s` vs `ss`: sekunda jako `8` vs `08`
+
+Výsledné pořadí složek se sestaví podle aktuálního prostředí, takže formát je **nezávislý** na národním prostředí.
+Například formát `yyyyMMMMd` v postředí `en_US` vypíše `April 15, 2023`, zatímco v prostředí `cs_CZ` vypíše `15. dubna 2023`. Formát `MMMM` bez dalších symbolů se vypíše jako `duben`.
+
+**b) použití přednastavených stylů**
+
+Parametry `date` a `time` určují úroveň detailu pro datum a čas. Možné hodnoty jsou 'full', 'long', 'medium', 'short'. Lze uvést buď jen datum, jen čas, nebo obojí:
+
+```latte
+{$date|localDate:date:'full':time:'short'}
+{* Výstup (en_US): Saturday, April 15, 2023 at 2:30 PM *}
+{* Výstup (cs_CZ): sobota 15. dubna 2023 14:30 *}
+```
+
+Pro datum lze použít prefix `relative-` (např. `relative-short`), který buď zobrazí `včera`, `dnes` nebo `zítra` pro data blízká současnosti, jinak se vypíše standardním způsobem.
+
+Pokud neuvedete žádný parametr, filtr se chová, jako by bylo `date = long`.
+
+Viz také [#date].
+
+
 lower .[filter]
 ---------------
 Převede řetězec na malá písmena. Vyžaduje PHP rozšíření `mbstring`.
@@ -475,7 +512,7 @@ Neescapovaný: <b>hello</b>
 
 number(int decimals = 0, string decPoint = '.', string thousandsSep = ',') .[filter]
 ------------------------------------------------------------------------------------
-Formátuje číslo na určitý počet desetinných míst. Lze určit znak pro desetinnou čárku a oddělovač tisíců.
+Formátuje číslo na určitý počet desetinných míst. Pokud je nastavené [národní prostředí |develop#locale], použijí se odpovídající oddělovače desetinných míst a tisíců.
 
 ```latte
 {1234.20 |number}              1,234
@@ -485,6 +522,36 @@ Formátuje číslo na určitý počet desetinných míst. Lze určit znak pro de
 ```
 
 
+number(string mask) .[filter]
+-----------------------------
+Při aktivním [národním prostředí |develop#locale] lze číslo formátovat podle vzoru, která umožňuje přesně definovat, jak má být zobrazeno. Tvoří jej symboly, tyto jsou základní:
+
+- `0` : číslice se zobrazí vždy, i když má číslo méně číslic (pak se zobrazí 0)
+- `#` : číslice se zobrazí, pokud na této pozici existuje
+- `.` : oddělovač desetinných míst dle národního prostředí
+- `,` : oddělovač skupin (obvykle tisíců) dle národního prostředí
+- `-` : znaménko minus pro záporná čísla
+- `@` : zajišťuje, že se zobrazí určitý počet platných číslic bez ohledu na desetinnou čárku
+
+Příklady (přesný výstup závisí na nastaveném prostředí):
+
+```latte
+{* Základní formátování *}
+{1234.5|number: '#,##0.00'}     {* vypíše: 1,234.50 *}
+{1234.5|number: '#,##0.##'}     {* vypíše: 1,234.5 *}
+
+{* Platné číslice *}
+{1234.5|number: '@@@'}          {* vypíše: 1230 *}
+{1.23456|number: '@@@'}         {* vypíše: 1.23 *}
+
+{* Zarovnání *}
+{12.3|number: '000.00'}         {* vypíše: 012.30 *}
+{3.14|number: '##0.00*_'}       {* vypíše: 3.14___ *}
+```
+
+Tento pattern systém nabízí mnoho dalších možností formátování, včetně vědecké notace, negativních vzorů a dalších. Pro pokročilé použití doporučujeme nahlédnout do "oficiální dokumentace Unicode DecimalFormat":[https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/classDecimalFormat.html#:~:text=%7D-,patterns,-A%20DecimalFormat%20consists].
+
+
 padLeft(int length, string pad = ' ') .[filter]
 -----------------------------------------------
 Doplní řetězec do určité délky jiným řetězcem zleva.
@@ -615,7 +682,7 @@ Ve výchozím nastavení filtr změní pořadí a resetuje celočíselného klí
 
 sort(?Closure comparison, string|int|\Closure|null by=null, string|int|\Closure|bool byKey=false) .[filter]
 -----------------------------------------------------------------------------------------------------------
-Filtr slouží k seřazení prvků v poli nebo iterátoru, přičemž zachovává asociační klíče:
+Filtr seřadí prvky pole nebo iterátoru a zachová jejich asociační klíče. Při nastaveném [národním prostředí |develop#locale] se řazení řídí jeho pravidly, pokud není specifikována vlastní porovnávací funkce.
 
 ```latte
 {foreach ($names|sort) as $name}