Část III · Sloupce

11. Systémový sloupec

addSystem($alias, $title) – sloupec, o kterém datový zdroj neví. Hodnota se doplní až v rows(), takže se do něj vejde cokoli, co jde spočítat v PHP.

Ukázka

Podíl poplatků se počítá z ostatních tří sloupců. V dotazu takový sloupec není – zkuste podle něj filtrovat nebo řadit a hlavička ani filtrovací řádek nic nenabídnou.

Zdrojový kód

php app/Modules/AdminModule/Components/Docs/Columns/ColumnSystemGridControl/ColumnSystemGridControl.php

<?php

declare(strict_types=1);

namespace App\Components\Docs\Columns\ColumnSystemGridControl;

use Xart\Grid\Button\ButtonManager;
use Xart\Grid\Column\ColumnManager;
use Xart\Grid\Control\GridControl;
use Xart\Grid\DataOutput\Row;
use Xart\Grid\DataSource\DataSource;
use Xart\Grid\DataSource\SQL\SQLDataSource;

/**
 * Dokumentace, kapitola 11 – Systémový sloupec.
 *
 * Podíl dopravy a platby na ceně objednávky. V datech takový sloupec není a dopočítat ho v SQL by
 * šlo taky – schválně se počítá až v rows(), aby bylo vidět, co addSystem() umí a co ne.
 */
class ColumnSystemGridControl extends GridControl
{
    public function createDataSource(): DataSource
    {
        return new SQLDataSource(__DIR__ . '/ColumnSystemGridControl.sql');
    }


    public function columns(ColumnManager $cm): void
    {
        $cm->add('number', 'Číslo');
        $cm->addNumber('total_price', 'Celkem', 2, 'Kč');
        $cm->addNumber('shipping_price', 'Doprava', 2, 'Kč');
        $cm->addNumber('payment_price', 'Platba', 2, 'Kč');

        // Systémový sloupec – datový zdroj o něm nic neví, hodnota se plní v rows().
        $cm->addSystem('fees_share', 'Podíl poplatků');
    }


    public function buttons(ButtonManager $bm): void
    {
    }


    public function rows(Row $row): void
    {
        // Formattery presetů už buňky přepsaly, původní číslo drží defaultValue.
        $total = (float) $row['total_price']->defaultValue;
        $fees = (float) $row['shipping_price']->defaultValue + (float) $row['payment_price']->defaultValue;

        $row['fees_share'] = $total > 0
            ? number_format($fees / $total * 100, 1, ',', ' ') . ' %'
            : '–';

        $row['fees_share']->addClass('text-end');
    }


    public function render(): void
    {
        $this->template->render(__DIR__ . '/ColumnSystemGridControl.latte');
    }
}

sql app/Modules/AdminModule/Components/Docs/Columns/ColumnSystemGridControl/ColumnSystemGridControl.sql

SELECT
    o.id,
    o.number,
    o.total_price / 100 AS total_price,
    o.shipping_price / 100 AS shipping_price,
    o.payment_price / 100 AS payment_price
FROM `order` o

Jak se plní

public function columns(ColumnManager $cm): void
{
	$cm->addSystem('fees_share', 'Podíl poplatků');
}

public function rows(Row $row): void
{
	$row['fees_share'] = '12,5 %';
}

rows() se volá pro každý načtený řádek. Ostatní buňky už v tu chvíli prošly formattery presetů, takže $row['total_price']->value je naformátovaný text – původní číslo drží defaultValue. Podrobněji v kapitole 13.

Co systémový sloupec neumí

Filtrovat. Podmínka by musela do WHERE, jenže databáze o sloupci neví. Frontend ho proto vynechá i z globálního hledání.
Řadit. Řadí se v databázi, a to nad stránkou dat, kterou teprve dostane rows() – seřadit šla by leda právě zobrazená stránka, což je horší než neřadit vůbec. Hlavička proto přepínač řazení nenabídne.

Když má být hodnota filtrovatelná a řaditelná, spočítejte ji v SQL – skalárním poddotazem nebo výrazem (kapitola 3.3). Systémový sloupec je pro to, co v databázi spočítat nejde: údaj z jiné služby, hodnota složená z několika sloupců podle práv uživatele, HTML poskládané v PHP.

V exportu

Systémový sloupec se exportuje jako každý jiný – rows() běží i pro řádky, které jdou do sešitu. Výchozím typem je text; číslo, datum nebo procento nastavíte přes setExportType() (kapitola 40).