BaseView – Klasa bazowa

Źródło: BaseView.js

BaseView jest klasą bazową dla wszystkich widoków w OrbitoViewEngine. Dziedziczy po HTMLElement, co oznacza, że każdy widok jest Custom Element.

Właściwości

groups

Tablica grup, do których należy widok. Może być używana do:

• Zarządzania widocznością grupy widoków
• Zbiorczego zbierania danych z inputów należących do tej samej grupy
• Organizacji widoków w logiczne sekcje

Grupy są automatycznie parsowane z pola groups w schemacie widoku podczas inicjalizacji.

type: text
groups:
  - section-1
  - editable
text: Treść widoku

viewId

Unikalny identyfikator widoku. Jeśli nie jest podany w schemacie, generowany jest automatycznie.

Zdarzenia cyklu życia

onLoad

Akcja wykonywana jednorazowo po dodaniu widoku do drzewa DOM. Obsługuje wszystkie akcje zdefiniowane w ActionHandler – tak samo jak onClick w ButtonView czy BadgeView.

type: card
title: Tytuł karty
content: []
onLoad:
  action: emit
  event: someEvent

Wywołanie metody API po załadowaniu:

type: card
onLoad:
  action: callMethod
  module: core/orders
  method: init
  then:
    action: reload
    target: ordersTable

Uwaga: onLoad jest wywoływane tylko raz – przy pierwszym podpięciu elementu do DOM. Ponowne przeniesienie elementu w drzewie DOM nie wyzwoli akcji po raz drugi.

onEvent

Tablica listenerów EventBus. Każdy wpis pozwala wykonać dowolną akcję z ActionHandler w momencie otrzymania wskazanego eventu. Listenery są rejestrowane przy connectedCallback i automatycznie usuwane przy disconnectedCallback.

type: card
onEvent:
  - event: order:updated
    action:
      action: reload
      target: ordersTable

Z warunkiem:

type: text
onEvent:
  - event: order:statusChanged
    condition:
      status: completed
    action:
      action: toast
      type: success
      title: Zamówienie zakończone

Operatory w condition

Składnia wzorowana na Mongo. Klucze obsługują dot-notation do odczytu zagnieżdżonych pól. Domyślnie wartość prosta oznacza równość (===).

condition:
  $page.someVar: order
  someView001:
    $neg: "some negated value"
  $event.status:
    $nin:
      - cancelled
      - archived

Uwaga: Wartość prosta (np. "completed") jest skrótem dla $eq. Klucze z kropką (np. "meta.type") odczytują zagnieżdżone pola z danych eventu.

Operator $size / $length

Sprawdza długość wartości — działa dla tablic (liczba elementów) oraz stringów (liczba znaków). Dla wartości innego typu warunek zwraca false. $size i $length to aliasy — działają identycznie.

Wartość operatora może być:

• liczbą — dopasowanie dokładnej długości (length === n),
• obiektem z operatorami porównania: $eq, $neq, $gt, $gte, $lt, $lte.

# tablica ma dokładnie 3 elementy
condition:
  tags:
    $size: 3

# co najmniej 2 elementy
condition:
  tags:
    $size:
      $gte: 2

# string krótszy niż 10 znaków
condition:
  name:
    $length:
      $lt: 10

onVarChange

Skrócona składnia do nasłuchiwania zmian zmiennych w VarStore. Alternatywa dla onEvent z ręczną nazwą eventu — pozwala reagować na setPageVar, setGlobalVar oraz zmiany danych widoków bez znajomości wewnętrznych nazw eventów.

type: card
onVarChange:
  - scope: page
    key: activeTab
    action:
      action: reload
      target: contentTable

Reagowanie na zmienną globalną z warunkiem:

type: text
onVarChange:
  - scope: global
    key: theme
    condition:
      value: dark
    action:
      action: emit
      event: applyDarkMode

Reagowanie na dane innego widoku:

type: card
onVarChange:
  - scope: view
    key: someViewId
    action:
      action: reload
      target: summaryPanel

