Page tree
Skip to end of metadata
Go to start of metadata

Obsah

 

Features

  • Zobrazení dat v tabulce
  • Řazení
  • Globální vyhledávání a filtrování dle jednotlivých sloupečků
  • Definice vlastností (řaditelnost, vyhledatelnost, viditelnost...) pro jednotlivé sloupečky
  • Zpracování dat na serveru
  • Podpora lazy loadingu dat a "nekonečného" scollování
  • Operace nad jednotlivými záznamy i nad množinami záznamů
  • Automatické generování základních formulářů (nový záznam, editace záznamu, smazání záznamů)
  • Jednoduché API

Definice sloupců

Základní

Jednoduchá tabulka vytvořená z array bez nutnosti specifikovat další vlastnosti. Sloupce se vytvoří podle prvního řádku dat a mají indexy 0 až count($array[0]). Funguje řazení, vyhledávání, stránkování.

Kód

$array = [
   ['a', 3, 'Bar'],
   ['b', 1, 'Baz'],
   ['c', 2, 'Foo']
];

$table->createFromArray($array);

Výsledek

 

S názvy sloupečků

Názvy sloupců stačí přidat jako druhý argument createFromArray, čímž jsou vytvořeny sloupce s výchozími vlastnostmi.

Kód

$array = [
   ['a', 3, 'Bar'],
   ['b', 1, 'Baz'],
   ['c', 2, 'Foo']
];

$table->createFromArray($array, ['First', 'Second', 'Third']);

Výsledek

S definicí sloupečků

Jako druhý argument createFromArray je možné předat pole instancí Vivo\UI\RichTable\Column, díky čemuž je možné sloupečkům rychle nadefinovat základní vlastnosti.

Kód

$array = [
   ['a', 3, 'Bar'],
   ['b', 1, 'Baz'],
   ['c', 2, 'Foo']
];

$columns = [
   new Column('First', 0),
   new Column('Second', 1),
   new Column('Third', 2),
];

$table->createFromArray($array, $columns);

Výsledek

Pole $columns může být též asociativní. V takovém případě se klíč použije jako název sloupce a pokud je sloupec definován jen titulkem i jako index zdroje dat pro daný sloupec.

Kód

$array = [
   ['first' => 'a', 'second' => 3, 'third' => 'Bar'],
   ['first' => 'b', 'second' => 1, 'third' => 'Baz'],
   ['first' => 'c', 'second' => 2, 'third' => 'Foo']
];

$columns = [
   'first' => 'First',
   'second' => new Column('Second', 'second'),
   'custom' => new Column('Custom', 'third')
];

$table->createFromArray($array, $columns);

Výsledek

 

Ruční přidání sloupečků

Sloupečky je možné ručně přidávat funkcí addColumn($name, $column). Prvním argumentem je index sloupečku, pomocí kterého je možné jej získat zpět voláním getColumn($name). Počet sloupečků v tabulce nemusí odpovídat šířce záznamu ve vstupních datech, sloupečků může být více či méně než dat.

Kód

$array = [
   ['a', 3, 'Bar'],
   ['b', 1, 'Baz'],
   ['c', 2, 'Foo']
];

$table->createFromArray($array, []);
$table->addColumn(0, 'First');
$table->addColumn(1, new Column('Second', 1));

Výsledek

Vlastnosti sloupečků

VlastnostVýznam
titleTitulek sloupečku zobrazovaný v záhlaví a v editačních formulářích
fieldNameNázev formulářového pole. Defaultně odpovídá názvu sloupečku
fieldTypeTyp formulářového pole (input, select ...)
searchableUrčuje, zda má být obsah daného sloupečku zahrnut do globálního vyhledávání
sortableUrčuje, zda má být možné dle daného sloupečku řadit data
filterableUrčuje, zda má být podle daného sloupečku možné individuálně filtrovat data
visibleUrčuje, zda má být sloupeček viditelný. Pokud sloupeček viditelný není, posílají se klientovi i přesto příslušná data a může s nimi tedy pracovat
serverOnlyUrčuje, zda má sloupeček existovat pouze na straně serveru. Pokud je nastaveno, nebude sloupeček na straně klienta vůbec existovat ani se z něj nebudou posílat žádná data. Možné využití je jako zdroj dat pro vyhledávání nebo na definici formulářových prvků
dataSourceIndex ve vstupních datech, ze kterého mají být do sloupečku načítány hodnoty. Pokud je null, sloupeček s daty nepracuje
visibleInEditFormUrčuje, zda má pro daný sloupeček být vytvořeno pole v editačním formuláři
visibleInNewRecordFormUrčuje, zda má pro daný sloupeček být vytvořeno pole ve formuláři pro přidání nového záznamu
rendererTyp zobrazení dat ve sloupečku. Je možné použít některou z RENDERER_* konstant, nebo definovat vlastní typ.

Howto

Jak změnit způsob vykreslování hodnoty ve sloupečku?

U sloupečku definovat typ rendereru ($column->setRenderer('myRenderer')). V javascriptu definovat daný renderer pomocí:

