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.
Tworzenie komponentu
Aby utworzyć nowy komponent złożony lub edytować istniejący, należy:
W Eximee Designer przejść do modułu Biblioteka i wybrać zakładkę Komponenty złożone,
w tym widoku wyświetlana jest lista wszystkich dostępnych komponentów złożonych w repozytorium wraz z opcjami zarządzania,
Z poziomu listy można:
utworzyć nowy komponent (przycisk Dodaj komponent złożony),
skopiować lub edytować istniejący artefakt korzystając z rozwijanego menu (trzy kropki)
przejrzeć historię wersji komponentu korzystając z rozwijanego menu (trzy kropki)
Wybrać opcję dodawania nowego komponentu złożonego
pojawia się okno tworzenia artefaktu, w którym podajemy nazwę komponentu oraz lokalizację (folder) w drzewie projektu, analogicznie jak przy tworzeniu nowego formularza.
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.
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.
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.
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.
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.
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:
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:
W rezultacie na interfejsie użytkownika formularz wyświetla trzy jednolite sekcje adresowe korzystające z tego samego komponentu złożonego:
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.
Last updated
Was this helpful?