# Komponenty złożone ## Wprowadzenie Komponent złożony pozwala zamknąć kawałek ekranu aplikacji w spójny, reużywalny element.\ W komponencie zdefiniowany jest zarówno wygląd obszaru ekranu jak i jego zachowanie. Zespoły wykorzystujące komponenty złożone do budowy interfejsów użytkownika oszczędzają czas oraz ułatwiają sobie zadanie utrzymania spójności frontendu. ### **Rola i zastosowania** Główną rolą komponentów złożonych jest **wielokrotne reużycie** powtarzalnych obszarów formularza na rożnych stronach. Raz utworzony komponent złożony można osadzić: * na różnych stronach formularza – dzięki czemu wiele stron może korzystać ze wspólnej, spójnej części * wielokrotnie na tej samej stronie – np. jeżeli w jednym formularzu potrzebne są dwie niezależne sekcje adresowe (dla adresu zameldowania i korespondencyjnego). Takie podejście znacząco przyspiesza tworzenie aplikacji i ułatwia utrzymanie – zmiana w definicji komponentu złożonego automatycznie wpływa na wszystkie miejsca, w których został on użyty. Zwiększa to spójność aplikacji (te same komponenty prezentują się i działają identycznie w różnych formularzach) oraz redukuje ryzyko błędów wynikających z duplikowania konfiguracji. Na przykład, jeśli w formularzu potrzebujemy powtarzającej się sekcji z tymi samymi polami (jak wspomniana sekcja adresu), warto wydzielić ją jako komponent złożony i użyć go wielokrotnie zamiast tworzyć te pola od podstaw za każdym razem. Komponenty złożone są często wykorzystywane w aplikacjach biznesowych jako standardowe sekcje formularzy (np. dane adresowe, dane kontaktowe, sekcje z informacjami o kliencie itp.), co zapewnia jednolitość doświadczenia użytkownika i ułatwia rozwój kolejnych formularzy.

Ilustracja 1. "Komponenty złożone" w module "Biblioteka"

## Tworzenie komponentu Aby utworzyć nowy komponent złożony lub edytować istniejący, należy: 1. W **Eximee Designer** przejść do modułu **Biblioteka** i wybrać zakładkę **Komponenty złożone,** 1. w tym widoku wyświetlana jest lista wszystkich dostępnych komponentów złożonych w repozytorium wraz z opcjami zarządzania, 2. Z poziomu listy można: 1. utworzyć nowy komponent (przycisk **Dodaj komponent złożony**), 2. skopiować lub edytować istniejący artefakt korzystając z rozwijanego menu (trzy kropki) 3. przejrzeć historię wersji komponentu korzystając z rozwijanego menu (trzy kropki) 3. Wybrać opcję dodawania nowego komponentu złożonego 1. pojawia się okno tworzenia artefaktu, w którym podajemy nazwę komponentu oraz lokalizację (folder) w drzewie projektu, analogicznie jak przy tworzeniu nowego formularza.

Ilustracja 2. "Okno z listą komponentów złożonych w bibliotece"

Po utworzeniu artefaktu komponentu złożonego otwiera się **edytor komponentów złożonych**, bardzo podobny do edytora formularza. W centralnej części widoku projektujemy układ i dodajemy potrzebne pola oraz kontrolki – można przeciągać na obszar roboczy komponenty bazowe (np. pola tekstowe, listy, przyciski etc.) lub nawet zagnieżdżać inne dostępne komponenty złożone. W ten sposób definiujemy wewnętrzną strukturę nowego komponentu złożonego. Z prawej strony dostępny jest panel właściwości, w którym konfigurujemy atrybuty zaznaczonych pól (tak jak w formularzu). Po skonfigurowaniu zawartości komponentu złożonego zapisujemy go, nadając odpowiednią wersję (o wersjonowaniu więcej poniżej). Zapisanie powoduje utworzenie nowej wersji artefaktu, która może zostać użyta w formularzach.

Ilustracja 3. "Okno edytora komponentu złożonego – projektowanie zawartości"

