latte 3.0.18

nette · Aug 6, 2024 · 1ab035c · 1ab035c
1 parent 2226b07
commit 1ab035c
Show file tree

Hide file tree

Showing 4 changed files with 246 additions and 20 deletions.
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,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ů, jejichž 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říklady. 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 vynásobí 100× a přidá se znak `%`:
+
+```latte
+{0.1234|number: '#.##%'}        {* 12.34% *}
+```
+
+Můžeme definovat odlišný formát pro kladná a záporná čísla, odděluje je znak `;`. Tímto způsobem lze například nastavit, že kladná čísla se mají zobrazovat se znaménkem `+`:
+
+```latte
+{42|number: '#.##;(#.##)'}      {* 42 *}
+{-42|number: '#.##;(#.##)'}     {* (42) *}
+{42|number: '+#.##;-#.##'}      {* +42 *}
+{-42|number: '+#.##;-#.##'}     {* -42 *}
+```
+
+Pamatujte, že skutečný vzhled čísel se může lišit podle nastavení země. 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í a nemusíte se 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}

diff --git a/latte/en/develop.texy b/latte/en/develop.texy
@@ -166,6 +166,22 @@ try {
 ```
 
 
+Locale .{data-version:3.0.18}
+=============================
+
+Latte allows you to set the locale, which affects the formatting of numbers, dates, and sorting. It is set using the `setLocale()` method. The locale identifier follows the IETF language tag standard, which uses the PHP `intl` extension. It consists of a language code and possibly a country code, for example, `en_US` for English in the United States, `de_DE` for German in Germany, etc.
+
+```php
+$latte = new Latte\Engine;
+$latte->setLocale('cs');
+```
+
+The locale setting affects the filters [localDate|filters#localDate], [sort|filters#sort], [number|filters#number], and [bytes|filters#bytes].
+
+.[note]
+Requires the PHP `intl` extension. The setting in Latte does not affect the global locale setting in PHP.
+
+
 Strict Mode .{data-version:3.0.8}
 =================================
 

diff --git a/latte/en/filters.texy b/latte/en/filters.texy
@@ -11,7 +11,7 @@ Filters are functions that change or format the data to a form we want. This is
 | `bytes`      | [formats size in bytes |#bytes]
 | `clamp`      | [clamps value to the range |#clamp]
 | `dataStream` | [Data URI protocol conversion |#datastream]
-| `date`       | [formats date |#date]
+| `date`       | [formats the date and time|#date]
 | `explode`    | [splits a string by the given delimiter |#explode]
 | `first`      | [returns first element of array or character of string |#first]
 | `group`      | [groups data according to various criteria |#group]
@@ -20,6 +20,7 @@ Filters are functions that change or format the data to a form we want. This is
 | `join`       | [joins an array to a string |#implode]
 | `last`       | [returns last element of array or character of string |#last]
 | `length`     | [returns length of a string or array |#length]
+| `localDate`  | [formats the date and time according to the locale|#localDate]
 | `number`     | [formats number |#number]
 | `padLeft`    | [completes the string to given length from left |#padLeft]
 | `padRight`   | [completes the string to given length from right |#padRight]
@@ -168,7 +169,7 @@ Inserts HTML line breaks before all newlines.
 
 bytes(int precision = 2) .[filter]
 ----------------------------------
-Formats a size in bytes to human-readable form.
+Formats the size in bytes into a human-readable form. If the [locale |develop#locale] is set, the corresponding decimal and thousand separators are used.
 
 ```latte
 {$size|bytes}     0 B, 1.25 GB, …
@@ -255,13 +256,14 @@ Requires PHP extension `fileinfo`.
 
 date(string format) .[filter]
 -----------------------------
-Returns a date in the given format using options of [php:strftime] or [php:date] PHP functions. Filter gets a date as a UNIX timestamp, a string or an object of `DateTime` type.
+Formats the date and time according to the mask used by the PHP function [php:date]. The filter accepts the date in UNIX timestamp format, as a string, or as a `DateTimeInterface` object.
 
 ```latte
-{$today|date:'%d.%m.%Y'}
 {$today|date:'j. n. Y'}
 ```
 
+See also [#localDate].
+
 
 escapeUrl .[filter]
 -------------------
@@ -418,6 +420,53 @@ Returns length of a string or array.
 ```
 
 
+localDate(string format = null, string date = null, string time = null) .[filter]
+---------------------------------------------------------------------------------
+Formats date and time according to the [locale |develop#locale], ensuring consistent and localized display of time data across different languages and regions. The filter accepts the date as a UNIX timestamp, string, or `DateTimeInterface` object.
+
+**a) Using the format**
+
+The `format` parameter describes which time components should be displayed. It uses letter codes, where the number of repetitions affects the width of the output:
+
+| Year | `y` / `yy` / `yyyy` | `2024` / `24` / `2024`
+| Month | `M` / `MM` / `MMM` / `MMMM` | `7` / `07` / `Jul` / `July`
+| Day | `d` / `dd` | `1` / `01`
+| Hour | `j` | in the preferred format of the locale
+| Minute | `m` / `mm` | `5` / `05` <small>(2 digits when combined with seconds)</small>
+| Second | `s` / `ss` | `8` / `08` <small>(2 digits when combined with minutes)</small>
+
+The order of codes in the format does not matter, as the order of components will be displayed according to the locale conventions. Therefore, the format is locale-independent.
+For example, the format `yyyyMMMMd` in the `en_US` locale will display `April 15, 2024`, while in the `cs_CZ` locale it will display `15. dubna 2024`. Similarly, `MMMM` alone will display `duben`, etc.
+
+**b) Using preset styles**
+
+The `date` and `time` parameters determine the level of detail for the date and time display. You can choose from several levels: `full`, `long`, `medium`, `short`. You can display just the date, just the time, or both:
+
+```latte
+{$date|localDate: date: short}              {* 1/23/78 *}
+{$date|localDate: date: medium}             {* Jan 23, 1978 *}
+{$date|localDate: date: long}               {* January 23, 1978 *}
+{$date|localDate: date: full}               {* Monday, January 23, 1978 *}
+{$date|localDate: time: short}              {* 2:30 PM *}
+{$date|localDate: date: long, time: medium} {* January 23, 1978 at 2:30:59 PM *}
+(exact output may vary depending on the locale)
+```
+
+For the date, you can also use the prefix `relative-` (e.g., `relative-short`), which for dates close to the present will display `yesterday`, `today`, or `tomorrow`; otherwise, it will display in the standard way.
+
+```latte
+{$date|localDate: date: relative-short}    {* yesterday *}
+```
+
+If you use the filter without parameters, the date will be displayed at the `long` level:
+
+```latte
+{$date|localDate}   {* April 15, 2024 *}
+```
+
+See also [#date].
+
+
 lower .[filter]
 ---------------
 Converts a value to lowercase. Requires PHP extension `mbstring`.
@@ -475,16 +524,64 @@ Misuse of the `noescape` filter can lead to an XSS vulnerability! Never use it u
 
 number(int decimals = 0, string decPoint = '.', string thousandsSep = ',') .[filter]
 ------------------------------------------------------------------------------------
-Formats a number to given number of decimal places. You can also specify a character of the decimal point and thousands separator.
+Formats a number to a specified number of decimal places. If the [locale |develop#locale] is set, the corresponding decimal and thousand separators are used.
 
 ```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]
+-------------------------------
+The `format` parameter allows you to define the appearance of numbers exactly according to your needs. It requires a set [locale |develop#locale]. The format consists of several special characters, the complete description of which can be found in the "DecimalFormat":https://unicode.org/reports/tr35/tr35-numbers.html#Number_Format_Patterns documentation:
+
+- `0` mandatory digit, always displayed even if it's zero
+- `#` optional digit, displayed only if the number has a digit in that place
+- `@` significant digit, helps to display the number with a certain number of significant digits
+- `.` marks where the decimal separator should be (comma or dot, depending on the locale)
+- `,` used to separate groups of digits, usually thousands
+- `%` multiplies the number by 100 and adds the percent sign
+
+Let's look at some examples. In the first example, two decimal places are mandatory; in the second, they are optional. The third example shows padding with zeros on both sides, and the fourth displays only the existing digits:
+
+```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 *}
+```
+
+Significant digits determine how many digits, regardless of the decimal point, should be displayed, rounding the number if necessary:
+
+```latte
+{1234|number: '@@'}             {* 1200 *}
+{1234|number: '@@@'}            {* 1230 *}
+{1234|number: '@@@#'}           {* 1234 *}
+{1.2345|number: '@@@'}          {* 1.23 *}
+{0.00123|number: '@@'}          {* 0.0012 *}
+```
+
+An easy way to display a number as a percentage. The number is multiplied by 100 and the `%` sign is added:
+
+```latte
+{0.1234|number: '#.##%'}        {* 12.34% *}
+```
+
+We can define a different format for positive and negative numbers, separated by a `;` character. This way, for example, positive numbers can be displayed with a `+` sign:
+
+```latte
+{42|number: '#.##;(#.##)'}      {* 42 *}
+{-42|number: '#.##;(#.##)'}     {* (42) *}
+{42|number: '+#.##;-#.##'}      {* +42 *}
+{-42|number: '+#.##;-#.##'}     {* -42 *}
+```
+
+Remember that the actual appearance of numbers may vary depending on the locale settings. For example, in some countries, a comma is used instead of a dot as a decimal separator. This filter automatically accounts for this, so you don't need to worry about it.
+
+
 padLeft(int length, string pad = ' ') .[filter]
 -----------------------------------------------
 Pads a string to a certain length with another string from left.
@@ -615,7 +712,7 @@ Filter will reorder and reset the integer array keys by default. This behaviour
 
 sort(?Closure comparison, string|int|\Closure|null by=null, string|int|\Closure|bool byKey=false) .[filter]
 -----------------------------------------------------------------------------------------------------------
-The filter is used to sort the elements in an array or iterator while preserving the association keys:
+The filter sorts elements of an array or iterator while preserving their associative keys. When a [locale |develop#locale] is set, the sorting follows its rules unless a custom comparison function is specified.
 
 ```latte
 {foreach ($names|sort) as $name}