Latte: jeden řádek a lokalizuje za vás

Klíčovou novinkou Latte verze 3.0.18 je možnost nastavit národní prostředí. Je to otázka jednoho řádku kódu:

$latte = new Latte\Engine;
$latte->setLocale('cs_CZ');

Tímto jednoduchým krokem zajistíte, že všechny lokalizované filtry budou respektovat české prostředí. Můžete samozřejmě použít jakýkoli platný IETF language tag, například en_US pro angličtinu ve Spojených státech nebo de_DE pro němčinu v Německu.

Nastavení prostředí ovlivňuje filtry sort, number, bytes a zbrusu nový filtr localDate.

Nový filtr |localDate

Tento filtr je opravdovým klenotem nové verze. Umožňuje vypisovat data a časy s ohledem na místní zvyklosti. Nabízí dva hlavní způsoby použití, které pokryjí prakticky všechny vaše potřeby při formátování časových údajů.

Parametr format

Jde o řetězec, který umožňuje přesně specifikovat, jak má výsledné datum vypadat. Něco podobného znáte z PHP funkcí date() nebo strftime(). Ale pozor, tento formát je v něčem magický. Přizpůsobí se jakémukoli jazyku. Pojďme si to ukázat.

{$date|localDate: 'd MMMM yyyy'}

Písmena d, M a y představují den, měsíc a rok, yyyy značí, že rok se má vypsat v plné čtyřčíselné formě, obdobně „dlouhé“ MMMM značí měsíc celým slovem. Ale co pořadí dne a měsíce? Nebo oddělovače? Ty se přeci v různých locale zásadně liší!

To nechte na Latte. Nemusíte se starat o pořadí dne a měsíce nebo o to, jaké použít oddělovače. Latte to všechno vyřeší za vás a vypíše datum správně:

• V češtině: 6. srpna 2024
• V angličtině: August 6, 2024
• V němčině: 6. August 2024

Jak vidíte, formát je zcela nezávislý na lokálním nastavení. Vlastně by jej bylo možné zapsat třeba takto: yyyyMMMMd, na pořadí symbolů a mezer mezi nimi totiž nezáleží.

Pojďme se podívat na další příklady:

{* rok a měsíc *}
{$date|localDate: 'yyyyMMMM'}
{* ČJ: duben 2024, EN: April 2024 *}

{* krátký formát data *}
{$date|localDate: 'yMd'}
{* ČJ: 15. 4. 2024, EN: 4/15/2024 *}

{* základní formát času *}
{$time|localDate: 'jm'}
{* ČJ: 14:30, EN: 2:30 PM *}

{* krátký formát bez dopoledne/odpoledne *}
{$time|localDate: 'Hm'}
{* ČJ: 14:30, EN: 14:30 *}

Podobný popis najdete v dokumentaci filtru localDate.

Předpřipravené šablony s date a time

Druhý způsob využití filtru localDate nabízí předpřipravené šablony date a time. Ty fungují jako zkratky pro nejběžnější formáty dat a časů. K dispozici máte čtyři úrovně detailu: full, long, medium a short. Můžete je kombinovat nebo použít samostatně:

{* pouze datum *}
{$date|localDate: date: short}
{* ČJ: 15.04.2024, EN: 4/15/24 *}

{* pouze čas *}
{$date|localDate: time: medium}
{* ČJ: 14:30:45, EN: 2:30:45 PM *}

{* krátký formát data a času *}
{$date|localDate: date: short, time: short}
{* ČJ: 23.04.2024 14:30, EN: 4/23/24, 2:30 PM *}

Bonusem je možnost použít pro datumy prefix relative-, který relativně blízká data vypíše jako včera, dnes a zítra. V sobotu večer a v neděli ráno 🙂

{$yesterday|localDate: date: relative-short}
{* Výstup: včera *}

Pokud filtr zavoláte bez parametrů, vypíše se jako dlouhý formát data:

