Columns

Columns neboli sloupce jsou jednoduché PHP třídy, které ovlivňují to, v jakém formátu vám budou navrácena data z API a také, jak budou renderovány v datagridu.

Příklad použítí sloupců

Přidání sloupce EmailColumn vám umožní pracovat s propety email skrze API endpoint a zároveň vám umožní rendering tohoto sloupce v tabulce datagridu. Tento sloupec má (by default) přiřazen EmailColumnRenderer.vue, jenž zajištuje, že hodnota bude v tabulce vykreslena jako hypertextový odkaz. K dispozici je celá řada sloupců a column rendererů.

public function read(ReadBuilder $builder, CollectionRequest $request): ReadBuilder
{
    return $builder
        ->add(new EmailColumn(
            key: 'email', 
            name: 'E-mail', 
            formatters: [
                // Demonstrace formáteru - vysvětleno v následujícím odstavci
                //new CallableFormatter(fn($value) => "mailto:{$value}"),
            ]
        ))
        //->add(...)
        //->add(...)
    ;
}

Formátery

Při čtení dat ze sloupce se hodnota vždy zformátuje pomocí tzv. formáterů. V příkladu je demonstrativně zakomentován CallableFormatter, který lze použít pro rychlou transformaci dat. K dispozici je ale celá řada formatters.

Přehled sloupců

	Column (název třídy)	Formatters	Renderers	Renderer output	Fallback na String
1	ArrayColumn		Array	<v-chip-group>	ne
2	BlobColumn		String	string	ano
3	BooleanColumn		Boolean	<v-icon>	ne
4	DateColumn	Date	String	Formát Y-m-d	ano
5	DateCzColumn	DateCz	String	Formát j.n.Y	ano
6	DateTimeColumn	DateTime	String	Formát Y-m-d H:i:s	ano
7	DateTimeCzColumn	DateTimeCz	String	Formát j.n.Y H:i:s	ano
8	DateTimeIntervalColumn	DateTimeInterval	DateTimeInterval	Formát %y %m %d %h %m %s	ne
9	DateTimeZoneColumn	DateTimeZone	DateTimeZone	Formát ISO 8601	ne
10	DateTimeZoneCzColumn	DateTimeZoneCz	DateTimeZone	Formát ISO 8601	ne
11	EmailColumn	Email	Email	<a href="mailto:...">	ne
12	HourMinuteColumn	HourMinute	String	Formát H:i	ano
13	HourMinuteCzColumn	HourMinuteCz	String	Formát G:i	ano
14	JsonColumn		Json	JSON string	ne
15	NumericColumn		String	string	ano
16	PhoneColumn	Phone	Phone	<a href="tel:...">	ne
17	RichTextColumn	RichText	String	string	ano
18	StringColumn		String	string	ano
19	TimeColumn	Time	String	Formát H:i:s	ano
20	TimeCzColumn	TimeCz	String	Formát G:i:s	ano
21	ToManyColumn	ToMany	JoinMany	<v-chip-group>	ne
22	ToOneColumn	ToOne	JoinOne	<v-chip>	ne
23	UrlColumn		Url	<a href="...">	ne
24	VideoLinkColumn	VideoLink	Url	<a href="...">	ne

Společné parametry sloupců

U všech sloupců lze nastavit tyto společné parametry:

Parametr	Typ	Výchozí hodnota	Popis
key	string		Klíč sloupce v API a ve formuláři.
name	string		Název sloupce v záhlaví datagridu.
sortable	bool	false	Určuje, zda je sloupec řaditelný v datagridu.
visible	bool	true	Určuje, zda je sloupec vizuálně skrytý v datagridu.
formatters	IFormatters[]	dle sloupce	Pole formatterů, které se použijí pro formátování dat.

Přehled column rendererů

	Vue column renderer	Soubor	Vue renderuje	Poznámka
