Přeskočit na hlavní obsah

Formatters

Formátery slouží k formátování dat před jejich vykreslením v API, datagridu a ve formulářích.

Příklad využití formáterů​

Předpokládejme, že chceme vypsat datagrid se třemi sloupci: date, paragraph a nickname. Sloupec date obsahuje datum, které chceme zobrazit ve formátu j.n.Y. Sloupec paragraph obsahuje text, který chceme zobrazit maximálně na 100 znaků a se třemi tečkami na konci. Sloupec nickname obsahuje přezdívku, kterou chceme zobrazit velkými písmeny. Navíc chceme, aby se sloupec paragraph formátoval pouze v datagirdu (AdminPanelu).

public function readAll(ReadBuilder $builder, CollectionRequest $request): ReadBuilder
{
    return $builder
        ->add(new TextColumn(
            key: 'date', 
            name: 'Datum', 
            formatters: [
                // Převede \Datetime na string ve formátu: j.n.Y
                new DateCzFormatter()
            ]
        ))
        ->add(new TextColumn(
            key: 'paragraph', 
            name: 'Odstavec', 
            formatters: [
                // Odstraní HTML tagy, zkrátí text na 100 znaků a přidá tři tečky na konec
                new RichTextFormatter(
                    max: 100, 
                    truncate: false, 
                    suffix: '...', 
                    stripTags: true,
                    showOnlyOn: ShowOnlyOn::ADMIN_PANEL
                )
            ]
        ))
        ->add(new TextColumn(
            key: 'nickname', 
            name: 'Přezdívka', 
            formatters: [
                // Převede na velká písmena
                new CallableFormatter(fn($value) => mb_strtoupper($value))
            ]
        ))
    ;
}

Přehled formáterů​

Formatter (název třídy)PopisParametry
1CallableFormatterUmožňuje definovat vlastní callback funkci pro formátování hodnoty.callable $callback
?ShowOnlyOn $showOnlyOn
2DateCzFormatterPřevede \Datetime či \DateTimeImmutable na string ve formátu: j.n.Y.?ShowOnlyOn $showOnlyOn
3DateFormatterPřevede \Datetime či \DateTimeImmutable na string ve formátu: Y-m-d.?ShowOnlyOn $showOnlyOn
4DateTimeCzFormatterPřevede \Datetime či \DateTimeImmutable na string ve formátu: j.n.Y H:i:s.?ShowOnlyOn $showOnlyOn
5DateTimeFormatterPřevede \Datetime či \DateTimeImmutable na string ve formátu: Y-m-d H:i:s.?ShowOnlyOn $showOnlyOn
6DateTimeIntervalFormatterPřevede \DateInterval na array v tomto formátu.?ShowOnlyOn $showOnlyOn
7DateTimeZoneCzFormatterPřevede \DateTime či \DateTimeImmutable na array v tomto formátu.?ShowOnlyOn $showOnlyOn
8DateTimeZoneFormatterPřevede \DateTimeZone či \DateTimeImmutable na array v tomto formátu.?ShowOnlyOn $showOnlyOn
9HourMinuteCzFormatterPřevede \DateTime či \DateTimeImmutable na string ve formátu: G:i.?ShowOnlyOn $showOnlyOn
10HourMinuteFormatterPřevede \DateTime či \DateTimeImmutable na string ve formátu: H:i.?ShowOnlyOn $showOnlyOn
11MaxFormatterV případě array vrátí maximální počet položek. V případě stringu vrátí oříznutý text.int $max
?ShowOnlyOn $showOnlyOn
12RichTextFormatterOdstraní HTML tagy, zkrátí text na zadaný počet znaků a přidá suffix.int $max
bool $truncate
string $suffix
bool $stripTags
?ShowOnlyOn $showOnlyOn
13TimeCzFormatterPřevede \DateTime či \DateTimeImmutable na string ve formátu: G:i:s.?ShowOnlyOn $showOnlyOn
14TimeFormatterPřevede \DateTime či \DateTimeImmutable na string ve formátu: H:i:s.?ShowOnlyOn $showOnlyOn
15ToManyFormatterPřevede na array{label: string, value: string}[] či null. Více zde.?ShowOnlyOn $showOnlyOn
16ToOneFormatterPřevede na array{label: string, value: string} či null. Více zde.?ShowOnlyOn $showOnlyOn

Jak funguje ToManyFormatter​

Tento formáter dokáže rozpoznat cílovou (relační) entitu a pokud tato cílová entita implementuje rozhraní IJoinable a tedy i metodu getJonableLabel(), tak transformuje celou ArrayCollection na array-list, kde každý prvek obsahuje property label a value. Property value je vždy id cílové entity a label je sestaven podle předpisu v metodě getJonableLabel().

Jak funguje ToOneFormatter​

Stejně jako ToManyFormatter, tak i tento formáter dokáže rozpoznat cílovou (relační) entitu a pokud tato cílová entita implementuje rozhraní IJoinable a tedy i metodu getJonableLabel(), tak transformuje celou entitu na pole - ovšem ale pouze na klasické pole viz array{label: string, value: string}.

Návratová hodnota DateTimeIntervalFormatter​

array {
    is_positive: bool,
    all_days: int,
        each: {
        years: int,
        months: int,
        days: int,
        hours: int,
        minutes: int,
        seconds: int
    }
}

Návratová hodnota DateTimeZoneCzFormatter​


array {
    value: string,      // j.n.Y H:i:s
    iso_8601: string,   // 2021-08-26T14:00:00+02:00
    zone_id: string,    // Europe/Prague
    utc_offset: string  // +02:00
}

Návratová hodnota DateTimeZoneFormatter​

array {
    value: string,      // Y-m-d H:i:s
    iso_8601: string,   // 2021-08-26T14:00:00+02:00
    zone_id: string,    // Europe/Prague
    utc_offset: string  // +02:00
}

Vlastní formáter​

Pokud potřebujete ovlivnit formátování nějakých hodnot jiným způsobem než nabízí výše uvedené formátery, můžete si vytvořit vlastní formáter.

Vytvoření formáteru​

Stačí přidat novou třídu, která podědí BaseFormatter a implementuje metodu format().

app/Collection/Formatter/MyCustomFormatter.php
class MyCustomFormatter extends BaseFormatter
{
    public function __construct(
        protected int         $max = 100,
        protected bool        $truncate = false,
        protected string      $suffix = '...',
        protected bool        $stripTags = true,
        protected ?ShowOnlyOn $showOnlyOn = null
    )
    {
        parent::__construct($showOnlyOn);
    }
    
    public function format(mixed $value, string $key): mixed
    {
        if (!is_string($value)) {
            return $value;
        }
        
        $value = strip_tags($value);
        
        if (Strings::length($value) > $this->max) {
            if ($this->truncate) {
                $value = Strings::truncate($value, $this->max, $this->suffix);
            } else {
                $value = Strings::substring($value, 0, $this->max) . $this->suffix;
            }
        }
        
        return $value;
    }
}

Povinné parametry konstruktoru​

Jediným povinným parametrem je showOnlyOn, který určuje, kde se má formáter použít - zda jen v API nebo v AdminPanelu a nebo v obou případech - což je výchozí nastavení.