myRichTable.registerRenderer('myRenderer', function(data, type, row, meta){
    return '<a class="cool">' + data + '</a>';
});

Význam jednotlivých argumentů viz. http://datatables.net/reference/option/columns.render#function

Jakým způsobem se generuje obsah editačního formuláře?

Třída Vivo\UI\RichTable\Column dědí od Vivo\UI\Form\Field a lze s ní tedy přímo pracovat jako s formulářovým polem. Editační formulář pak pouze posbírá všechny sloupečky, které mají nastaveno visibleInEditForm, a přidá je do formu.

Jak přidat do editačního formuláře položku, která není viditelná jako sloupeček?

Sloupečku stačí nastavit vlastnost serverOnly.

K čemu je u sloupečku dobré dataSource?

Určuje zdroj dat pro daný sloupeček (např. název sloupce v DB). Identifikátor sloupce v rámci tabulky a zdroj jeho dat jsou samostatné vlastnosti. Ve většině případů budou sice stejné, ale je možné například přidat sloupec, který žádná data nemá (jsou např. generována až na straně klienta pomocí JS), nebo naopak nastavit více sloupců na stejný zdroj dat.

Jak zobrazit ve formuláři pro přidání nového záznamu jiné položky, než v editačním formuláři?

Pomocí vlastností visibleInEditFormvisibleInNewRecordForm je možné určit ve kterém z formulářů se pole pro daný sloupeček má zobrazovat.

Jak zobrazit ve formuláři pro přidání nového záznamu stejné položky, jako v editačním formuláři, ale s jinými vlastnostmi (validátory apod.)?

Použít dva sloupečky. Jeden pro editační formulář, jeden pro formulář přidání záznamu. Pomocí vhodné kombinace s dataSource a fieldName je možné oba sloupečky nakonfigurovat tak, aby pracovaly nad stejnými daty.

Příklad pole, které je při vytváření záznamu editovatelné a při editaci readonly:

$columns = [
   'username' => new RichTable\Column(__('Username'), 'username'),
   'username_edit' => new RichTable\Column(__('Username'), 'username')
];
 
$table->getColumn('username')->setVisibleInEditForm(false); // Hide editable username in edit form
 
$table->getColumn('username_edit')->setVisibleInNewRecordForm(false); // Hide readonly username in new record form
$table->getColumn('username_edit')->setColumnProperties(false, false, false, false, true); // Set properties so the column is only used in the form
$table->getColumn('username_edit')->readonly = true; // Make the username in edit form readonly

Jak přidat podporu základních funkcí práce se záznamy?

Podpora jednotlivých operací v tabulce se aktivuje pomocí

$table->addBasicControls($enableNew, $enableEdit, $enableDelete)

Pro zpracování jednotlivých akcí je nutné přetížit příslušné funkce tabulky

protected function createRecord($data){}
protected function updateRecord($key, $data){}
protected function deleteRecords($keys){}

Do těchto funkcí již vstupují data, které úspěšně prošla validací v příslušných formulářích.

Jak použít pro tabulku jiný zdroj dat, než pole (např. DB)?

U tabulky je nutné přetížit metody

protected function queryData(DataRequest $dataRequest, DataResponse $dataResponse){}
protected function getRecordLabels(array $keys){}
protected function getRecord($key){}

Metoda queryData se stará o zpracování požadavku na zobrazení určité části dat. V $dataRequest jsou obsaženy všechny údaje o požadavku - počet záznamů, nastavení řazení, vyhledávané výrazy... Úkolem implementace je na základě těchto údajů naplnit příslušné hodnoty (počty záznamů celkem/po filtrování a samotná data) v proměnné $dataResponse.

Úkolem metody getRecordLabels je získání popisků pro záznamy s danými klíči za účelem jejich zobrazení v dialogu pro potvrzení smazání záznamů.

Metoda getRecord se pak stará o získání konkrétního záznamu pro jeho zobrazení v editačním dialogu.

Jak zobrazit v dialogu pro přidání/editaci/smazání záznamů vlastní obsah?

Obsahem dialogu může být libovolná UI komponenta dědící od UI\Form a implementující příslušný Vivo\UI\RichTable\FormInterface. Samotné tabulce je pak danou komponentu možné nastavit pomocí funkcí

$table->setNewRecordForm($newRecordForm);
$table->setEditForm($editForm);
$table->setDeleteForm($deleteForm);

Obsah, který má být zobrazen v dialogu, musí mít nastavenou třídu dialogContent, např.:

<form class="dialogContent">
	This will be visible in the dialog
</form>

<form>
	This will not
</form>

Veškeré formuláře obsažené v dialogu jsou automaticky napojené na potvrzovací tlačítko v příslušném dialogu a neměly by tedy obsahovat vlastní submit tlačítka.

Kde se inspirovat?

Modul Vivo\CMS\UI\Manager\SecurityDomain  využívá většinu vlastností tabulky včetně ukázky, jak v editačním dialogu zobrazit standardní entity editor.

  • No labels