{$date|localDate}
{* ČJ: 23. dubna 2024, EN: April 23, 2024 *}

Použití filtru localDate pro formátování času vám umožní vytvářet mezinárodní aplikace s minimálním úsilím. Ale je skvělý i v případě, že tvoříte aplikaci jen v jednom jazyce.

• Automatická adaptace: Jeden formát se automaticky přizpůsobí lokálním zvyklostem. Nemusíte psát podmínky pro různé jazyky.
• Čitelnost kódu: Váš kód zůstává čistý a srozumitelný, bez ohledu na to, kolik různých locale podporujete.
• Konzistence: Zajistíte, že časy budou vždy zobrazeny správně podle očekávání uživatelů v dané zemi.

Filtr |number: Známá tvář s novými triky

Filtr number existuje v Latte již od prapočátku. Jeho standardní chování se novou verzí nemění a zůstává zcela zpětně kompatibilní. Teprve ve chvíli, kdy nastavíte locale, začne automaticky používat národní oddělovače pro desetinné čárky a tisíce:

{* S nastaveným českým locale *}
{1234.56|number}  {* Výstup: 1 234,56 *}

{* S nastaveným anglickým (US) locale *}
{1234.56|number}  {* Výstup: 1,234.56 *}

A teď přichází ta nejlepší část – můžete si s čísly vyhrát jako nikdy předtím. S novým parametrem pro formátování čísel si můžete jejich podobu ušít přesně na míru. Získáváte nebývalou kontrolu nad tím, jak se budou vypisovat. Několik příkladů:

{1234.5|number: '#,##0.00'}     {* 1,234.50 *}
{1234.5|number: '#,##0.##'}     {* 1,234.5 *}
{1234.5|number: '@@'}           {* 1200 *}
{1234.5|number: '@@@'}          {* 1230 *}
{1234.56|number: '#,##0.00 ¤'}  {* 1 234,56 Kč *}

Podobný popis formátu najdete v dokumentaci filtru number.

S filtrem number získáváte to nejlepší z obou světů – jednoduchost použití a zároveň možnost detailní kontroly nad formátováním čísel. Ať už vytváříte e-shop, finanční aplikaci nebo cokoli jiného, kde jsou čísla důležitá, tento filtr vám usnadní práci a zajistí, že vaše data budou vždy vypadat profesionálně a budou srozumitelná pro uživatele po celém světě.

Vylepšení filtrů |sort a |bytes

Tyto filtry dostaly v nové verzi Latte upgrade a nyní plně respektují nastavené locale. Filtr sort nyní řadí podle místních pravidel, což je zvláště důležité pro jazyky s diakritikou nebo speciálními znaky:

{['Železo', 'Jablko', 'Čaj']|sort}
{* Výstup v ČR: ['Čaj', 'Jablko', 'Železo'] *}

Díky tomu všechna data v šablonách, která nepocházejí z databáze, budou vždy správně seřazeny podle očekávání uživatelů v dané zemi. Kdyby to ale nebylo žádoucí, můžete předat filtru jinou porovnávací funkci.

Filtr bytes nyní automaticky používá správný oddělovač desetinných míst podle nastaveného locale:

{120000|bytes}
{* ČJ: 117,19 KB, EN: 117.19 KB *}

Jak začít s novými funkcemi v presenterech

Implementace do vašich projektů je jednoduchá a přímočará. Základem je nastavení správného locale pomocí funkce setLocale(). V presenterech jej můžete nastavit takto:

$this->template->getLatte()->setLocale($locale);

Pro projekty, které běží pouze v jednom jazyce, je efektivnější nastavit locale globálně v konfiguraci:

latte:
	locale: cs

Toto nastavení zajistí, že všechny instance Latte používané presentery a komponentami v celé aplikaci budou automaticky používat české locale.

Poznámka: Pro využití těchto nových lokalizačních funkcí je nezbytné mít nainstalované PHP rozšíření intl. A použití formátu ve filtru localDate vyžaduje PHP 8.1.