Uwaga: Dane przekazane do akcji w onVarChange dla scope page/global to { key, value }, a dla scope view to { viewId, value }.

onKey

Tablica skrótów klawiszowych. Każdy wpis pozwala wykonać dowolną akcję z ActionHandler po naciśnięciu wskazanej kombinacji klawiszy (np. Escape, Ctrl+S). Listenery są rejestrowane przy connectedCallback i automatycznie usuwane przy disconnectedCallback.

Nazwy klawiszy odpowiadają wartościom KeyboardEvent.key (np. Enter, ArrowUp, Delete), z dodatkowymi aliasami: Esc, Up/Down/Left/Right, Space, Del, Plus, Return. Modyfikatory: Ctrl, Shift, Alt, Meta (Cmd) oraz Mod (= Ctrl na Windows/Linux lub Cmd na macOS).

type: card
onKey:
  - key: Escape
    action:
      action: closeModal
      target: editModal
  - key: Ctrl+S
    action:
      action: callMethod
      module: core/orders
      method: save

Skrót wieloplatformowy z warunkiem:

type: card
onKey:
  - key: Mod+Shift+K
    condition:
      $page.editing: true
    action:
      action: emit
      event: openCommandPalette

Uwaga: Dane przekazane do condition przez $event to { key, ctrl, shift, alt, meta }. Składnia warunku jest identyczna jak w onEvent.

renderIf

Warunkowe renderowanie widoku. Jeśli warunki nie są spełnione, widok nie jest budowany (nie jest tworzona jego zawartość ani widoki potomne). Gdy renderIf jest pominięte lub jest pustym obiektem, widok renderuje się normalnie.

Widok jest reaktywny — automatycznie nasłuchuje na zmienne użyte w warunkach ($page, $global oraz zmienne innych widoków) i pojawia się / znika, gdy ich wartość ulega zmianie. Listenery są rejestrowane przy connectedCallback i usuwane przy disconnectedCallback.

Składnia warunków jest identyczna jak w condition (sekcja onEvent). Klucz to ścieżka zmiennej, a widok nasłuchuje na jej zmiany:

• $page.<klucz> — zmienna strony
• $global.<klucz> — zmienna globalna
• <viewId>.<pole> — dane innego widoku (np. select001.value)

Renderuj tylko dla roli admin:

type: card
title: Panel administracyjny
renderIf:
  $global.role: admin
content: []

Renderuj gdy wybrano jedną z opcji:

type: text
content: Wybrano zamówienie aktywne lub oczekujące
renderIf:
  select001.value:
    $in:
      - active
      - pending

Wiele warunków (łączone operatorem AND):

type: button
label: Zapisz
renderIf:
  $page.editMode: true
  $global.role:
    $neq: viewer

Uwaga: Wszystkie warunki muszą być spełnione jednocześnie (AND). Wartość prosta (np. admin) jest skrótem dla $eq.

Notacja .$ w renderIf

Gdy widok jest renderowany jako element listy (listvar, list, kolumna datatable), w warunkach renderIf możesz użyć notacji .$, aby odwołać się do bieżącego elementu kolekcji. Symbol $ jest zamieniany na indeks aktualnego elementu.

Działa to w obu miejscach warunku:

• w wartości — np. '{{ ordersTable.$._id }}',
• w kluczu (ścieżce sprawdzanego pola) — np. ordersTable.$.products, gdzie $ zostaje zamienione na indeks bieżącego wiersza, dzięki czemu warunek odczytuje dane właśnie tego elementu listy.

Pokaż przycisk „zwiń" tylko dla rozwiniętego wiersza ($ w wartości):

type: html
renderIf:
  $page.expandedOrder: '{{ ordersTable.$._id }}'
content: <span>▴ zwiń</span>

Pokaż „wyświetl pozostałe", gdy wiersz NIE jest rozwinięty i ma > 3 produkty ($ zarówno w wartości, jak i w kluczu ordersTable.$.products):