## Parametry **wejściowe** Komponenty złożone mogą przyjmować **parametry wejściowe**, co pozwala przekazywać do ich wnętrza wartości z zewnątrz – z formularza lub nawet z innego komponentu złożonego. Aby zdefiniować parametr wejściowy, w edycji definicji komponentu złożonego należy w lewym panelu wybrać opcję **Parametry wejściowe**, a następnie kliknąć **Dodaj parametr wejściowy.** Każdy parametr wejściowy odwołuje się do jakiegoś pola lub zmiennej sesyjnej z kontekstu **osadzania** komponentu (czyli będzie oczekiwał przypisania konkretnego pola/zmiennej, gdy komponent zostanie użyty). Definiując parametr: * wskazujemy źródło wartości (pole formularza lub zmienna), * opcjonalnie nadajemy *alias* (przyjazną nazwę wyświetlaną podczas mapowania) * opcjonalnie podajemy wartość domyślną – używaną, jeśli podczas osadzania nie zostanie przypisana żadna wartość. Możliwe jest mapowanie wartości z pól formularza nadrzędnego, pól z innych komponentów złożonych znajdujących się na tym samym formularzu, a także zmiennych sesyjnych dostępnych w kontekście formularza. Dzięki mechanizmowi parametrów wejściowych komponent złożony może być bardziej uniwersalny – np. zamiast odwoływać się wewnątrz do konkretnej zmiennej globalnej, może przyjmować wartość jako parametr, co pozwoli użyć go w różnych miejscach z różnymi danymi.

Ilustracja 4. "Panel konfiguracji parametrów wejściowych w edytorze komponentu złożonego"

## Osadzanie komponentu Utworzony komponent złożony można osadzić w dowolnym formularzu lub nawet wewnątrz innego komponentu złożonego (zagnieżdżanie) – platforma dopuszcza dowolne poziomy zagnieżdżeń. Aby użyć komponentu złożonego w formularzu, należy przejść do edycji tego formularza, a następnie z palety komponentów po lewej stronie wybrać zakładkę **Złożone**. Wyświetli się lista wszystkich dostępnych komponentów złożonych w repozytorium (z możliwością wyszukiwania po nazwie). Z tej listy wybieramy odpowiedni komponent i dodajemy go do formularza metodą przeciągnij-upuść w żądane miejsce struktury formularza. Po upuszczeniu, komponent złożony zostanie osadzony na formularzu jako jedna logiczna całość – w drzewie struktury formularza widoczny będzie jako pojedynczy węzeł zawierający w sobie zdefiniowane wcześniej pola. {% hint style="info" %} Jeżeli osadzany komponent złożony posiada zdefiniowane parametry wejściowe, po jego dodaniu do formularza **należy skonfigurować mapowanie tych parametrów**, przypisując im odpowiednie pola lub wartości w kontekście formularza lub komponentu nadrzędnego. W edytorze formularza służy do tego sekcja **Parametry wejściowe** we właściwościach osadzonego komponentu – wystarczy zaznaczyć komponent złożony na formularzu i kliknąć ikonę ołówka przy polu *Parametry wejściowe*, aby otworzyć okno mapowania. {% endhint %}

Ilustracja 5. "Okno mapowania parametrów wejściowych przy osadzeniu komponentu złożonego na formularzu"

