SZ-TABLES

Tabulka pro zobrazení dat, původně část aplikace DCS.

INSTALACE

npm install git+ssh://[e-mail]/spravazeleznic/sz-tables.git --legacy-peer-deps
npm install @emotion/react@11.9.0 @emotion/styled@11.8.1 @mui/icons-material@5.10.6 @mui/material@5.10.6 array-move@4.0.0 axios@0.27.2 process@0.11.10 prop-types@15.8.1 react@18.2.0 react-dom@18.2.0 react-sortable-hoc@2.0.0 react-toastify@9.0.4 --legacy-peer-deps

*(--legacy-peer-deps se používá kvůli drag & drop knihovně, která již nemá nové aktualizace)

NASTAVENÍ

Pole objektů. Příklad:

const defaultColumns = [{
    headerName: "time",
    visible: true,

    headerNameCZ: tx(COLUMN.time),
    sortDeactivated: true,
    styles: { width: "5.4vw" },

    //    Sorting - no db
    sorting: { val: false, asc: "desc", order: 0 },
}]

Nejprve je potřeba vytvořit nastavení tabulky (pole objektů). Každý objekt obsahuje nastavení jednoho sloupce (i jeho pořadí).

**PROPERTY OBJEKTU - POVINNÉ**
- **headerName: "time"**: string - musí odpovídat jménu property dat z response API endpointu
- **headerNameCZ: "Čas"**: string - libovolný název sloupce, zobrazí se v aplikaci
- **sorting: { val: false, asc: "desc", order: 0 }**: objekt - defaultní nastavení řádkového řazení


**PROPERTY OBJEKTU - NEPOVINNÉ**
- **visible: true**: boolean - sloupec on/off (defaultní nastavení viditelnosti sloupce)
- **useValueFrom: "time"**: string nebo array (od 1.8.1) - název jiného headerName (sloupce) - použije hodnotu tohoto jiného-definovaného sloupce pro data tabulky (např. čas a datum mohou být 2x sloupec - 1x hodnota), v případě pole vrátí string hodnot složených pomocí znaku ~
- **sortDeactivated: true,**: boolean - true vypne řádkový filtr daného sloupce
- **styles: { width: "5.4vw" }**: objekt - nastaví CSS pro daný header sloupce (např. width nastaví hodnotu šířky sloupce)
- **stylesData: { textAlign: "right" }**: objekt - nastaví CSS pro danou buňku hodnoty sloupce (např. textAlign nastaví zarovnání hodnoty v buňce)
- **formatter: (val, rowData) => { return roundNumber(parseFloat(val), 3); }**: funkce - slouží pro libovolnou úpravu hodnoty, např. zaokrouhlení čísla (na vstupu hodnota -> vrací upravenou hodnotu)
- **type: "GoogleMapsLink"**: string - nastaví typ speciálního zobrazení hodnoty, musí odpovídat nabídce: "GoogleMapsLink" - ikona mapy s proklikem, "Checkbox" - checkbox pro DCS Watchdog
- **onClick: "memoizedHandleOpenModal"**: string - jméno funkce definované mimo tabulku, která se spustí na proklik hodnoty (typicky proklik na modal)
- **apiException: ["ehv", "link", "name"]**: array - vrátí hodnotu objektu dle cesty složené z tohoto pole
- **customIcon: "icon1"**: string - jméno property **customIcons** (volitelný props komponenty tabulky) kterou chceme použít pro daný sloupec

POUŽITÍ

* Příklad použití v App.js viz VÝVOJ SZ-TABLES níže

import { ListTable } from "sz-tables";

// do verze 1.3.5
import { makeOrderDefaults, makeColumnsSettings } from "sz-tables/dist/components/tables/services/tableData";

// od verze 1.4.0
// staré - změna cesty
import { makeOrderDefaults, makeColumnsSettings } from "sz-tables";
// nové
import { apiconnection, apiConnectionFake, apiconnectionSave } from "sz-tables";

SLOŽENÍ PROPSŮ
Definice statů pro tabulku:

const [t0Columns, setT0Columns] = useState([]);
const [rows, setRows] = useState([]);

