Edycja szablonów RTF

Program Sparx Enterprise Architect jest instalowany wraz z kolekcją predefiniowanych szablonów RTF. Dostęp do tych raportów jest możliwy z poziomu okna Resources. Szablony te są zebrane w grupę o nazwie System. Raport wygenerowany przy użyciu predefiniowanego szablonu jest łatwo rozpoznawalny z uwagi na zastosowanie specyficznych styli paragrafów. Chociażby wszystkie nagłówki mają odcienie koloru niebieskiego.
Taki styl może nie odpowiadać każdemu, w związku z tym sugeruję, aby traktować je jedynie jako przykłady możliwych konstrukcji, a dla celów projektowych opracować na ich podstawie własne szablony.
Jest to o tyle istotne, że predefiniowane szablony zawierają bardzo dużą ilość cech, tabel oraz pól, które mogą być nadmiarowe. Brak doświadczenia w edycji szablonów bądź po prostu ludzka niechęć do wyrzucania czegokolwiek sprawia, że wygenerowany raport przy użyciu standardowego szablonu staje się nieczytelny z uwagi na przeładowanie niepotrzebnymi informacjami.
W jednym z projektów spotkałem się z raportem wygenerowanym przy użyciu standardowego szablonu, który liczył blisko 200 stron. Ważne informacje były tak rzadko rozsiane, że samo przewijanie stawało się nieprzyjemne, a jak się pomyśli jeszcze o tym, że taki raport jest drukowany w kilku egzemplarzach, to aż żal lasów. Ten raport zamiast 200 stron bez problemu zmieściłby się na 20-30 stronach.

Edytor szablonów RTF

Do edycji szablonów RTF służy narzędzie o nazwie Document Template Designer (Edytor szablonów RTF). Okno edytora szablonów składa się z dwóch podstawowych części:

• Sections,
• Content.

Powyższy rysunek prezentuje przykład samodzielnie opracowanego szablonu o nazwie DA_LinkedDocumentH1. Zastosowanie takiego szablonu umożliwia umieszczenie w raporcie złożonym treści statycznych zapisanych w postaci Linked Document przypisanych do elementów.

Znaczniki sekcji i pól

W części Sections widoczne są zaznaczone checkboxy przy Package oraz Element (pozostałe checkboxy są niewidoczne na tym zrzucie ekranu). Wybór określonej sekcji poprzez zaznaczenie checkboxa powoduje wstawienie w głównym oknie (Content) odpowiednich znaczników.

Przykładowe znaczniki dla sekcji Package pokazuje poniższy rysunek. 

Po wstawieniu takiego znacznika należy usunąć podpowiedź, czyli tekst right-click-to-insert-Package-field(s). A zamiast tego umieścić wybrane pola opisujące określoną sekcję. Zakres pól zależy od kontekstu sekcji. Dostępny jest przy użyciu menu kontekstowego po kliknięciu prawym przyciskiem myszy w aktualnej sekcji.

Znaczniki pól są prezentowane jako tekst objęty klamrami. W powyższym przykładzie w miejscu, gdzie znajduje się pole {Pkg.Name} zostanie umieszczona nazwa pakietu.

Kolejność sekcji w raporcie determinowana jest kolejnością poszczególnych pozycji w części Sections. Gdy zachodzi potrzeba zmiany tej kolejności należy posłużyć się przyciskami w kształcie dłoni skierowanej w dół lub w górę. 

Może to być przydatne na przykład, gdy w szablonie dla modelu użycia chcemy uporządkować opis przypadku użycia w następującej kolejności:

• warunki początkowe - sekcja Constraint-Pre
• scenariusze przypadku użycia - sekcja Scenario
• warunki końcowe - sekcja Constraint-Post

Aby to osiągnąć konieczne jest przesunięcie sekcji Constraint-Post poniżej sekcji Scenario.

Szczególnymi sekcjami są:

• Child packages,
• Child elements.

Pakiety i elementy w strukturze modelu mogą być dowolnie zagnieżdżane. Umieszczenie wyżej wymienionych sekcji w szablonie umożliwia iteracyjne przejście przez podrzędne pakiety (elementy) i uwzględnienie ich w raporcie. 

W przypadku, gdy sekcja taka jest pusta, tzn. nie zawiera żadnych znaczników pól oraz żadnych znaków (w tym białych znaków), wówczas do zaraportowania podrzędnego pakietu (elementu) zostanie zastosowana zawartość sekcji dotycząca pakietu (elementu) nadrzędnego. Jeśli jednak chcemy w inny sposób opisać w raporcie cechy podrzędnych pakietów (elementów), wówczas możemy wypełnić sekcję Child packages lub Child elements.

Formatowanie tekstu oraz style

Tekst w raporcie może być formatowany z wykorzystaniem wszystkich możliwości opisanych w specyfikacji formatu RTF. Istotne jest odpowiednie zdefiniowanie styli paragrafów, dzięki czemu treść dokumentu może być prezentowana w spójny sposób. Każdemu stylowi można przypisać między rodzaj czcionki, wielkość czcionki, kolor, pogrubienie, pochylenie, styl numerowania itp.

