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()`. 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}
 ====================================
 

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,53 @@ 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` / `yy` / `yyyy` | `2024` / `24` / `2024`
+| 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` <small>(2 číslice v kombinaci se sekundami)</small>
+| sekunda | `s` / `ss` | `8` / `08` <small>(2 číslice v kombinaci s minutami)</small>
+
+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, 2024`, zatímco v prostředí `cs_CZ` vypíše `15. dubna 2024`. 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: medium}             {* 23. 1. 1978 *}
+{$date|localDate: date: long}               {* 23. ledna 1978 *}
+{$date|localDate: date: full}               {* pondělí 23. ledna 1978 *}
+{$date|localDate: time: short}              {* 14:30 *}
+{$date|localDate: date: long, time: medium} {* 23. ledna 1978 v 14:30:59 *}
+(přesný výstup se může lišit v závislosti na prostředí)
+```
+
+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 použijete filtr bez parametrů, vypíše se datum v úrovni `long`:
+
+```latte
+{$date|localDate}   {* 15. dubna 2024 *}
+```
+
+Viz také [#date].
+
+
 lower .[filter]
 ---------------
 Převede řetězec na malá písmena. Vyžaduje PHP rozšíření `mbstring`.
@@ -475,16 +524,64 @@ 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
-{1234.20 |number:1}            1,234.2
-{1234.20 |number:2}            1,234.20
-{1234.20 |number:2, ',', ' '}  1 234,20
+{1234.20|number}              1,234
+{1234.20|number:1}            1,234.2
+{1234.20|number:2}            1,234.20
+{1234.20|number:2, ',', ' '}  1 234,20
 ```
 
 
+number(string format) .[filter]
+-------------------------------
+Parametr `format` umožňuje definovat vzhled čísel přesně podle vašich potřeb. K tomu je potřeba mít nastavené [národní prostředí |develop#locale]. Formát se skládá z několika speciálních znaků (kompletní popis najdete v dokumentaci "DecimalFormat":https://unicode.org/reports/tr35/tr35-numbers.html#Number_Format_Patterns):
+
+- `0` povinná číslice, vždy se zobrazí, i kdyby to byla nula
+- `#` volitelná číslice, zobrazí se jen tehdy, pokud na tomto místě číslo skutečně je
+- `@` významná číslice, pomáhá zobrazit číslo s určitým počtem platných číslic
+- `.` označuje, kde má být desetinná čárka (nebo tečka, podle země)
+- `,` slouží k oddělení skupin číslic, nejčastěji tisíců
+- `%` číslo vynásobí 100× a přidá znak procenta
+
+Pojďme se podívat na příkladů. Nejprve ukázka povinných vs volitelných číslic. V prvním příkladu jsou dvě desetinná místa povinná, ve druhém volitelná. Třetí příklad ukazuje doplnění nulami zleva i zprava, čtvrtý zobrazuje jen existující číslice:
+
+```latte
+{1234.5|number: '#,##0.00'}     {* 1,234.50 *}
+{1234.5|number: '#,##0.##'}     {* 1,234.5 *}
+{1.23  |number: '000.000'}      {* 001.230 *}
+{1.2   |number: '##.##'}        {* 1.2 *}
+```
+
+Významné číslice určují, kolik číslic bez ohledu na desetinou čárku má být zobrazeno, přičemž se zaokrouhluje:
+
+```latte
+{1234|number: '@@'}             {* 1200 *}
+{1234|number: '@@@'}            {* 1230 *}
+{1234|number: '@@@#'}           {* 1234 *}
+{1.2345|number: '@@@'}          {* 1.23 *}
+{0.00123|number: '@@'}          {* 0.0012 *}
+```
+
+Snadný způsob, jak zobrazit číslo jako procenta. Číslo se automaticky vynásobí 100 a přidá se znak `%`:
+
+```latte
+{0.1234|number: '#.##%'}        {* 12.34% *}
+```
+
+Můžeme definovat odlišný formát pro záporná čísla. První způsob zobrazí záporné číslo v závorkách, druhý s minusem:
+
+```latte
+{42|number: '#.##;(#.##)'}      {* 42 *}
+{-42|number: '#.##;(#.##)'}     {* (42) *}
+{42|number: '+#.##;-#.##'}      {* +42 *}
+{-42|number: '+#.##;-#.##'}     {* -42 *}
+```
+
+Pamatujte, že skutečný vzhled čísel se může mírně lišit podle nastavení země (locale). Například v některých zemích se používá čárka místo tečky jako oddělovač desetinných míst. Tento filtr to automaticky zohlední, takže se nemusíte o nic starat.
+
+
 padLeft(int length, string pad = ' ') .[filter]
 -----------------------------------------------
 Doplní řetězec do určité délky jiným řetězcem zleva.
@@ -615,7 +712,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}