latte 3.0.18

dg · dg · commit 7670171a0b49 · 2024-08-06T18:56:38.000+02:00
diff --git a/latte/cs/develop.texy b/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()`. Identifikátor prostředí se řídí standardem IETF language tag, který používá rozšíření PHP `intl`. 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 atd.
+
+```php
+$latte = new Latte\Engine;
+$latte->setLocale('cs');
+```
+
+Nastavení prostředí ovlivňuje filtry [localDate|filters#localDate], [sort|filters#sort], [number|filters#number] a [bytes|filters#bytes].
+
+.[note]
+Vyžaduje PHP rozšíření `intl`. Nastavení v Latte neovlivňuje globální nastavení locale v PHP.
+
+
 Striktní režim .{data-version:3.0.8}
 ====================================
 
diff --git a/latte/cs/filters.texy b/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 podle národního prostředí|#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 typu `DateTimeInterface`.
 
 ```latte
-{$today|date:'%d.%m.%Y'}
 {$today|date:'j. n. Y'}
 ```
 
+Viz také [#localDate].
+
 
 escapeUrl .[filter]
 -------------------
@@ -418,6 +420,46 @@ 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 [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 typu `DateTimeInterface`.
+
+**a) použití formátu**
+
+Parametr `format` popisuje, které časové složky se mají zobrazit. Používá pro ně písmenné kódy, jejichž počet opakování ovlivňuje šířku výstupu:
+
+| rok | `y` / `yyyy` | `23` / `2023`
+| měsíc | `M` / `MM` / `MMM` / `MMMM` | `7` / `07` / `čvc` / `červenec`
+| den | `d` / `dd` | `1` / `01`
+| hodina | `j` | v preferovaném formátu prostředí
+| minuta | `m` / `mm` | `5` / `05`
+| sekunda | `s` / `ss` | `8` / `08`
+
+Na pořadí kódů ve formátu nezáleží, protože pořadí složek se vypíše podle zvyklostí národního prostředí. Formát je tedy na něm nezávislý.
+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`. Nebo samotné `MMMM` se vypíše jako `duben`, atd.
+
+**b) použití přednastavených stylů**
+
+Parametry `date` a `time` určují, jak podrobně se má datum a čas vypsat. Můžete si vybrat z několika úrovní: `full`, `long`, `medium`, `short`. Lze nechat vypsat jen datum, jen čas, nebo obojí:
+
+```latte
+{$date|localDate: date: short}             {* 23.01.1978 *}
+{$date|localDate: date: long}              {* 23. ledna 1978 *}
+{$date|localDate: time: short}             {* 14:30 *}
+{$date|localDate: date: long, time: short} {* sobota 15. dubna 2023 v 14:30 *}
+```
+
+U data lze navíc použít prefix `relative-` (např. `relative-short`), který pro data blízká současnosti zobrazí `včera`, `dnes` nebo `zítra`, jinak se vypíše standardním způsobem.
+
+```latte
+{$date|localDate: date: relative-short}  {* včera *}
+```
+
+Pokud neuvedete žádný parametr, použije se `date: long`.
+
+Viz také [#date].
+
+
 lower .[filter]
 ---------------
 Převede řetězec na malá písmena. Vyžaduje PHP rozšíření `mbstring`.
@@ -475,7 +517,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 +527,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 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 +687,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}