Komponent złożony umieszczony na ekranie staje się jego integralną częścią. Wszystkie zawarte w nim pola dziedziczą zachowanie standardowych pól – np. pola wymagane muszą być uzupełnione, walidatory przypięte do pól wewnątrz komponentu złożonego działają tak samo, jak w przypadku pól dodanych bezpośrednio na formularzu itp. W razie potrzeby, na poziomie formularza można także definiować dodatkowe **walidatory formularza** obejmujące również pola wewnątrz komponentów złożonych (np. skrypt sprawdzający spójność danych między sekcjami). Podobnie, mechanizmy nawigacji czy warunkowej widoczności działają również na zagnieżdżone komponenty – komponent złożony można np. ukrywać lub pokazywać w zależności od warunku, analogicznie do pojedynczego pola. ## Wersjonowanie i propagacja zmian Wersjonowanie zostało szczegółowo opisane [tutaj](/budowanie-aplikacji/aplikacja-biznesowa/wersjonowanie.md). ## Interakcje z innymi artefaktami Komponent złożony nie funkcjonuje w próżni – wchodzi w interakcje z różnymi elementami platformy ### Formularze Podstawową „relacją” jest osadzenie na formularzu, co zostało omówione powyżej. Z punktu widzenia formularza komponent złożony jest po prostu elementem formularza – podczas działania aplikacji użytkownik końcowy nie widzi różnicy między polami pochodzącymi z komponentu złożonego a innymi polami. W **zakładce Tłumaczenia** formularza wszystkie teksty zawarte w osadzonych komponentach złożonych są dostępne do edycji – oznacza to, że tłumaczenia etykiet i podpowiedzi z komponentu złożonego mogą być nadpisane lub dostosowane na poziomie konkretnego formularza, jeśli zajdzie taka potrzeba. Komponent złożony jest także traktowany jako część składowa aplikacji. ### Walidatory Pola w ramach komponentu złożonego mogą korzystać ze wszystkich mechanizmów walidacji dostępnych dla zwykłych pól. Jeśli do któregoś z pól wewnątrz komponentu złożonego przypiszemy **walidator skryptowy**, będzie on wykonywany tak samo, jak dla pola standardowego na formularzu. Również **warunki widoczności** czy **warunki wymagalności** można definiować dla pól wewnątrz komponentu złożonego – będą one respektowane po osadzeniu komponentu w formularzu. Co więcej, walidatory definiowane na poziomie całego formularza (np. weryfikujące zależności między różnymi polami) mogą odnosić się do pól znajdujących się w komponentach złożonych. Identyfikacja takiego pola może odbywać się po jego **identyfikatorze biznesowym (mid)** – komponenty złożone i ich pola posiadają identyfikatory biznesowe tak jak zwykłe pola formularza, co ułatwia odwoływanie się do nich w skryptach i konfiguracjach. ### Treści formatowane W komponentach złożonych można wykorzystywać również **artefakty treści** (TextContent), analogicznie jak w zwykłych formularzach. Jeśli jakaś sekcja wymaga osadzenia większego bloku statycznego tekstu (np. warunków, klauzul, opisów), można w komponencie złożonym dodać kontrolkę typu **Treść sformatowana** i podpiąć do niej artefakt Treść zawierający odpowiednią zawartość (zarządzaną centralnie). Dzięki temu komponent złożony może zawierać nie tylko pola danych, ale i elementy informacyjne czy instrukcje dla użytkownika, co czyni go kompletnym, reużywalnym fragmentem interfejsu użytkownika. ### Usługi i zmienne Jeżeli wewnątrz komponentu złożonego używane są **zmienne sesyjne** (np. do przechowywania przejściowych wartości lub wyników usług), należy pamiętać aby w wyrażeniach warunkowych poprzedzać nazwy tych zmiennych symbolem `@.` Dzięki temu platforma odróżni zmienną sesyjną komponentu od zmiennej sesyjnej formularza nadrzędnego. Ponadto zmienne sesyjne nie mogą być bezpośrednio wykorzystywane w komponentach typu *Sekcja powtarzalna* wewnątrz komponentu złożonego – w takich sytuacjach zaleca się użycie pól technicznych jako nośnika wartości. Jeśli komponent złożony potrzebuje skorzystać z zewnętrznej usługi (np. do wypełnienia swoich pól na podstawie danych z bazy), może wywoływać **usługi** tak jak formularz. Usługę można podpiąć jako *PageService* w logice komponentu i np.: wywołać w odpowiedzi na zdarzenie (np. zmianę pola). Trzeba jednak pamiętać, że usługi działają w kontekście całego wniosku, więc wywołanie serwisu z poziomu komponentu wpływa na formularz nadrzędny. ## **Dobre praktyki** ### **Identyfikacja możliwości reużycia** Już na etapie analizy wymagań warto identyfikować sekcje formularzy, które mogą pojawiać się wielokrotnie albo w wielu różnych formularzach aplikacji. Takie sekcje (np. dane adresowe, dane personalne klienta, sekcja informacji kontaktowych, sekcje zgód itp.) powinny być projektowane jako oddzielne komponenty złożone, zamiast powielać te same pola w wielu miejscach. Ułatwia to rozwój (sekcja jest tworzona raz) i utrzymanie (modyfikacja sekcji w jednym miejscu aktualizuje ją wszędzie tam, gdzie jest użyta). ### **Nazewnictwo i organizacja** Stosuj spójne nazewnictwo artefaktów. Komponent złożony powinien mieć nazwę jasno wskazującą na jego zawartość lub przeznaczenie. Często stosuje się konwencję poprzedzania nazw komponentów prefiksem związanym z aplikacją lub modułem biznesowym, np. `crmAdresKlienta`, `ubezDanePojazdu` – dzięki temu w repozytorium łatwiej zidentyfikować, do jakiego obszaru należy dany komponent. Ponadto utrzymuj porządek w strukturze katalogów w Bibliotece – komponenty złożone warto grupować w folderach tematycznych lub projektowych. ### **Dokumentowanie komponentu** Każdy komponent złożony można opatrzyć wewnętrzną **dokumentacją**. W zakładce **Właściwości** edytora komponentu złożonego dostępna jest sekcja „Dokumentacja”, w której można opisać działanie i przeznaczenie komponentu (obsługuje ona formatowanie HTML). Zaleca się uzupełnienie dokumentacji dla komponentu – zwłaszcza jeśli będzie on wykorzystywany przez wielu developerów lub w wielu miejscach – aby użytkownicy platformy wiedzieli, jak poprawnie go zastosować i jakie są jego ewentualne zależności. Dobra dokumentacja ułatwia ponowne użycie komponentu oraz przyspiesza onboarding nowych członków zespołu.