1	Array	ArrayColumnRenderer.vue	Pole jako <chip-group>
2	Boolean	BooleanColumnRenderer.vue	Boolean jako <v-icon>
3	DateTimeInterval	DateTimeIntervalColumnRenderer.vue	Interval jako %y %m %d %h %m %s	+tooltip
4	DateTimeZone	DateTimeZoneColumnRenderer.vue	Datum a čas s timezone jako ISO 8601	+tooltip
5	Email	EmailColumnRenderer.vue	E-mail jako <a href="mailto:...">	_blank
6	JoinMany	JoinManyColumnRenderer.vue	Položky jako <chip-group>
7	JoinOne	JoinOneColumnRenderer.vue	Položku jako <v-chip>
8	Json	JsonColumnRenderer.vue	JSON jako JSON string
8	Phone	PhoneColumnRenderer.vue	Telefon jako <a href="tel:...">	_blank
9	String	StringColumnRenderer.vue	string
10	Url	UrlColumnRenderer.vue	URL jako <a href="...">	_blank

Vlastní sloupec

Pokud potřebujete ovlivnit vykreslení dat konkrétního sloupce v datagridu či konkrétní property v API jiným způsobem, než umožňují dostupné columns (či jejich formátery a renderery), můžete si vytvořit vlastní sloupec.

Vytvoření sloupce

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

app/Collection/Column/MyCustomColumn.php

class MyCustomColumn extends BaseColumn
{
    /** 
     * Definuje název Vue column-rendereru.     
     * Pokud Vue komponenta není zaregistrována, 
     * provede se fallback na StringColumnRenderer.vue.      
     */
    public function renderer(): string
    {
        return 'my-custom-column-renderer';
    }
    
    /**
     * Pomocí konstruktoru lze přidat jakékoli vlastní parametry.
     *
     * @param IFormatter[] $formatters
     */
    public function __construct(
        protected string $key,
        protected string $name,
        protected string $myParam
        protected bool   $sortable = false,
        protected bool   $visible = true,
        protected array  $formatters = [],
    )
    {
        // Ukázka přidání vlastního formatteru.
        $formatters[] = new MyCustomFormatter();
        parent::__construct(
            key: $key,
            name: $name,
            sortable: $sortable,
            visible: $visible,
            formatters: $formatters
        );
    }
    
    /**
     * Také je možné přidat metodu toArray(), díky které 
     * můžete ovlivnit výsledné schéma pro datagrid.
     *
     * @return array{
     *     renderer: string,
     *     key: string,
     *     name: string,
     *     sortable: bool,
     *     visible: bool,
     *     formatters: class-string[],
     *     params: array{myParam: string}     
     * }
     */
    public function toArray(): array
    {
        $schema = parent::toArray();
        $schema['params']['myParam'] = $this->myParam;
        return $schema;
    }
}

Povinné parametry konstruktoru

Konstruktor musí obsahovat veškeré parametry, které obsahuje i konstruktor rodičovské třídy BaseColumn.

public function __construct(
    
    // Klíč sloupce v API
    protected string $key,
    
    // Název sloupce v záhlaví datagridu
    protected string $name,
    
    // Navíc - Váš rozšiřující parametr
    protected string $myParam,
    
    // Navíc - Další rozšiřující parametr
    protected string $myParamX,
    
    // Určuje, zda je sloupec řaditelný v datagridu
    protected bool   $sortable = false,
    
    // Určuje, zda je sloupec vizuálně skrytý v datagridu
    protected bool   $visible = true,
    
    // Pole formatterů, které se použijí pro formátování dat
    protected array  $formatters = [],
)
{
    // ...
}

Vlastní column renderer

Pokud potřebujete vytvořit vlastní Vue komponentu pro vykreslení sloupce v datagridu, lze to provést ideálně ve složce assets/datagrid/columns. Vytvoříme zde tedy nový soubor MyCustomColumnRenderer.vue a dále budeme postupovat podle následující kapitoly: megio panel - column