DataTableView

Źródło: views/DataTableView.js

DataTableView

Rozbudowana tabela danych z paginacją, wyszukiwaniem, sortowaniem, selekcją i akcjami. Styl zgodny z Tabler UI.

Źródło danych

Tabela obsługuje dwa źródła — reszta konfiguracji (kolumny, selekcja, akcje, stopka) jest dla obu identyczna:

# 1. Lokalne — tablica ze stanu; filtrowanie, sortowanie i strony liczone lokalnie
data:
  varPath: $page.payments      # $page.* | $global.* | $props.* | <viewId>[.pole]
  searchFields: [title, note]  # pola przeszukiwane (domyślnie wszystkie proste)
  paginate: false              # wyłącza stronicowanie i stopkę (domyślnie włączone)

# 2. API — zapytanie do modułu; stronę wyników zwraca serwer
dataSource:
  module: core/orders
  method: list

Źródło lokalne odświeża się samo po zmianie wskazanej zmiennej — bez reload.

Układ karty

  • Nagłówek (card-header) niesie tytuł, pole wyszukiwania i przyciski akcji. Renderuje się tylko wtedy, gdy schemat podaje title, queryKey, search: true albo niepustą listę actions — tabela bez żadnego z nich nie rysuje nagłówka, więc nadaje się do wstawienia w cudzą kartę bez efektu karty w karcie.
  • Stopka (card-footer) niesie informację o liczbie wyników, kontrolkę liczby wierszy na stronę i paginację. Domyślnie jest; footer: false wyłącza ją w całości, a data.paginate: false ukrywa ją automatycznie — bez stronicowania nie ma czego stronicować, a licznik „od–do” tylko wprowadzałby w błąd.
  • embedded: true — tabela przeznaczona do wstawienia w content cudzej karty (card, modal). Host nie dostaje klasy card, tylko ove-datatable-embedded, a <table> traci card-table (ta klasa rozsuwa skrajne komórki o padding karty, co w cudzym card-body dałoby podwójny margines). Nagłówek i stopka renderują się na zwykłych zasadach, ale w tym trybie sensowna jest tabela bez title i z footer: false — inaczej znów widać ramy karty w karcie.
  • minHeight (string CSS, np. 0, 200px) ustawia minimalną wysokość obszaru tabeli. Domyślnie 300px, ale tylko gdy tabela ma stopkę — paginacja zmienia liczbę wierszy i bez rezerwy układ skakałby przy każdej zmianie strony. Bez stopki tabela zajmuje tyle, ile mają wiersze. Jawna wartość wygrywa w obu przypadkach.

Schema

type: datatable
id: ordersTable
title: Zamówienia
perPage: 10
perPageOptions:
  - 10
  - 25
  - 50
  - 100
footer: false                # bez paska z licznikiem i paginacją
columns:
  - header: ID Zamówienia
    field: orderId            # sama wartość z wiersza — bez szablonu
    sortable: true            # `sortKey` domyślnie równy `field`
    width: 150px
  - header: Nazwa Klienta
    field: customer.name
  - header: Kwota
    field: amount
    align: end
    decimals: 2
    suffix: " PLN"
    summary: sum              # wiersz podsumowań w stopce tabeli
  - header: Status
    content:                  # pełna swoboda — dowolne widoki w komórce
      - type: badge
        label: "{{ ordersTable.$.status }}"
  - header: ""
    width: 1%
    actions:                  # kolumna akcji wiersza
      - icon: pencil
        title: Edytuj
        action: openModal
        target: editModal
dataSource:
  module: core/products
  method: search
  params:
    status: active
    minQty: "#minQty"        # wartość z kontrolki o id "minQty"
    statusId: "$local.statusId"  # wartość z localStorage klucza "ove_statusId"
  responsePath: data
  totalPath: pagination.total
  pageParam: page
  perPageParam: perPage
  sortParam: sort
  sortDirParam: sortDir
queryKey: name
searchPlaceholder: "Szukaj..."
actions:
  - icon: plus
    label: Dodaj
    variant: primary
    action: openModal
    target: addModal
emptyMessage: Brak danych
loadingMessage: Ładowanie...
selectable: false
selectKey: _id