Każdy nowy szablon wyposażony jest w zestaw styli zdefiniowanych w pliku normal.rtf, który instalowany jest wraz z programem w lokalizacji %APPDATA%\Roaming\Sparx Systems\EA\RTF Templates\. W przypadku, gdy wykorzystujemy mechanizm Virtual Reports, wówczas szczególnie istotną kwestią jest to, aby wszystkie szablony, z których składa się finalny dokument posiadały te same zestawy styli. Aby to zapewnić należy zdefiniować style w pliku normal.rtf. Można to osiągnąć edytując ten plik w programie MS Word lub Wordpad. Aby zaktualizować style w istniejących już szablonach można skorzystać z funkcji Update Styles (menu kontekstowe w szablonie RTF: File -> Update Styles).

Edycja stylu w edytorze szablonów RTF została opracowana w niekonewencjonalny sposób. Po wyborze z menu kontekstowego opcji Edit -> Edit Style pojawia się okno dialogowe, w którym należy wybrać z listy styl, którego definicję chcemy zmienić.

Po naciśnięciu przycisku OK następuje powrót do normalnej edycji, jednakże program znajduje się w tle w trybie zmiany szablonu. Zmiany atrybutów takich jak rodzaj czcionki, jej wielkość czy kolor zostaną zapisane w definicji stylu. Zakończenie edycji stylu następuje poprzez kliknięcie (umieszczenie kursora) w dowolnym miejscu pola edycyjnego lub ponowne wywołanie opcji Edit Style z menu kontekstowego. Niestety taki sposób wychodzenia z funkcji edycji stylu sprawia, że przypadkowe kliknięcie w obszarze edycyjnym skutkuje potrzebą kolejnej iteracji.

Numerowanie sekcji

Opracowanie złożonych dokumentów często wymaga numerowania sekcji. Treść generowana w formie raportów RTF może być opatrzona numerowanymi nagłówkami wg następującego schematu.

Aby to osiągnąć należy zdefiniować:

• Numbering List - menu Edit -> List and Overrides -> Create List Item...,
• List Override - menu Edit -> List and Overrides -> Create List Override...

Zgodnie ze specyfikacją formatu RTF Numbering List stanowi tylko i wyłącznie definicję stylu numerowania lub wypunktowania i nie jest bezpośrednio stosowany w stylu paragrafu. Do zastosowania Numbering List wykorzystywany jest List Override, który wskazuje na określony Numbering List, a identyfikator List Override przypisywany jest określonym stylom.

List Override może być przypisany:

• Do stylu paragrafu - menu Edit -> Edit Style,
• Do konkretnego paragrafu - menu Paragraph -> List Numbering.

Jeśli w raporcie uwzględnione są pakiety (elementy) podrzędne (child packages lub child elements) oraz styl paragrafu zawiera definicję numerowania, wówczas pakiety (elementy) podrzędne są numerowane przy zastosowaniu podrzędnych poziomów numerowania. Dzięki temu poziomy numerowania w raporcie odpowiadają strukturze zagnieżdżonych pakietów (elementów) w modelu.

Tabele

Zawartość całego raportu lub jego wybranych sekcji może być prezentowana w formie tabelarycznej. Odpowiednie formatowanie tabel w edytorze szablonów RTF jest mniej intuicyjne niż w zewnętrznych edytorach tekstu, takich jak MS Word. W związku z tym zalecane jest przygotowanie szablonu tabeli w MS Word i skopiowanie go do edytora szablonów RTF.

Przed skopiowaniem szablonu zalecane jest ustawienie stałej szerokości kolumn. W MS Word należy w tym celu zaznaczyć całą tabelę, a następnie wybrać z menu MS Word opcję:  Layout -> AutoFit -> Fixed Column Width.

W EA User Guide taka wskazówka nie jest podawana wprost. W historii zmian programu Enterprise Architect można znaleźć informacje o tym, że problem nieprawidłowego interpretowania szerokości kolumn został poprawiony, ale mimo to występuje nadal. Aby było jeszcze ciekawiej, gdy po żmudnym ustawieniu szerokości kolumn w edytorze i zapisaniu zmian, wyświetlimy szablon ponownie okazuje się, że tabela wygląda jeszcze gorzej niż na początku edycji. Zatem, gdy tabela wklejona z MS Word do edytora szablonów "rozjeżdża się", rozwiązaniem pozostaje stała szerokość kolumn w MS Word. 

Dzięki tej operacji możemy być pewni, że tabela zostanie poprawnie wygenerowana w finalnym dokumencie.

Poniższy rysunek prezentuje przykładową tabelę, która została umieszczona w sekcji Element. W raporcie wygenerowanym w oparciu o taki szablon dla każdego elementu w wybranym pakiecie zostaną umieszczone: 

