Cześć!
Stworzenie dokumentacji Word na podstawie repozytorium, czasami wymaga użycia bardziej zaawansowanych funkcji generowania dokumentacji. Dzisiaj omówimy Fragment Template, czyli rozszerzenie funkcji szablonów do generowania dokumentacji.
W tym artykule dowiesz się:
- Czym jest Fragment Template
- Jak stosować Fragment Template
- Jakie możliwości daje zastosowanie Fragment Template w szablonie
Jeżeli nie czytałeś poprzednich wpisów, musisz koniecznie się z nimi zapoznać, aby w pełni zrozumieć treść tego artykułu.
Poniżej link do wpisów.
- Tworzenie szablonu RTF w Enterprise Architect
- Generowanie dokumentacji w Enterprise Architect – podstawy
Zaawansowany szablon!
Generowanie dokumentacji jest często końcowym krokiem tworzenia modeli w Enterprise Architect. Czasami na podstawie struktury pakietów stworzonego modelu, ciężko jest wygenerować dokumentację, dokładnie taką jak potrzebujemy, ponieważ często potrzebujemy np. informacji szczegółowych o innych elementach spoza pakietu. W takim wypadku często zaczynamy stosować nieco bardziej zaawansowane funkcje generatora dokumentacji takie jak filtry, dedykowane zapytania i fragmenty szablonu (Fragment Template ).
Czym jest Fragment Template?
Według definicji ze strony Sparx:
https://sparxsystems.com/
Fragment Template jest dedykowaną częścią raportu i może mieć odmienne własności niż sam szablon (czyli stanowi pod szablon, głównego szablonu).
Brzmi trochę zawile, prawda? Nieco rozwinę tę definicję. Fragment jest częścią szablonu, pozwalający na stworzenie pod szablonów, które posiadają oddzielną logikę, czyli inne zasady pobierania informacji z repozytorium. Jeżeli dalej nie jest to dla Ciebie jasne. To poniżej przygotowałem grafikę, która to obrazuje.
Jakie Fragment Template daje możliwości?
Fragment template ma duży wachlarz funkcjonalności, które możemy wykorzystać, do tworzenia dokumentacji. Są one szersze niż dla samego szablonu.
Korzystając z fragmentów, można zawrzeć w raportach informacje wyodrębnione za pomocą zapytań SQL i skryptów. Można także użyć Template Selektora, aby wywołać inne fragmenty w zależności od typu elementu, którego dotyczy raport. Lista funkcji, które oferuje fragment template jest długa. Poniżej lista najważniejszych funkcji wyszczególnionych przez sparx.
- Normal document Template
- Template Selctor
- Custom SQL
- Custom Scripts
- Document Script
- Custom XML Script
Dostępnych funkcji jest dużo. Pytanie, czy wszystkie są potrzebne? To zależy od tego, jak twoje repozytorium jest zbudowane. Jeżeli struktura repozytorium jest uporządkowana, to zapewne nigdy większości z nich nie użyjesz.
Kiedy stosujemy Fragment Template?
Czy zastosowanie Fragment Template jest zawsze niezbędne? Nie, lecz jest kilka przypadków, kiedy rekomenduje, aby użyć tego rozwiązania, nawet w wypadku prostych szablonów. Przy złożonych szablonach i dużych repozytoriach jest to często niezbędne i inaczej nie da się osiągnąć pożądanego efektu z użyciem wbudowanego narzędzia.
Niezbędne jest to w momencie, kiedy tworzymy złożone szablony. Przykładem może być tu szablon przypadków użycia, gdzie musimy również wyświetlić informację o aktorze na podstawie łączącej relacji przypadeku użycia z aktorem. Nie da się tego zrobić bezpośrednio w szablonie, ponieważ wyświetlimy dodatkowo niechciane informacje, jak np. relacje do wymagań czy innych przypadków użycia. Więc, w tym przypadku niezbędne jest użycie fragmentu i oddzielnej logiki dla filtrów.
Podstawą są dla mnie fragmenty, gdy przygotowuje szablony firmowe. Raz dobrze przygotowany zestaw prostych fragmentów może być wielokrotnie wykorzystywany przez różne osoby i dzięki temu zachowujemy spójność firmową w ramach całej tworzonej dokumentacji.
Przydatną opcją jest skorzystanie z funkcji Template Selector, czyli funkcji, która pozwala nam na wywoływanie innych fragmentów względem określonych elementów pakietu. Użycie tej funkcji pozwala na automatyzacje procesu tworzenia dokumentacji, oraz ograniczamy liczbę tworzonych szablonów.
Praktyczny przykład
Sporo teorii, ale jak ma się ona do praktycznego zastosowania? Zaprezentuję to na dość prostym zadaniu, wykorzystywanym na wielu szkoleniach. Zadanie to pozwoli przećwiczyć osadzanie fragmentów w szablonach dokumentacji i da Ci szablon przydatny w pracy.
Zadanie
Stwórz szablon, który pozwoli na wygenerowanie informacji o aktorze powiązanym przypadkiem użycia.
Rozwiązanie
Zanim zaczniemy planować, sprawdźmy jak wygląda model w repozytorium.
Celem zadania jest wyświetlenie informacji o aktorach powiązanych z przypadkiem użycia. Jak widać, conamniej jeden z przypadków użycia posiada relacje do innych elementów niż aktorzy. Ten przypadek posiada relację, również do wymagań. Przeglądając, resztę repozytorium stwierdzam, że ta zasada dotyczy wszystkich przypadków.
Plan
Na podstawie mojej wiedzy o budowaniu szablonów wiem, że potrzebuję 1 szablonu i 2 fragmentów.
Szablon jest potrzebny, ponieważ muszę wyświetlić pewien zakres danych o przypadku użycia oraz muszę mieć miejsce do osadzenia fragmentu.
Fragment nr 1 pozwoli mi na pobranie wszelkich elementów, będących w relacji z przypadkiem użycia.
We fragmencie nr 2 ustawię filtr, aby wyświetlane były tylko i wyłącznie: elementy o typie actor i osadzę go we Fragmencie nr 1. Do pracy!
Przygotowanie szablonu i fragmentów
Przygotowałem nagranie, w którym przygotowuje i omawiam proces stworzenia szablonu z zadania. Wykonaj zadanie razem z mną!
Podsumowanie
Jak widzisz na podstawie nagrania, przygotowanie i zastosowanie szablonu zawierającego fragmenty nie jest trudne. Pozwala za to na stworzenie zaawansowanych szablonów, które ułatwiają pracę z dokumentacją. Nie należy jednak mylić fragment Template z Model Document. Są to dwie różne funkcjonalności i mają inne zastosowanie w Enterprise Architect. Jeżeli chcesz poznać jak tworzyć zaawansowane szablony dokumentacji, zapraszam na konsultacje oraz do śledzenia bloga.
Biblografia
- Sparx system – Fragment Template (Data dostępu 01.12.2020) https://sparxsystems.com/enterprise_architect_user_guide/14.0/model_publishing/rtf_template_fragments.html
- Zeszyt z notatkami ze szkolenia Enterprise Architect – Wojciech Giers