Parametry

  • type - Typ widoku: "datatable"
  • id - Identyfikator widoku (wymagane)
  • title - Tytuł tabeli (opcjonalne)
  • perPage - Liczba wyników na stronę (domyślnie: 10)
  • perPageOptions - Opcje wyboru liczby wyników (opcjonalne)
  • footer - false ukrywa stopkę karty (licznik wyników, liczba wierszy, paginacja); domyślnie stopka jest
  • embedded - true renderuje tabelę bez własnej karty (do wstawienia w content cudzej karty); domyślnie false
  • minHeight - Minimalna wysokość obszaru tabeli (string CSS); domyślnie 300px ze stopką, bez stopki brak
  • columns - Tablica definicji kolumn:
    • header - Nagłówek kolumny
    • field - Ścieżka do wartości w wierszu (customer.name); komórka pokazuje samą wartość
    • content - Tablica widoków w komórce (ma pierwszeństwo przed field)
    • actions - Lista akcji wiersza renderowana jako przyciski (ma pierwszeństwo przed content)
    • align - Wyrównanie: start, center, end
    • width - Szerokość kolumny (150px, 1%)
    • sortable / sortKey - Sortowanie (sortKey domyślnie równy field)
    • decimals, prefix, suffix, emptyText [template] - Formatowanie wartości field
    • summary - Podsumowanie w stopce: sum, avg, min, max, count (albo obiekt { agg, field, decimals, prefix, suffix })
    • summaryValue [template] - Gotowa wartość podsumowania zamiast agregacji
    • className / cellClassName - Dodatkowe klasy nagłówka / komórek
  • data - Lokalne źródło danych (varPath, searchFields, paginate)
  • dataSource - Źródło danych z API
  • queryKey - Nazwa parametru wyszukiwania w API (pokazuje pole wyszukiwania jeśli podane)
  • search - true pokazuje pole wyszukiwania dla źródła lokalnego (bez parametru API)
  • searchPlaceholder - Placeholder dla pola wyszukiwania (opcjonalne)
  • actions - Akcje w nagłówku tabeli (opcjonalne)
  • emptyMessage - Komunikat gdy brak wyników (opcjonalne)
  • loadingMessage - Komunikat ładowania (opcjonalne)
  • selectable - Czy wiersze są zaznaczalne (opcjonalne)
  • selectKey - Klucz identyfikatora dla zaznaczania (opcjonalne)
  • rowKey - Klucz identyfikujący wiersz przy edycji (domyślnie selectKey, potem _id)
  • editable - Edycja wiersza w miejscu (patrz niżej)

Edycja wiersza

rowKey: id
editable:
  fields:                       # wspólny opis pól (`formFields.js`)
    - key: qty
      type: number
      min: 0
      required: true
    - key: note
  save:
    module: core/orders
    method: product.update
    params:
      orderId: { valueFrom: $page.orderId }
    rowKeyParam: productId      # nazwa parametru z identyfikatorem (domyślnie `rowKey`)
    onlyChanged: true
    refresh: [orderDetail]
columns:
  - header: Ilość
    field: qty                  # w trybie edycji zamienia się w kontrolkę pola `qty`

Tabela dokłada kolumnę z przyciskami ✎ / ✓ / ✕. Edycja działa na roboczej kopii danych (FormDraft), więc anulowanie nie wymaga przeładowania, a walidacja pól wykonuje się przed wysłaniem. Edytowany wiersz rozpoznawany jest po rowKey, więc przetrwa sortowanie i odświeżenie danych; gdy zniknie ze zbioru, edycja się zamyka. Błąd zapisu pokazuje się pod wierszem, a wiersz zostaje w trybie edycji.

Emitowane zdarzenia

  • datatable:loaded:${id} - po załadowaniu danych
  • datatable:pageChange:${id} - po zmianie strony
  • datatable:search:${id} - po wyszukiwaniu
  • datatable:sort:${id} - po sortowaniu
  • datatable:select:${id} - po zaznaczeniu wierszy
  • datatable:rowClick:${id} - po kliknięciu w wiersz
  • datatable:editRow:${id} - po otwarciu edycji wiersza
  • datatable:cancelRow:${id} - po anulowaniu edycji
  • datatable:savedRow:${id} - po udanym zapisie wiersza

Podsumowania a źródło danych

Źródło lokalne agreguje wszystkie przefiltrowane wiersze, źródło API — tylko wiersze bieżącej strony (przeglądarka nie zna pozostałych). Dla sum z serwera użyj summaryValue z wartością zwróconą w odpowiedzi.

Ostatnio zaktualizowano::
Contributors: Wiktor Koźmiński, Claude Fable 5.1