UiType

Moduł UiType (User Interface Type) jest kluczowym komponentem silnika prezentacji i transformacji danych w architekturze platformy Ammonly. Definiuje zachowanie wizualne, formatowanie, kontrolki formularzy oraz reguły serializacji dla każdego pola skonfigurowanego w systemie.

Separacja warstw

W Ammonly typ pola w bazie danych (np. VARCHAR, INT, JSON) jest całkowicie odseparowany od jego typu interfejsu (UiType). Dzięki temu ta sama kolumna tekstowa może funkcjonować jako wygodny selektor słownikowy, pole adresu e-mail, próbnik kolorów lub dynamiczny odnośnik URL.

1. Istota i rola UiType w systemie

UiType pełni rolę wzorca adaptera pomiędzy fizycznym rekordem w bazie danych a jego wielokanałową prezentacją: w tabeli DataGrid, w formularzu edycji, w widoku szczegółowym oraz w reprezentacji JSON w REST API.

mermaid

flowchart LR
    A[Fizyczna Kolumna SQL] --> B[Silnik UiType]
    B --> C[Kontrolka Formularza HTML5 / TomSelect]
    B --> D[Formatowanie w Tabeli DataGrid]
    B --> E[Serializacja do REST API]
    B --> F[Dedykowana Walidacja Wartości]

Podstawowe zadania modułu UiType:

Standaryzacja kontrolek: Automatyczny dobór właściwego elementu formularza (np. <input type="date">, wielolinijkowy edytor, przełącznik toggle czy asynchroniczny dropdown).
Dwukierunkowa transformacja: Bezpieczna konwersja danych pomiędzy surowym formatem HTTP a typowanym obiektem w bazie danych.
Spójność wizualna: Przypisanie domyślnych ikon systemowych (Bootstrap Icons), formatów dat oraz kolorowych etykiet (badges) w widokach list.

2. Pipeline transformacji danych

Wszystkie operacje odczytu i zapisu przechodzą przez scentralizowany rurociąg transformatorów (UiTypeTransformerPipeline). Proces ten gwarantuje, że dane zawsze trafiają do bazy w bezpiecznym formacie.

mermaid

sequenceDiagram
    autonumber
    actor User as Użytkownik / Klient API
    participant Pipeline as UiTypeTransformerPipeline
    participant DB as Warstwa Bazy Danych
    participant Grid as Widok DataGrid / HTML

    User->>Pipeline: Wejście surowe (np. "2026-09-06T12:00")
    Pipeline->>Pipeline: Normalizacja wejściowa (transformInput)
    Pipeline->>DB: Zapis w bazie (np. "2026-09-06 12:00:00")
    DB-->>Pipeline: Odczyt wartości z rekordu
    Pipeline->>Grid: Formatowanie wyjściowe (transformOutput)
    Grid-->>User: Wyświetlenie sformatowane (np. "06.09.2026 12:00")

Fazy cyklu życia wartości:

Transformacja wejściowa (transformInput): Oczyszcza i normalizuje dane wejściowe przekazane z formularza HTML lub payloadu REST API przed wykonaniem zapytania INSERT lub UPDATE.
Transformacja wyjściowa (transformOutput): Formatowuje surową wartość pobraną z bazy SQL do postaci czytelnej dla człowieka w widokach szczegółowych i tabelach.
Serializacja API: Przygotowuje ustandaryzowaną reprezentację JSON dla zewnętrznych integracji.

3. Przegląd kategorii UiType

Typy interfejsu w systemie Ammonly podzielone są na logiczne kategorie funkcjonalne:

1. Kategoria tekstowa (Textual)

Przeznaczona do przechowywania i edycji danych alfanumerycznych o zróżnicowanej długości i strukturze:

string_input (1001): Standardowe pole tekstowe jednolinijkowe z ograniczeniem długości.
text_area (1002): Pole wielolinijkowe do wprowadzania dłuższych treści i notatek.
rich_text (1003): Zaawansowany edytor wizualny WYSIWYG z formatowaniem HTML.
email_input (1005): Walidowany adres e-mail z automatycznym linkiem mailto: i akcją wysyłki poczty.
url_input (1007): Odnośnik internetowy z walidacją protokołu http:// lub https://.
phone_number (1008): Numer telefonu z formatowaniem międzynarodowym i integracją z dialerem.

2. Kategoria liczbowa i walutowa (Numeric & Currency)

Obsługuje precyzyjne operacje matematyczne i finansowe:

integer_number (2001): Liczba całkowita z walidacją formatu numerycznego.
decimal_number (2002): Liczba dziesiętna z konfigurowalną liczbą miejsc po przecinku.
currency_amount (3001): Wartość finansowa z symbolem waluty, separatorem tysięcy i zaokrągleniami.

3. Kategoria dat i czasu (Date & Time)

