ages/grid

Reusable Nette UI Grid component with Nextras ORM

Maintainers

Package info

github.com/A-g-e-s/ages-grid

pkg:composer/ages/grid

Statistics

Installs: 64

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

Security

Advisories: 0

Aikido package health analysis

v1.0.1 2025-08-17 14:06 UTC

Requires

MIT 56d6e2e3bafb34719d795b150519097b335140e5

This package is auto-updated.

Last update: 2026-04-28 21:21:20 UTC

README

Znovupoužitelná tabulková komponenta pro Nette s Nextras ORM. Podporuje řazení, filtrování, stránkování, akce na řádcích a export do Excelu.

Požadavky: PHP 8.4, Nette Application 3.1+, Nextras ORM 5.0+

Instalace

composer require ages/grid

Základní použití

Komponentu registrujte v Presenteru nebo Facade přes factory metodu:

use Ages\Grid\Grid;
use Nextras\Orm\Collection\ICollection;

protected function createComponentGrid(): Grid
{
    $grid = new Grid($this->repository->findAll());

    $grid->addColumnString('name', 'Jméno')->sortAndFilter();
    $grid->addColumnDate('createdAt', 'Vytvořeno');
    $grid->addColumnNumber('price', 'Cena', unit: 'Kč');

    $grid->addAction(ActionType::Edit, 'edit', 'Upravit');
    $grid->addAction(ActionType::Delete, 'delete!', 'Smazat');

    return $grid;
}

V šabloně:

{control grid}

Konstruktor

new Grid(
    ICollection|OneHasMany $rawData,
    ?GridStyleInterface    $gridStyle = null
)
Parametr Popis
$rawData Kolekce Nextras ORM nebo relace OneHasMany
$gridStyle Vlastní styly (viz Stylování), výchozí je GridStyle

Sloupce

Každý addColumn*() vrací instanci sloupce, na níž lze řetězit fluent metody.

Společné metody všech sloupců

->sortAndFilter()          // zapne řazení i filtrování najednou
->setSortable()            // zapne řazení
->setFilterable()          // zapne filtrování
->setWidth(WidthClasses)   // šířka buňky (Default | Fit | Boolean)
->addClass(string|array)   // přidá CSS třídu buňce
->setLink(string $link, bool $ajax, bool $history, bool $checkEmpty)
                           // hodnota v buňce bude odkaz
->addLinkParam(string $key, string $value, bool $data)
                           // parametr odkazu (data=true → z entity)
->setManyToMany(key, value, name)  // navigace přes ManyHasMany relaci
->setPrefix(string)        // prefix před hodnotou (např. '#')

addColumnString

$grid->addColumnString(
    string    $name,                    // název property entity (lze vnořit přes '->': 'author->name')
    ?string   $label = null,           // popis sloupce, výchozí = $name
    TextAlign $align = TextAlign::Left,
    ?string   $unit  = null,           // statická jednotka za hodnotou
    bool      $unitFromData = false    // jednotka z jiné property (pak $unit = název property)
): ColumnString

addColumnNumber

$grid->addColumnNumber(
    string    $name,
    ?string   $label = null,
    TextAlign $align = TextAlign::Right,
    ?string   $unit  = null,
    bool      $unitFromData = false
): ColumnNumber

Navíc:

->setFormat(int $decimal, string $decimalSep, string $thousandsSep)
->addSummary(SummaryType $type)   // souhrnný řádek: Sum | Avg | Min | Max

addColumnDate

$grid->addColumnDate(
    string    $name,
    ?string   $label    = null,
    DateType  $dateType = DateType::Date,
    TextAlign $align    = TextAlign::Left,
): ColumnDate

DateType hodnoty:

Hodnota Formát
Date d. m. y
DateTime d. m. y H:i
DateShort d.m
DateTimeShort d.m. H:i
Time H:i
YearMonth Y-m

Filtr datumového sloupce automaticky zobrazí rozsah Od–Do. Lze také aktivovat bez filtrování:

->setDateRangeFilter()

addColumnBoolean

$grid->addColumnBoolean(
    string      $name,
    ?string     $label = null,
    BooleanType $type  = BooleanType::Default,
    TextAlign   $align = TextAlign::Left,
): ColumnBoolean

BooleanType hodnoty: Default · Visibility · Trash · Error

addColumnEnum

$grid->addColumnEnum(
    string    $name,
    string    $label,
    string    $enumClass,    // FQCN BackedEnum
    TextAlign $align = TextAlign::Left,
): ColumnEnum

Filtr zobrazí select s hodnotami enumu.