Ilustracja 6. "Zakładka „Właściwości” komponentu złożonego – podgląd dokumentacji"

### **Wersjonowanie i zgodność wsteczna** Planując zmiany w komponencie złożonym, rozważ ich wpływ na istniejące formularze. **Unikaj wprowadzania niezgodnych zmian** bez podbicia wersji głównej (MAJOR). Jeśli konieczna jest zmiana struktury lub zachowania komponentu, która mogłaby zaburzyć działanie formularzy go używających, lepiej utworzyć nową gałąź wersji. Po modyfikacjach testuj komponent złożony we wszystkich krytycznych scenariuszach – zwłaszcza, gdy komponent jest używany w wielu miejscach. ### **Unikanie zbyt dużej złożoności** Choć komponenty złożone mogą zawierać dowolną logikę, staraj się, by realizowały one w miarę jednolitą, jasno określoną funkcję. Unikaj tworzenia jednego ogromnego komponentu złożonego obsługującego bardzo wiele niezwiązanych ze sobą zadań – lepiej podzielić go na mniejsze, bardziej wyspecjalizowane sekcje. Zbytnie zagnieżdżanie komponentów złożonych (komponent w komponencie w komponencie itd.) również może utrudnić debugowanie i zrozumienie formularza – wykorzystuj tę możliwość z rozwagą, kierując się czytelnością struktury formularza. ### **Ostrożnie z kopiowaniem komponentów** Platforma umożliwia duplikację komponentu złożonego (opcją **Duplikuj** na liście komponentów złożonych) – przydaje się to, gdy chcemy na bazie istniejącego stworzyć podobny komponent. Jednak **upewnij się, jak traktowane są komponenty zagnieżdżone** podczas kopiowania. Jeżeli kopiowany komponent złożony zawierał inne komponenty złożone, w kopii **nie powstaną ich duplikaty** – zostaną zachowane referencje do oryginalnych artefaktów. Trzeba się zastanowić, czy w nowym komponencie chcemy nadal korzystać z tamtych oryginalnych, współdzielonych pod-komponentów, czy też powinniśmy je również skopiować (np. gdy zmiany w nich nie powinny wpływać na nasz nowy komponent). Jest to ważne z punktu widzenia utrzymania – nieświadome edytowanie komponentu zagnieżdżonego może wpłynąć na inne miejsca, gdzie jest użyty. ### **Wykorzystywanie gotowych komponentów** Sprawdź, czy potrzebny Ci komponent złożony już nie istnieje w bibliotece – szczególnie w większych organizacjach może powstawać katalog wspólnych komponentów. Wykorzystywanie już przygotowanych, przetestowanych komponentów (np. komponentów autoryzacji użytkownika, komponentu dokumentów do pobrania, sekcji zgód RODO itp.) jest szybsze i bezpieczniejsze niż tworzenie własnych od zera. Buduj nowe komponenty złożone wtedy, gdy faktycznie brakuje odpowiedniej funkcjonalności w istniejących zasobach. ### **Spójność UX** Pamiętaj, że komponent złożony jest częścią interfejsu użytkownika – projektuj go zgodnie ze standardami UX/UI obowiązującymi w Twojej organizacji. Zadbaj o to, aby układ pól, ich etykiety, podpowiedzi, a także walidacje i komunikaty błędów w ramach komponentu były spójne z resztą formularza. Dzięki temu użytkownik nie odczuje, że dana sekcja została „doklejona” z innego miejsca. Korzystaj z mechanizmu **tłumaczeń** dla tekstów statycznych w komponencie, uzupełnij ich klucze i wartości – ułatwi to zarządzanie literałami z poziomu aplikacji. ## Przykład Na poniższych ilustracjach przedstawiono przykład komponentu złożonego o nazwie `demoAdres` oraz sposób jego wykorzystania. Najpierw zaprojektowano komponent złożony zawierający pola adresowe (ulica, miejscowość, kod pocztowy) – stanowi on wzorzec sekcji adresowej:

Ilustracja 7. Zaprojektowany komponent złożony „demoAdres” (sekcja adresowa)

Następnie ten sam komponent `demoAdres` został osadzony trzykrotnie w przykładowym formularzu (np. dla adresu zameldowania, korespondencyjnego oraz adresu miejsca pracy) – dzięki reużyciu jednego artefaktu uzyskujemy trzy sekcje w formularzu bez potrzeby tworzenia trzech zestawów pól osobno:

Ilustracja 8. Wielokrotne użycie komponentu złożonego „demoAdres” w strukturze formularza (osadzony trzykrotnie)

W rezultacie na interfejsie użytkownika formularz wyświetla trzy jednolite sekcje adresowe korzystające z tego samego komponentu złożonego:

Ilustracja 9. Wygląd formularza z wielokrotnie osadzonym komponentem złożonym „demoAdres” (trzy sekcje adresowe)

Powyższy przykład obrazuje, jak komponenty złożone upraszczają tworzenie powtarzalnych części aplikacji – modyfikacja komponentu `demoAdres` (np. dodanie pola "Państwo") automatycznie wprowadzi to pole we wszystkich trzech sekcjach adresowych na formularzu. Dzięki temu zarządzanie rozbudowanymi formularzami staje się łatwiejsze, a wspólne fragmenty aplikacji zachowują spójność we wszystkich miejscach użycia. Wykorzystując powyższe wskazówki i najlepsze praktyki, komponenty złożone Eximee pozwalają efektywnie tworzyć modułowe, łatwe w utrzymaniu aplikacje biznesowe, w których raz zdefiniowane sekcje mogą być używane w wielu procesach i formularzach. Dobre zaprojektowanie komponentów złożonych odwdzięcza się ograniczeniem duplikacji pracy, ujednoliceniem interfejsu oraz szybszym wdrażaniem zmian w przyszłości. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.eximee.com/budowanie-aplikacji/interfejs-uzytkownika/komponenty-rozszerzone/komponenty-zlozone.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.