• Wartość pola Alias elementu,
• Wartość pola Name elementu,
• Wartość pola Notes elementu.

Jeśli pomiędzy tabelą a końcem sekcji znajduje się jakiś znak (na przykład znak końca linii - jak w tym przykładzie), wówczas dla każdego elementu zostanie wygenerowana osobna tabela. Tabele te będą rozdzielone od siebie tymi znakami.

Usunięcie znaku końca linii sprawia, że wszystkie elementy znajdą się w jednej wspólnej tabeli.

Tabela w powyższym przykładzie posiada również wiersz nagłówkowy, w którym znajdują się opisy pól (ID, Nazwa, Opis). Jeśli wiersz ten zostanie oznaczony jako nagłówkowy (poprzez zaznaczenie wiersza i wybór opcji z menu kontekstowego Table -> Header Row), wówczas zostanie on wygenerowany tylko jednokrotnie i posłuży do opisu jednej wspólnej tabeli zawierających opis wszystkich elementów z danego pakietu.

Domyślna tabela tworzona w edytorze RTF nie posiada żadnych obramowań. Obramowanie określa się poprzez zaznaczenie całej tabeli, a następnie wybór z menu kontekstowego opcji Table -> Cell Border Width. Aby ustawić zwykłą szerokość obramowań, należy w oknie, które zostanie wyświetlone ustawić wartości takie, jak pokazano na poniższym rysunku.

Istotne jest wstawienie wartości 20 w polu Cell Text Margin (Twips). Obramowanie nie pojawi się, gdy wartość ta pozostanie nieokreślona.

Oprócz zwykłego zastosowania, raport w formie tabelarycznej może również posłużyć jako proste rozwiązanie służące do eksportu danych do arkusza MS Excel. Wystarczy zaznaczyć całą tabelę w wygenerowanym raporcie i wkleić ją do otwartego arkusza MS Excel. Dzięki temu możliwe będzie przeprowadzenie analizy danych pochodzących z modelu EA, takich jak na przykład sumowanie określonych wartości (liczba serwerów, liczba procesorów, sumaryczna pojemność pamięci itp.).

Wartości Tagged Value

Charakterystyka określonych elementów, której nie sposób opisać za pomocą standardowych cech może być opisana poprzez atrybuty typu Tagged Value. Mogą one być przypisywane do:

• Package,
• Element,
• Connector,
• Attribute,
• Operation,
• External Requirement.

Nazwy i wartości tych atrybutów można umieszczać w dowolnych miejscach sekcji dokumentu wykorzystując pole o nazwie valueOf. 

Poniższy rysunek przedstawia sytuację, gdy do opisu elementów dołożono kolumnę o nazwie Źródło. Każdy z elementów w pakiecie posiada przypisane tagged value o nazwie Źródło. Po wyborze z menu kontekstowego Insert Field -> valueOf pojawia się okno o nazwie Enter the Name of the Tagged Value. 

Po wpisaniu w tym oknie nazwy tagged value w szablonie umieszczane jest nowe pole: 

W raporcie w tym miejscu zostaną umieszczone wartości tego atrybutu dla każdego elementu. Jeśli element posiada więcej niż jeden tagged value o tej nazwie, wówczas zostaną zaraportowane wszystkie wartości oddzielone od siebie przecinkami.

Diagramy

Aby umieścić diagram w raporcie należy w edytorze szablonów RTF zaznaczyć sekcję Diagram. W szablonie zostaną wówczas umieszczone odpowiednie znaczniki.

Pomiędzy tymi znacznikami należy wstawić odpowiednie pola, tak jak to pokazano na powyższym rysunku. Najczęściej wykorzystywane pola to:

• Diagram.DiagramImg - w tym miejscu zostanie wstawiony plik graficzny,
• Diagram.Figure - numer kolejny diagramu,
• Diagram.Name - nazwa diagramu.

Diagramy są odpowiednio skalowane, aby zmieściły się na stronie. Jednakże w przypadku dużych diagramów może zaistnieć potrzeba podzielenia diagramu na kilka stron, aby zachować większą czytelność. W tym celu w oknie Properties diagramu należy zaznaczyć opcję Divide Diagram into Multiple Pages.

Po naciśnięciu przycisku Advanced dla długiego diagramu, np. zawierającego diagram sekwencji należy ustawić Custom oraz zwiększyć wartość w polu Pages tall.

Efektem będzie wówczas rozbicie diagramu na dwie osobne grafiki umieszczone na dwóch kolejnych stronach dokumentu, tak jak to pokazano na poniższym rysunku.

Niestety mimo tych zabiegów czytelność diagramów może nie być zadowalająca. W takim przypadku należy działać w dwóch obszarach: po pierwsze zdefiniować zasady projektowe tak, aby ograniczyć liczbę elementów na diagramie, a po drugie eksperymentować z wartościami wyżej wymienionych opcji.