addColumnFunction

Volá metodu repozitáře místo přímé property entity.

$col = $grid->addColumnFunction('getTotalPrice', 'Celkem');
$col->addFunctionParam('id', fromData: true);   // předá entity->id jako argument
$col->addFunctionParam(0);                       // předá konstantu 0

Metoda repozitáře musí mít odpovídající signaturu.

addColumnImage

$grid->addColumnImage(
    string    $name,
    ?string   $label      = null,
    ImageType $type       = ImageType::Small,  // Small | Medium | Large
    bool      $isRelative = true,              // cesta relativní k www/
): ColumnImage

addColumnFile

$grid->addColumnFile(
    string  $name,
    ?string $label          = null,
): ColumnFile

addColumnCheckEmpty

Zobrazí ikonu přítomnosti/nepřítomnosti hodnoty místo samotné hodnoty.

$grid->addColumnCheckEmpty(string $name, ?string $label, TextAlign $align): ColumnCheckEmpty

Akce na řádcích

Odkaz (addAction)

$grid->addAction(
    ActionType $type,
    string     $link,           // Nette link, např. 'edit' nebo 'delete!'
    ?string    $title  = null,
    bool       $history = false,
    bool       $ajax    = true,
): Action
$action->addLinkParam('id', 'id', data: true);  // přidá parametr z entity

Callback (addActionCallback)

Akce zavolá PHP callback místo přesměrování.

$action = $grid->addActionCallback(ActionType::Delete, primaryKey: 'id');
$action->onCall[] = function (int $id): void {
    $this->repository->delete($id);
};

Záhlaví (addHeaderAction)

$grid->addHeaderAction(
    ActionType $type,
    string     $link,
    ?string    $title   = null,
    bool       $ajax    = true,
    bool       $history = true,
): HeaderAction

ActionType hodnoty

Edit · Delete · Show · New · Duplicate · Archive · Cancel · Complete · Link · Export · Money · Graph · Print · Info · Update · Email · Close · Cart · Bulb · Copy · Truck

Filtrování

Filtr se aktivuje na konkrétním sloupci:

$grid->addColumnString('name')->setFilterable();
// nebo zároveň řazení:
$grid->addColumnString('name')->sortAndFilter();

Řádek filtru se zobrazí automaticky, pokud je alespoň jeden sloupec filtrovatelný.

Operátory ve filtru (textová pole)

Prefix Operátor
bez prefixu LIKE contains
> větší než
< menší než
= přesná shoda
! není rovno
null (přesně) IS NULL

Řazení

Výchozí řazení se nastaví automaticky na první přidaný sloupec. Lze přepsat:

$grid->setSortColumn('createdAt');
$grid->reverseSort();   // výchozí směr DESC NULLS FIRST

Kliknutím na záhlaví sloupce uživatel přepíná ASC/DESC.

Stránkování

// Zapnutí s výchozími možnostmi (80, 160, 240) a výchozím offsetem #1
$grid->setPagination();

// Vlastní možnosti
$grid->setItemsPerPageOptions([25, 50, 100], itemsPerPageOffset: 1);

Export do Excelu

$grid->addExport();                      // tlačítko s výchozím názvem 'Export'
$grid->addExport('Přehled zakázek');     // vlastní název souboru

// Vlastní výstupní adresář (volitelné, výchozí: www/export/)
$grid->setExportPaths(
    basePath:   '/var/www/app/',
    exportPath: '/var/www/app/www/export/'
);

// Callback po exportu (dostane název souboru)
$grid->onExport[] = function (string $filename): void {
    // logování, notifikace…
};

Export vždy zahrnuje aktuálně filtrovaná a seřazená data (bez stránkování).

Popis / caption

$grid->setCaption('Seznam zákazníků');

Hover efekt řádků

$grid->hoverable = true;

Stylování

Všechny CSS třídy jsou odděleny do GridStyleInterface. Výchozí implementace GridStyle používá Tailwind CSS.

Pro vlastní styly implementujte rozhraní a předejte instanci do konstruktoru:

class MyGridStyle implements GridStyleInterface
{
    public function mainContainer(): string { return 'my-grid-wrapper'; }
    // … ostatní metody
}

$grid = new Grid($data, new MyGridStyle());

Vnořené property a relace

Sloupce podporují tečkovou notaci (oddělovač ->) pro přístup k vnořeným entitám:

$grid->addColumnString('customer->company->name', 'Firma');

Pro ManyHasMany relace:

$grid->addColumnString('tags->name')
     ->setManyToMany(key: 'type', value: 'primary', name: 'label');