From 3f5d9a795e8ab0256f9e593677f59fb37ded89f9 Mon Sep 17 00:00:00 2001 From: Marcin Wojas Date: Mon, 12 Jan 2026 10:49:17 +0100 Subject: [PATCH] soneta-form-xml.skill --- soneta-form-xml/SKILL.md | 734 ++++++++++++ soneta-form-xml/assets/Adres.form.xml | 40 + .../Kontrahent.WarunkiHandlowe.pageform.xml | 62 + .../assets/MojObiekt.Ogolne.pageform.xml | 58 + soneta-form-xml/references/ELEMENTS.md | 864 ++++++++++++++ soneta-form-xml/references/Form.xsd | 1060 +++++++++++++++++ 6 files changed, 2818 insertions(+) create mode 100644 soneta-form-xml/SKILL.md create mode 100644 soneta-form-xml/assets/Adres.form.xml create mode 100644 soneta-form-xml/assets/Kontrahent.WarunkiHandlowe.pageform.xml create mode 100644 soneta-form-xml/assets/MojObiekt.Ogolne.pageform.xml create mode 100644 soneta-form-xml/references/ELEMENTS.md create mode 100644 soneta-form-xml/references/Form.xsd diff --git a/soneta-form-xml/SKILL.md b/soneta-form-xml/SKILL.md new file mode 100644 index 0000000..f783f30 --- /dev/null +++ b/soneta-form-xml/SKILL.md @@ -0,0 +1,734 @@ +--- +name: soneta-form-xml +description: Tworzenie plików form.xml opisujących formularze, zakładki i widoki UI dla platformy enova365/Soneta Enterprise. Używaj gdy użytkownik prosi o utworzenie zakładki formularza (pageform.xml), widoku listy (viewform.xml), formularza (form.xml), lookupu (lookupform.xml), lub gdy pyta o strukturę i składnię plików form.xml dla enova365. +--- + +# Soneta Form XML - Formularze UI + +Skill do tworzenia plików XML definiujących interfejs użytkownika w systemie enova365/Soneta Enterprise. + +## Typy plików formularzy + +| Typ pliku | Wzorzec nazwy | Przeznaczenie | +|-----------|---------------|---------------| +| **pageform.xml** | `{DataType}.{PageName}.pageform.xml` | Zakładka formularza edycji obiektu | +| **viewform.xml** | `{NazwaWidoku}.viewform.xml` | Widok listy zarejestrowanej jako folder (listy główne) | +| **gridform.xml** | `{IdentyfikatorListy}.gridform.xml` | Indywidualne ustawienia listy na formularzu | +| **lookupform.xml** | `{NazwaPodpowiedzi}.lookupform.xml` | Lista wyboru (lookup) | +| **form.xml** | `{Nazwa}.form.xml` | Współdzielony fragment UI (include) | + +### Format nazwy pageform.xml + +Nazwa pliku składa się z 4 części rozdzielonych kropkami: + +``` +{DataType}.{PageName}.pageform.xml +``` + +- **DataType** - typ danych, dla którego definiowana jest zakładka (np. `Towar`, `Kontrahent`, `DokumentHandlowy`) +- **PageName** - nazwa zakładki (np. `Ogolne`, `Dodatkowe`, `Adresy`) +- **pageform.xml** - stały sufiks + +**Przykłady:** +- `Towar.Ogolne.pageform.xml` +- `Towar.Dodatkowe.pageform.xml` +- `Kontrahent.Adresy.pageform.xml` +- `DokumentHandlowy.Pozycje.pageform.xml` + +### Format nazwy viewform.xml + +Nazwa pliku składa się z 3 części rozdzielonych kropkami: + +``` +{NazwaWidoku}.viewform.xml +``` + +**Przykłady:** +- `Towary.viewform.xml` +- `Kontrahenci.viewform.xml` +- `DokumentyHandlowe.viewform.xml` + +### Format nazwy gridform.xml + +Nazwa pliku składa się z 3 części rozdzielonych kropkami: + +``` +{IdentyfikatorListy}.gridform.xml +``` + +**Przykłady:** +- `PozycjeDokumentu.gridform.xml` +- `RachunkiBankowe.gridform.xml` + +### Format nazwy lookupform.xml + +Nazwa pliku składa się z 3 części rozdzielonych kropkami: + +``` +{NazwaPodpowiedzi}.lookupform.xml +``` + +**Przykłady:** +- `Towary.lookupform.xml` +- `Kontrahenci.lookupform.xml` + +## Hierarchia elementów XML + +Elementy XML dzielą się na trzy grupy dziedziczące po `uiElement`: + +1. **Elementy proste** - Field, Label, Command, Gap, Html, GroupBy, Axis +2. **Kontenery elementów** - Group, Stack, Row, Flow, Bar, Dashboard, Include, Page (dziedziczą po `ContainerElement`) +3. **Kolekcje** - Grid, Cards, Scheduler, Chart, Diagram, Pivot (dziedziczą po `CollectionElement`) + +## Struktura dokumentu + +Każdy plik formularza zaczyna się od deklaracji XML i elementu głównego `DataForm`: + +```xml + + + + +``` + +### Atrybuty DataForm + +| Atrybut | Opis | +|---------|------| +| `Priority` | Kolejność zakładek (domyślnie 100, niższa = wcześniej) | +| `RightName` | Opcjonalny. Nazwa uprawnienia do zakładki (tylko gdy inna niż standardowa) | +| `Contexts` | Warunki licencyjne, np. `"Licence.HAN \| Licence.FA"` (nie bindowane) | +| `ViewType` | Typ widoku: `None`, `Dialog`, `Form`, `Folder` | +| `Mode` | Tryb: `None`, `Form`, `Folder`, `Wizard`, `Modal`, `Popup`, `Frame` | +| `DataType` | Opcjonalny. Pełne określenie typu danych (wymagany tylko gdy nazwa pliku nie określa jednoznacznie typu), np. `"Soneta.Handel.DokumentHandlowy,Soneta.Handel"` | + +## Wspólne atrybuty elementów + +Następujące atrybuty mogą być użyte w **dowolnym** elemencie form.xml: + +| Atrybut | Opis | +|---------|------| +| `Name` | Identyfikator elementu, który można wykorzystać w kodzie C# | +| `Class` | Klasy stylów (lista wartości oddzielonych spacją) | +| `DataContext` | Zmienia kontekst danych dla elementu i wszystkich jego elementów podrzędnych | +| `Visibility` | Warunek widoczności (bindowalne z logiką biznesową) | +| `Renderable` | Czy element ma być dostępny. Wyrażenie liczone **raz** przy logowaniu operatora - optymalne dla warunków zależnych od środowiska, licencji i innych parametrów niezmiennych w trakcie sesji | + +### Atrybut CaptionHtml + +Atrybut `CaptionHtml` występuje w elementach: `Label`, `Field`, `Group`, `Page`, `Command` i innych. + +Może zawierać: +- Tekst etykiety (w formacie HTML) +- Wyrażenia bindowane w klamrach: `{wyrażenie}` - wartość tekstowa jest automatycznie kodowana do HTML +- Wyrażenia zwracające kod HTML: `{WłaściwośćHtml}` - nazwa musi mieć sufiks `Html`, wtedy wartość nie jest kodowana +- Podwójne klamry dla literalnych znaków: `{{` → `{`, `}}` → `}` + +**Specjalne przypadki w `Field`:** +- Brak atrybutu → automatyczna etykieta wyliczana na podstawie danych +- `CaptionHtml=" "` (spacja) → pusta etykieta (miejsce na etykietę zostaje zachowane) +- `CaptionHtml=""` (pusty) → brak etykiety (pole bez miejsca na etykietę) + +**Alternatywa:** Zamiast `CaptionHtml` można użyć `CaptionMarkdown` dla etykiet w formacie Markdown. + +## Elementy kontenerowe + +### Page - Zakładka + +Główny kontener dla zawartości zakładki: + +```xml + + + +``` + +| Atrybut | Opis | +|---------|------| +| `Name` | Opcjonalny. Unikalny identyfikator zakładki | +| `CaptionHtml` | Tytuł zakładki. Może zawierać `/` do grupowania zakładek (np. `"Dokumenty/Faktury"`) | +| `DataContext` | Źródło danych. `{DataSource}` oznacza obiekt edytowany na zakładce, ale można wskazać inne dane | +| `Visibility` | Wyrażenie warunkowe widoczności (bindowalne) | +| `Renderable` | Czy zakładka ma być dostępna. Wyrażenie liczone raz przy logowaniu - optymalne dla warunków zależnych od środowiska, licencji itp. | +| `Key` | Skrót klawiaturowy wywołujący zakładkę formularza | +| `GroupIcon` | Ikona grupy zakładek | + +### Zasada budowania zakładki formularza + +Zakładka składa się z elementów ``. Każda grupa może zawierać: + +1. **Listę pól w kolumnie** - pola ułożone pionowo jedno pod drugim +2. **Układ wielokolumnowy** - `` zawierający kilka `` z polami +3. **Listę elementów podrzędnych** - np. Grid, ewentualnie poprzedzony polami filtrującymi + +```xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +### Group - Grupa pól + +Wizualna ramka grupująca powiązane pola: + +```xml + + + + +``` + +| Atrybut | Opis | +|---------|------| +| `CaptionHtml` | Tytuł grupy | +| `LabelWidth` | Opcjonalny. Szerokość etykiet dla wszystkich pól w kontenerze | +| `Visibility` | Warunek widoczności (bindowalne z logiką biznesową) | +| `Renderable` | Czy grupa ma być dostępna (liczone raz przy logowaniu) | + +### Stack - Układ pionowy + +Układa elementy jeden pod drugim: + +```xml + + + + +``` + +### Row - Układ poziomy + +Układa elementy obok siebie w wierszu: + +```xml + + + + +``` + +**Pole na całą szerokość:** użyj `Width="*"` + +**Pola dosunięte do prawej:** umieść `` na początku: + +```xml + + + + + +``` + +### Flow - Układ płynny + +Elementy umieszczane są od lewej do prawej. Gdy nie mieszczą się na formularzu, przenoszone są do nowego wiersza: + +```xml + + + + + +``` + +## Elementy pól i kontrolek + +### Field - Pole edycyjne + +Podstawowy element do wyświetlania i edycji danych. Jest generowany **dynamicznie** - w zależności od typu właściwości wyświetla odpowiednią kontrolkę (int → pole numeryczne, bool → checkbox, double → pole z kalkulatorem, typ Sonety → lookup z listą wyboru). + +Minimalny `` powinien zawierać: +- `EditValue` - **wymagany**, binding do właściwości +- `CaptionHtml` - etykieta pola +- `Width` - szerokość pola + +```xml + +``` + +| Atrybut | Opis | +|---------|------| +| `EditValue` | **Wymagany**. Binding do właściwości: `{Właściwość}` lub `{new Extender.Właściwość}` | +| `CaptionHtml` | Etykieta pola (patrz sekcja "Atrybut CaptionHtml") | +| `Width` | Szerokość pola w znakach lub px (`*` = wypełnij) | +| `OuterWidth` | Całkowita szerokość z etykietą (do wyrównywania w pionie) | +| `LabelWidth` | Szerokość etykiety | +| `Height` | Wysokość w wierszach lub px (dla pól wieloliniowych) | +| `IsReadOnly` | Warunek tylko do odczytu (bindowalne z logiką biznesową). Logika biznesowa ma wyższy priorytet | +| `Visibility` | Warunek widoczności (bindowalne z logiką biznesową): `true`/`false`/`Visible`/`Hidden`/`Collapsed` | +| `Renderable` | Czy pole ma być dostępne (liczone raz przy logowaniu) | +| `Format` | Formatowanie wartości w standardzie .NET `string.Format`. Pole `{0}` to wartość edytowana | +| `Footer` | Agregacja w stopce **tylko na listach**: `Sum`, `Count`, `Average`, `Min`, `Max` | +| `CheckedValue` | Wartość dla **RadioButton** | +| `Class` | Klasy stylów (patrz sekcja Class) | +| `DataContext` | Zmienia kontekst danych dla tego pola i elementów podrzędnych | + +#### RadioButton + +Aby utworzyć RadioButton, dodaj parametr `CheckedValue`: + +```xml + + + +``` + +Pola z tym samym `EditValue` i różnymi `CheckedValue` tworzą grupę RadioButton. + +### Label - Etykieta + +Tekst bez możliwości edycji: + +```xml +