From 0199950f9937534197f01c5ef3ea3dc2ed542e48 Mon Sep 17 00:00:00 2001 From: David Grudl Date: Tue, 6 Aug 2024 02:32:22 +0200 Subject: [PATCH] latte 3.0.18 --- latte/cs/develop.texy | 16 +++++++++ latte/cs/filters.texy | 79 +++++++++++++++++++++++++++++++++++++++---- 2 files changed, 89 insertions(+), 6 deletions(-) diff --git a/latte/cs/develop.texy b/latte/cs/develop.texy index 396ba77813..b72f70bbed 100644 --- 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á i knihovna `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). + +```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 index 60c7e1877f..d99b069599 100644 --- 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|#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 `
` 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 [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 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, 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 +512,7 @@ Neescapovaný: hello 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 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}