PodporaZnalostní báze

Použití funkcí data a času

Jednou z nejčastějších potřeb v šablonách je manipulace s datem a časem. I když si můžete myslet, že vše, co potřebujete, je přidat a odečíst data, existuje mnoho dalších scénářů, které dávají smysl a mohou využít výpočty data a času.

Stejně jako mnoho dalších pokročilých funkcí jsou funkce pro práci s datem a časem poskytovány prostřednictvím pluginu, který je třeba nejprve načíst:

[% USE date -%]

Plugin poskytuje metodu format(), která přijímá časovou hodnotu, formátovací řetězec a název národního prostředí. Všechny tyto parametry jsou volitelné. Pokud není určeno tak výchozími hodnotami jsou aktuální systémový čas, výchozím formátem je ('% H:% M:% S% d-% b-% Y') a aktuálním místním nastavením je “en_US”. Výchozí hodnoty pro čas, formát a / nebo národní prostředí mohou být zadány jako pojmenované parametry direktivy USE.

[% USE date(format='%-d.%-m.%Y') %]

Tímto dojde k nastavení výchozího formátování na evropský standardní formát d.m.r bez úvodních nul, např. 1.2.2020. Níže naleznete standardní zástupné symboly.

Nyní, když jsme nahráli plugin pro datum a čas, můžeme začít pracovat s hodnotami data a času. Základním krokem je vložení aktuálního data a času podle výchozího formátování:

[% date.format -%]

Nezapomeňte však, že se jedná o aktuální datum a čas zpracování šablony. Znamená to tedy, že datum a čas v těle zprávy bude odpovídat okamžiku vygenerování zprávy. Pokud vaše zpráva bude obsahovat odkaz na zobrazení v prohlížeči, tento náhled pak zobrazí aktuální datum a čas, nikoliv čas kdy byla zpráva odeslána

Můžete také použít funkci pro formátování jakékoli hodnoty data a času do formátu předáním určitého data v parametru date.format(datumová_hodnota). Lze tedy funkci využít k formátování data a času odeslání zprávy (viz. proměnné obsahu):

[% senddate = '' _ email.YEAR _ '-' _ email.MONTH _ '-' _ email.DAY _ ' ' _ '00:00:00' -%]
[% date.format(senddate) -%]

Dalším jednoduchým příkladem je získávání data poslední objednávky uložené v poli CUSTOM1 příjemce a manipulace s tímto datem (s uloženým přesným časem):

[% date.format (recipient.CUSTOM1) -%]

V případě, že pole obsahuje pouze datum bez času, jednoduše přidáme do hodnoty libovolný čas připojením _ ' 00:00:00' k hodnotě.

Datový plugin má také některé další vylepšené funkce, které umožňují manipulaci a výpočty data a času a ty mohou být předány jako hodnoty pro formátování. Výstup z komplexnějšího výpočtu, například formátovaná hodnota nadcházejícího dne za 7 dní od dnešního dne, bude následující:

[% date.format(date.manip.UnixDate("7 days later","%s")) %]

Nebo můžete také přepsat výchozí formátování a vrátit datum ve formátu, který si vyberete pro tento konkrétní výstup. V tomto případě chceme vrátit datum dne 60 dní před dnešním dnem ve formátu USA, zatímco výchozí formát je nastaven na evropský:

[% date.format(date.manip.UnixDate("60 days earlier","%s"), '%d.%-m.%Y %-I:%M %p') %]

Jak jste si možná všimli, ve výše uvedených voláních je nová funkce nazvaná manipulace týkající se pluginu nazvaného Date::Manip. Poskytuje širokou škálu funkcí manipulace s datem a časem, které mohou dále rozšiřovat úroveň automatizace v šablonách. Jako by to nestačilo, je k dispozici další plugin nazvaný Date::Calc, který poskytuje dodatečné výpočty gregoriánského kalendáře. 

[% date.format(date.calc.Easter_Sunday(year).join('/') _ ' 00:00:00') %]

Chtěli jste někdy zahrnout do šablon datum velikonoční neděle, aniž byste museli aktualizovat každý rok? Tento řádek se postará o tento trik a v kombinaci s dalšími možnostmi manipulace data a času, můžete snadno přidat do šablony velikonoční blok, který se začne zobrazovat 2 týdny před Velikonoční nedělí. K tomu je potřeba udělat 2 různé výpočty - jeden pro datum velikonoční:

[% easter = date.format(date.calc.Easter_Sunday(year).join('/') _ ' 00:00:00','%s') %]

A datum 20 dnů před Velikonocemi:

[% pre_easter = date.manip.UnixDate(date.manip.DateCalc("20 days earlier", date.calc.Easter_Sunday(year).join('/')),'%s') %]

Nyní, když máme tato dvě čísla jako hodnotu ve formátu UnixDate, což je čas v sekundách od počátku času, můžeme vytvořit jednoduchou podmínku pro zobrazení obsahu:

[% IF date.now > pre_easter && date.now < easter -%]
   <h1>Easter is coming!</h1>
[% END -%]

Pokud bychom chtěli naši kampaň posunout ještě o kousek dále, můžeme také spočítat počet dnů, které zbývají do Velikonoc, a mít ještě zajímavější obsah. Pro výpočet zbývajících dnů použijeme funkci delta k zobrazení rozdílu mezi aktuálním datem a vypočítaným datem velikonoc:

[% daystogo =  date.calc.Delta_Days(date.format(date.now,'%Y'),date.format(date.now,'%m'),date.format(date.now,'%d'),date.format(easter,'%Y'),date.format(easter,'%m'),date.format(easter,'%d')) -%]

A tuto hodnotu použijeme v našem výsledném bloku:

[% easter = date.format(date.calc.Easter_Sunday(year).join('/') _ ' 00:00:00','%s') %]
[% pre_easter = date.manip.UnixDate(date.manip.DateCalc("20 days earlier", date.calc.Easter_Sunday(year).join('/')),'%s') %]
[% daystogo =  date.calc.Delta_Days(date.format(date.now,'%Y'),date.format(date.now,'%m'),date.format(date.now,'%d'),date.format(easter,'%Y'),date.format(easter,'%m'),date.format(easter,'%d')) -%]
[% IF date.now > pre_easter && date.now < easter -%]
  <h1>Easter is coming in [% daystogo -%] days!</h1>
[% END -%]

Celé by to bylo samozřejmě mnohem snazší pro Vánoce, které mají každý rok stejné datum, ale třeba budete chtít upravit Obsah podle toho, na jaký den připadnou Vánoce. Stejná matematika by mohla být použita pro jakoukoliv jinou příležitost, např. Automatizovaný dárkový kupon k narozeninám, narozeninový dárek pro partnera, výročí svatby atd. Limity využití jsou skoro nekonečné.

Standardní zástupné znaky pro formátování data času:

%a Zkrácený název dne v týdnu podle národního prostředí en_US. (Vypočteno z tm_wday.)
%A Úplný název dne v týdnu podle národního prostředí en_US. (Vypočteno z tm_wday.)
%b Zkrácený název měsíce podle národního prostředí en_US. (Vypočteno z tm_mon.)
%B Úplný název měsíce podle národního prostředí en_US. (Vypočteno z tm_mon.)
%c Preferovaná reprezentace data a času aktuálního národního prostředí.
%C Číslo století (rok / 100) jako dvoumístné celé číslo. (Vypočteno z tm_year.)
%d Den v měsíci jako desetinné číslo (rozsah 01 až 31). Pro hodnotu bez úvodní nuly lze použít formátování %-d. (Vypočteno z tm_mday.)
%D Ekvivalent %m/%d/%y. Američané by si měli uvědomit, že v jiných zemích je %d/%m/%y poměrně běžné. To znamená, že v mezinárodním kontextu je tento formát nejednoznačný a neměl by být používán.)
%e Jako %d, den v měsíci jako desetinné číslo, ale počáteční nulu nahradí mezera. (Vypočteno z tm_mday.)
%F Ekvivalent %Y-%m-%d (formát data ISO 8601).
%G ISO 8601 týdenní rok se stoletím jako desetinné číslo. Čtyřmístný rok odpovídající číslu týdne ISO (viz %V). To má stejný formát a hodnotu jako %Y, kromě toho, že pokud číslo týdne ISO patří do předchozího nebo následujícího roku, použije se místo toho roku. (Vypočteno z tm_year, tm_yday a tm_wday.)
%g Stejně jako %G, ale bez století, to znamená s dvoumístným rokem (00–99). (Vypočteno z tm_year, tm_yday a tm_wday.)
%h Ekvivalent %b.
%H Hodina jako desetinné číslo pomocí 24hodinových hodin (rozsah 00 až 23). Pro hodnotu bez úvodní nuly lze použít formátování %-H. (Vypočteno z tm_hour.)
%I Hodina jako desetinné číslo pomocí 12hodinových hodin (rozsah 01 až 12). Pro hodnotu bez úvodní nuly lze použít formátování %-I. (Vypočteno z tm_hour.)
%j Den v roce jako desetinné číslo (rozsah 001 až 366). (Vypočteno z tm_yday.)
%k Hodina (24hodinové hodiny) jako desetinné číslo (rozsah 0 až 23); jednotlivým číslicím předchází prázdný znak. (Viz také %H.) (Vypočteno z tm_hour.)
%l Hodina (12hodinové hodiny) jako desetinné číslo (rozsah 1 až 12); jednotlivým číslicím předchází prázdný znak. (Viz také %I.) (Vypočteno z tm_hour.)
%m Měsíc jako celé číslo (rozsah 01 až 12). Pro hodnotu bez úvodní nuly lze použít formátování %-m. (Vypočteno z tm_mon.)
%M Minuta jako celé číslo (rozsah 00 až 59). Pro hodnotu bez úvodní nuly lze použít formátování %-M. (Vypočteno z tm_min.)
%n Znak nového řádku.
%p Buď "AM" nebo "PM" podle zadané hodnoty času, nebo odpovídající řetězce pro aktuální národní prostředí. Poledne je považováno za "PM" a půlnoci za "AM". (Vypočítáno z tm_hour.)
%P Stejně jako %p, ale malými písmeny: „am“ nebo „pm“ nebo odpovídající řetězec pro aktuální národní prostředí. (Vypočteno z tm_hour.)
%r Čas v zápisu am nebo pm. V národním prostředí POSIX to odpovídá %I:%M:%S%p.
%R Čas v 24hodinové notaci (%H:%M). Pro verzi obsahující sekundy viz %T níže.
%s Počet vteřin od počátku času, 1970-01-01 00:00:00 +0000 (UTC). (Vypočteno z mktime (tm).)
%S Vteřina jako číslo (rozsah 00 až 60). Pro hodnotu bez úvodní nuly lze použít formátování %-S. (Rozsah je do 60ti, aby se umožnily příležitostné přestupné vteřiny.) (Vypočteno z tm_sec.)
%t Znak tabulátoru.
%T Čas v 24hodinovém zápisu (%H:%M:%S).
%u Den v týdnu jako číslo, rozsah 1 až 7, pondělí je 1. Viz také %w. (Vypočteno z tm_wday.) (SU)
%U Číslo týdne aktuálního roku jako číslo, rozsah 00 až 53, počínaje první nedělí jako první den v týdnu 01. Pro hodnotu bez úvodní nuly lze použít formátování %-U. Viz také %V a %W. (Vypočteno z tm_yday a tm_wday.)
%V Číslo týdne aktuálního roku dle ISO 8601, rozsah 01 až 53, kde týden 1 je prvním týdnem, který má v novém roce alespoň 4 dny. Pro vrácení hodnoty bez úvodní nuly by mělo být použito formátování %-V. Viz také %U a %W. (Vypočteno z tm_year, tm_yday a tm_wday.)
%w Den v týdnu jako desetinné číslo, rozsah 0 až 6, neděle je 0. Viz také %u. (Vypočteno z tm_wday.)
%W Číslo týdne aktuálního roku jako číslo, rozsah 00 až 53, počínaje pondělím jako prvním dnem v týdnu 01. Pro hodnotu bez úvodní nuly lze použít formátování %-W. (Vypočteno z tm_yday a tm_wday.)
%x Preferované zobrazení data pro aktuální národní prostředí bez času.
%X Preferované zobrazení času pro aktuální národní prostředí bez data.
%y Rok jako číslo bez století (rozsah 00 až 99). (Vypočteno z tm_year)
%Y Rok jako číslo včetně století. (Vypočteno z tm_year)
%Z Název časového pásma nebo zkratka.