Zapewnia pełną kontrolę nad wymiarami czasowymi z uwzględnieniem strefy czasowej użytkownika:

date_picker (4001): Wybór daty w kalendarzu (format YYYY-MM-DD).
datetime_picker (4002): Połączony wybór daty i godziny z precyzją minutową.
time_picker (4003): Pole wyboru wyłącznie godziny i minut (format HH:MM).

4. Kategoria logiczna i słownikowa (Selection & Status)

boolean_toggle (5001): Przełącznik dwustanowy (Prawda / Fałsz) z czytelną kontrolką toggle.
picklist (6001): Pojedynczy wybór ze słownika systemowego z kolorowymi plakietkami i ikonami.
multipicklist (6002): Wybór wielu wartości słownikowych w postaci tagów.
color_picker (6005): Wybór koloru z palety systemowej do wizualizacji w kalendarzu lub na tablicach.

5. Kategoria relacyjna (Relational)

user_reference (7004): Dynamiczne powiązanie z użytkownikiem systemu (np. autor, właściciel rekordu).
relation_1m_picklist (7006): Asynchroniczne wyszukiwanie rekordu powiązanego w innym module.
relation_polymorphic (7008): Złożona relacja polimorficzna umożliwiająca wybór modułu i rekordu.

6. Kategoria techniczna i strukturalna (Technical)

json_display (8001): Formatowane dane JSON z walidacją składni i podświetlaniem struktury.
autonumber (9001): Samogenerujący się unikalny numer rekordu z prefiksem i sekwencją liczbową.

7. Kategoria systemowa i bezpieczeństwa (System & Security)

Dostęp specjalny (special_access / 6010): Kontrola cyklu życia rekordu (Widoczny, Zarchiwizowany, Usunięty, Ukryty) oraz poziomów dostępu bazodanowego. Modyfikacja dozwolona wyłącznie dla Superusera.
Flaga Superuser (is_superuser): Najwyższy poziom uprawnień administracyjnych w systemie, omijający ograniczenia ról i dający dostęp do rekordów ukrytych.

4. Kontrolki formularzy i komponenty UI

W zależności od typu pola silnik szablonów automatycznie ładuje dedykowane komponenty:

Kategoria	Komponent UI	Technologia wykonania
Tekst i Liczby	Standardowe kontrolki HTML5	Bootstrap 5.3 Form Controls
Słowniki i Relacje	Wyszukiwanie asynchroniczne	TomSelect z obsługą klawiatury
Daty i Godziny	Natywny kalendarz HTML5	Formaty `date` i `datetime-local`
Przełączniki	Kontrolka typu Toggle Switch	Bootstrap Form Switch
Kolory	Paleta barw i próbnik	HTML5 Color Input + paleta Tabler

5. Automatyczna walidacja i ikony

Każdy zarejestrowany UiType posiada wbudowane reguły formatowania i automatyczne weryfikacje wykonywane w silniku UniversalValidationEngine:

Walidacja poprawności adresu e-mail przez filtry FILTER_VALIDATE_EMAIL.
Sprawdzanie poprawności składni JSON za pomocą natywnej funkcji json_validate().
Weryfikacja wartości liczbowych (integer, float, numeric).
Dynamiczne przypisywanie ikon Bootstrap Icons do etykiet pól w formularzach i filtrach.

6. Bezpieczeństwo i higiena danych

Architektura modułu UiType gwarantuje rygorystyczne standardy bezpieczeństwa aplikacji internetowych:

Ochrona przed atakami XSS: Wszystkie wyjściowe wartości tekstowe są automatycznie bezpiecznie uciekane za pomocą filtrów szablonu Twig (|e('html') oraz |e('html_attr')).
Integralność relacji bazodanowych: Typy relacyjne weryfikują istnienie klucza obcego w tabeli docelowej przed zatwierdzeniem transakcji.
Rygorystyczne typowanie PHP 8.4: Brak podatności wynikających z niejawnej konwersji typów dzięki dyrektywie declare(strict_types=1); obecnej we wszystkich transformatorach silnika.

UiType ​

Spis treści ​

1. Istota i rola UiType w systemie ​

Podstawowe zadania modułu UiType: ​

2. Pipeline transformacji danych ​

Fazy cyklu życia wartości: ​

3. Przegląd kategorii UiType ​

1. Kategoria tekstowa (Textual) ​

2. Kategoria liczbowa i walutowa (Numeric & Currency) ​

3. Kategoria dat i czasu (Date & Time) ​

4. Kategoria logiczna i słownikowa (Selection & Status) ​

5. Kategoria relacyjna (Relational) ​

6. Kategoria techniczna i strukturalna (Technical) ​

7. Kategoria systemowa i bezpieczeństwa (System & Security) ​

4. Kontrolki formularzy i komponenty UI ​

5. Automatyczna walidacja i ikony ​

6. Bezpieczeństwo i higiena danych ​