Funkce, která připraví staty pro tabulku (uživatelské nastavení + nastavení tabulky - obě se posílají zvlášť kvůli úspoře znaků odesílaných v payloadu pro db). ```sh useEffect(() => { //if (!authState.loading) { // let orderSettings = getContextColumnsAllOrder()?.setting_types?.T0;

// if (!orderSettings) {
  orderSettings = makeOrderDefaults(defaultColumns);
//}

setT0Columns(makeColumnsSettings(orderSettings, defaultColumns));

//} }, [authState.loading]);

**Tady je třeba:**<br />
1/ copy & paste <br />
2/ upravit orderSettings (načtení uživatelského nastavení tabulky z globalního statu/db)<br />
3/ definovat spuštění useEffectu ("authState.loading").<br />

<br />
**JSX**
```sh
<ListTable
  loadingApi={loadingApi}
  apiLoaded={apiLoaded}
  dataLoading={authState.loading}
  // List data props
  columns={t0Columns}
  setColumns={setT0Columns}
  rows={rows}
  // Modals props
  memoizedHandleOpenModal={memoizedHandleOpenModal}
  // User prop - email
  user={authState.user}
  // Column changes
  tableColumnsUpdating={tableColumnsUpdating}
  //callApi
  callApi={callApi}
  // row styles
  rowStyles: {
    backgroundColor: "lightgreen",
  },
  rowStylesRemainder: 2,
  rowStylesRemainderModifier: -1,
/>

**LOADING STATY**
**loadingApi** - boolean - načítání dat z API
**apiLoaded** - boolean - data z API jsou načtena
**dataLoading** - boolean - načítání globalního statu


**DATA**
**columns, setColumns** - nastavení sloupců (pozn.: vytvoří se automaticky přes utils, viz výše)
**rows** - pole objektů - samotná data těla tabulky (název property musí odpovídat názvům property headerName v listSettings.js (Pozn.: Není třeba je vytvářet, stačí přeposlat response BE.))

**nepovinné**
**rowClick** - boolean - true zapne funkcionalitu prokliku řádků -> na proklik spustí funkci definovanou v propsu memoizedHandleOpenModal ```sh rowClick: true, memoizedHandleOpenModal: () => { console.log("row clicked"); }, ```

**rowStyles** - objekt se styly pro jednotlivé řádky
**rowStylesRemainder** - číslo - ne vždy chceme aplikovat styly pro všechny řádky, styl se aplikuje pro každý x. řádek (2 - každý druhý řádek)
**rowStylesRemainderModifier** - číslo - posunutí rowStylesRemainderu o x řádků, pro posunutí je třeba zadat záporné číslo -> pro případ, že chceme změnit pořádí řádků s aplikovaným stylem, např. -1 pokud chceme mít první řádek bez stylu

**customIcons** - objekt, jeho property jsou funkce které vrací JSX (tj. i libovolná komponenta, nemusí být ikona), výběr pro daný sloupec pomocí prop. nastavení **customIcon** (string)
od **1.9.2** na vstupu komponenty-funkce hodnota buňky (např. na jejím základě může komponenta vybrat ikonu)

Příklad objektu:

{
  date: "24. 08. 2022"
  dateCreated: "2022-08-24T09:22:25.719+02:00"
  destinationPath: "bad\\383051\\Meter_383051_016a5c_2102130030.abl.gz"
  errorCount: 1
  id: 54
  name: "Meter_383051_016a5c_2102130030.abl.gz"
  status: "Error"
  time: "09:22:25"
}

**MODAL PROPSY** - nepovinné
**memoizedHandleOpenModal** - spustí funkci definovanou mimo tabulku (memoizedHandleOpenModal) po kliknutí na hodnotu tabulky (onCLick v listSettings.js - onClick: "memoizedHandleOpenModal"). Obvykle se používá pro manipulaci se statem pro otevření modalu. Na vstupu dostane argumenty - e, rowData, id (synteticky event, data radku, id(fileId) radku pokud existuje)

**USER**
**user** - string - zpravidla email

**OSTATNÍ**
**tableColumnsUpdating** - string - spustí funkci definovanou mimo tabulku ve chvíli, kdy dojde ke změně nastavení tabulky vlivem uživatelského zásahu (např. vypnutí či změna pořadí sloupců). Na svém vstupu podává aktualizované columns, nejčastěji pro uložení do contextu a db.

Příklad funkce:

const tableColumnsUpdating = (updatedColumns) => {
  setT0Columns(updatedColumns);
  setContextColumnsOrder(dispatch, "T0", updatedColumns);
};

**callApi** - Spustí funkci definovanou mimo tabulku, která načte data tabulky. Např. uživatel zmáčkne tlačítko refresh.

VÝVOJ

npm start

SZ-TABLES může fungovat i jako samostatná aplikace s výchozí stránkou App.js pro vlastní vývoj.

PUBLIKOVÁNÍ

npm run build

_(git add . -> git commit -m "...abc" -> git push)_