type: html
renderIf:
  $page.expandedOrder:
    $neq: '{{ ordersTable.$._id }}'
  ordersTable.$.products:        # ← $ w kluczu = indeks bieżącego wiersza
    $size:
      $gt: 3
content: <span>▾ wyświetl pozostałe</span>

Szczegółowy opis notacji .$ (m.in. listy zagnieżdżone i samo {{ $ }}) znajdziesz w rozdziale Listy i notacja .$.

Wygląd widoku

Każdy widok przyjmuje trzy wspólne pola opisujące wygląd. Wszystkie działają obok siebie i są nadawane po zbudowaniu widoku, więc nie kolidują z jego własnymi klasami.

classIf

Włącza klasę, gdy warunek jest spełniony, i zdejmuje ją, gdy przestaje być. Korzysta z tego samego evaluatora warunków co renderIf — działają więc operatory ($gt, $gte, $lt, $lte, $in…), porównania typowane, notacja .$ oraz operandy { valueFrom }, które porównują dwie wartości ze sobą.

classIf:
  pk-green-row:
    packingDetail.products.$.packedQty:
      $gte:
        valueFrom: packingDetail.products.$.requiredQty

Klucz może zawierać kilka klas naraz ("text-danger fw-bold"). Widok nasłuchuje zmian obu stron porównania, więc klasa przelicza się bez przeładowania strony.

variantIf

Wybiera publiczny wariant widoku — kolor przycisku, kolor odznaki, kolor tekstu. Wygrywa pierwszy spełniony warunek; gdy żaden nie pasuje, obowiązuje variant ze schematu.

type: button
label: Pakuj
variant: secondary
variantIf:
  danger:
    packingDetail.missingQty: { $gt: 0 }
  success:
    packingDetail.missingQty: 0

Zmiana wariantu przebudowuje zawartość widoku, dlatego zasoby zarejestrowane w _build() (subskrypcje, timery) są przy tym zwalniane — patrz onCleanup().

Klikalny kafelek (ove-tile / ove-tile-action)

Gdy cały kafelek (kostka z logo, opisem itp.) ma być klikalny, nie wieszaj onClick na kontenerze — nałóż na niego przezroczysty przycisk. Kontener dostaje className: ove-tile (obramowanie, tło, promień, padding), a wewnątrz niego przycisk bez etykiety, rozciągnięty na całą powierzchnię klasą className: ove-tile-action w wariancie ghost-primary, niesie właściwy onClick:

- type: flex
  id: quickOptionTile
  direction: row
  className: ove-tile
  childs:
    - type: text
      content: Treść kafelka
    - type: button
      label: ''
      title: 'Wykonaj akcję'
      variant: ghost-primary
      className: ove-tile-action
      onClick:
        action: callMethod
        module: core/example
        method: doSomething

Kliknięcie, fokus i obsługa klawiatury zostają przy natywnym <button>, więc kontener kafelka nie musi udawać kontrolki ani dublować logiki dostępności. Hover nie zalewa przy tym kafelka szarym tłem jak zwykły przycisk — podświetla samą krawędź (ramka primary + cień), dzięki czemu logo i tekst w środku zostają czytelne pod kursorem.

Publiczne warianty zamiast style:

Widoki udostępniają nazwane opcje wyglądu, dzięki czemu schemat nie musi znać klas CSS ani wewnętrznego DOM-u widoku:

type: card
padding: sm
shadow: none
content:
  - type: text
    content: Klient
    size: sm
    muted: true
    transform: uppercase
    dense: true
  - type: input
    id: customerNameInput
    variant: borderless

Nieznana wartość opcji jest ignorowana i zgłaszana ostrzeżeniem w konsoli — literówka w schemacie nie psuje układu strony.

Publiczne API widoku

Metody, z których korzystają akcje — dostępne w każdym widoku:

Kontrolki wartości (input, select, checkbox, …) dokładają do tego kontrakt getValue() / setValue(value, { emitChange }), z którego korzysta akcja setValue.

Pełna lista dostępnych akcji: Dostępne Akcje (ActionHandler)