Znaczniki

---

Znaczniki są wykorzystywane do oznaczenia, w którym miejscu szablonu dokumentu powinny znaleźć się dane przekazane do dokumentu w polach wskazanych dla danego znacznika. Do szablonu dokumentu możesz przekazać wartości tekstowe, liczbowe, daty, obrazy, treść innych dokumentów, dane potrzebne do wygenerowania wykresu.

1. Odpowiedni znacznik wstaw kliknięciem w odpowiednim miejscu dokumentu, a następnie umieść kursor wewnątrz znacznika i wybierz panel Atrybuty.
2. W oknie atrybutów dla danego znacznika wskaż element danych, o który jest oparty znacznik.
3. Następnie skonfiguruj pozostałe parametry znacznika.

Wersja pełna i skrócona znaczników

Znaczniki mogą posiadać wersję pełną i skróconą. Gdy wstawisz znacznik do dokumentu i posiada on elementy graficzne takie same na początku i na końcu, wówczas jest to wersja pełna znacznika.

Wersja skrócona znacznika występuje wtedy, gdy jest krótki element graficzny zamykający znacznik.

Wersja skrócona znacznika powstaje gdy jest on zawarty w paragrafie.

Często MS Word automatycznie wstawia znacznik w paragraf (na przykład przy użyciu białych znaków zaraz po znaczniku, które nie posiadają swojej reprezentacji graficznej w MS Word).

Znacznik Notka oraz znacznik Podszablon nie mogą być zawarte w paragrafie.

Przy tworzeniu jakiegokolwiek znacznika na początku nowej strony sprawdź czy nowo stworzony znacznik nie jest niepoprawny. Jeśli taka sytuacja zaistniała, najprawdopodobniej MS Word otoczył znacznik paragrafem, co spowoduje błąd walidacji.

Aby naprawić znacznik usuń go bądź cofnij jego wprowadzanie i kliknij klawisz Enter. Następnie wprowadź jeszcze raz oczekiwany znacznik.

Sprawdź także, czy po znaczniku nie ma spacji. Wystarczy, że po znaczniku naciśniesz klawisz Spacja i dopiero Enter i już znacznik nie zadziała poprawnie.

Wersja znacznika ma także znaczenie w przypadku znacznika Iteracja, gdyż znacznik można skonfigurować w ten sposób aby zawartość wewnątrz znacznika była generowana w jednolinijkowej postaci lub jako osobne paragrafy. Więcej o konfiguracji znacznika Iteracja patrz: Iteracje jednolinijkowe lub w paragrafach.

Wartość

Znacznik Wartość pozwala na przekazywanie do dokumentu wartości typu tekstowego, liczbowego oraz daty/czasu.

Znacznik ten zostanie wstawiony do dokumentu po dwukrotnym kliknięciu ze struktury danych pola typu Tekst, Liczba lub Data.

Dla pól typu Liczba i Data, w oknie Atrybuty dla znacznika Wartość w polu Format danych wskaż format w jakim liczba lub data ma zostać wyświetlona w dokumencie.

Formatowanie liczb i daty

W atrybutach znacznika Wartość przy polach liczbowych możesz wybrać odpowiedni format danych. Przykładowo dla wartości kwotowych format stałoprzecinkowy lub procent dla wartości procentowych.

1. Jeżeli chcesz wprowadzić własne ustawienia i inny format możesz to zrobić bezpośrednio wprowadzając dane w polu Format danych. Wszystkie wartości można formatować za pomocą standardowych ciągów formatujących .NET.
2. Zaznacz przycisk ? , który przekieruje na stronę: https://learn.microsoft.com/en-us/dotnet/standard/base-types/formatting-types?redirectedfrom=MSDN na której podane są formatowania dla różnych typów danych w tym dla liczb.
3. Przykładowo jeżeli chcesz zastosować formatowanie dla liczb wyglądające w ten sposób 1 250 000,00 w polu Format danych wprowadź odpowiednie formatowanie zapisane w tej postaci: 0,00.00.

W elemencie danych Data przy wyborze reprezentowania dnia i miesiąca pisemnie (przykład: środa, 28 listopada 2018), informacja na temat języka, w którym będzie ta nazwa reprezentowana, są brane z systemowych ustawień konta użytkownika Windows. Należy ustawić odpowiednią kulturę w systemie. To samo zagadnienie dotyczy formatu liczb i dat reprezentowanych przez ten znacznik (na przykład separator liczb w zależności od języka może być kropką bądź przecinkiem, długi format daty w zależności od ustawień może być wyświetlany z nazwą dnia tygodnia lub bez).

wskazówka

W przypadku dat także można wprowadzić własny format danych.

Lista

Znacznik Lista, podobnie jak znacznik Wartość, umożliwia wstawienie do dokumentu wartości tekstowych, liczbowych oraz dat. W odróżnieniu od znacznika Wartość (za pomocą, którego do dokumentu można przekazać tylko jedną wartość wybranego pola), znacznik Lista używany jest do przekazania do dokumentu kilku wartości dla pola, które zostało wskazane w znaczniku jako element danych.

1. W oknie atrybutów znacznika Lista, w polu Element danych wskaż pole ze struktury danych (Tekst, Liczba lub Data), którego wartości będą powtarzane w dokumencie w obrębie znacznika Lista.
2. Dla liczb i dat dodatkowo ustaw format danych.

Dla liczb:

Waluta (np. 12,00zł), Wartość wykładnicza (np. 1200000E + 001), Stałoprzecinkowa (np. 12,00), Ogólne (np. 12), Liczba (np. 12,00), Procent (np. 12%).

Dla dat:

Krótki format daty, Długi format daty, Krótki format daty i godziny, Długi format daty i godziny, Krótki format ogólny, Długi format ogólny, Miesiąc i dzień, Data i godzina, Format RFC1123, Data i godzina, Krótki format czasu, Długi format czasu, Uniwersalna data i godzina, Uniwersalna pełna data i godzina, Rok i miesiąc.

Układ

1. W sekcji Układ określ w jaki sposób w dokumencie mają być wyświetlone wartości znacznika Lista.
2. Zaznaczenie pola wyboru Nowa linia spowoduje wyświetlanie wartości jedna pod drugą, niezaznaczenie spowoduje wyświetlanie ich obok siebie.
3. W polu Separator wskaż znak (np. przecinek, średnik) jakim rozdzielone mają zostać wartości przekazane do znacznika Lista. Zaznaczenie pola Separator po ostatnim spowoduje, że po ostatniej wartości w znaczniku Lista zostanie także wstawiony separator wskazany w polu Separator powyżej.

Dla konfiguracji z użyciem tylko separatora:

w wygenerowanym dokumencie wartości będą prezentować się w następujący sposób:

Z kolei dla konfiguracji z użyciem separatorów oraz opcji generowania każdego z elementów listy w nowej linii:

w wygenerowanym dokumencie wartości będą prezentować się w następujący sposób:

Iteracja

Znacznik Iteracja jest znacznikiem, który powtarza zawartą wewnątrz niego treść po kolei dla każdego rekordu tabeli/relacji, która została wskazana jako element danych, o który znacznik jest oparty.

Wewnątrz znacznika Iteracja można wprowadzić zarówno tekst, jak i inne znaczniki. Wszystkie znaczniki, które umieszczone są wewnątrz znacznika Iteracja muszą mieć wskazane w swoich atrybutach elementy danych będące polami tabeli/relacji, która jest wskazana jako element danych dla znacznika Iteracja.

Na poniższym przykładzie, znacznik Iteracja został oparty o tabelę INNE_NALEZNOSCI. Wszystkie znaczniki wewnątrz znacznika Iteracja są oparte na polach pochodzących z tabeli INNE_NALEZNOSCI.

W wygenerowanym dokumencie, fragment tekstu znajdujący się wewnątrz znacznika Iteracja zostanie powtórzony dla każdego zestawu danych Nazwa, Kwota, Odsetki przekazanego do dokumentu w tabeli INNE_NALEZNOSCI.

Zagnieżdżone iteracje

Iteracje mogą być zagnieżdżone czyli można wprowadzać jedną iterację w drugą. W obrębie zagnieżdżonego znacznika Iteracja można korzystać ze skalarnych pól z kontekstu "rodzica".

Przykładowo:

Wyświetl obciążenia klienta, czyli wszystkie raty z wszystkich produktów kredytowych jakie posiada.

Struktura danych dokumentu zawiera dane klienta i relacje do produktów klienta oraz rat.

Kolejność wstawiania znaczników jest następująca:

1. Iteracja Kredyty, gdyż chcemy wyświetlić wszystkie kredyty klienta.

2. Iteracja Raty, gdyż chcemy wyświetlić wysokość każdej raty jeżeli te raty występują.

3. Znacznik Wartość @Wysokosc odnośnie kwoty raty.

4. Znacznik Wartość @Rodzaj z tabeli Kredyty odnośnie kredytu. Mimo, iż jesteśmy w kontekście tabeli Raty, możemy sięgnąć "wyżej" i wstawić znacznik dotyczący kredytu.

Iteracje jednolinijkowe lub w paragrafach

Znacznik Iteracja można skonfigurować w ten sposób aby zawartość wewnątrz znacznika była generowana w jednolinijkowej postaci lub jako osobne paragrafy.

Jeżeli chcesz użyć znacznika w paragrafach, wstaw pełny znacznik Iteracja i zaznacz opcję Iteracja w paragrafach. Cała zawartość wewnątrz znacznika zostanie wygenerowana w osobnych paragrafach.

Jeżeli zawartość wewnątrz znacznika Iteracja ma zostać wygenerowana w jednej linijce, wówczas wstaw skrócony znacznik Iteracja i określ opcjonalnie separator. Aby uzyskać skrócony znacznik iteracji dodaj po lub przed znacznikiem tekst lub spację. Wewnątrz skróconego znacznika iteracji nie można stosować podziału linii.

O tym, iż znacznik jest wstawiony w wersji jednolinijkowej lub generacji w paragrafach informuje kolor znacznika i jego pełna wersja lub skrócona wersja. Jeżeli znacznik jest błędnie wstawiony, przykładowo w skróconej wersji i zaznaczoną ma opcję Iteracja w paragrafach, wówczas zostanie wyświetlony komunikat na panelu Walidacja o konieczności poprawnego wstawienia znacznika.

Więcej informacji o specyficznych przypadkach dodawania numeracji i punktorów przy znaczniku Iteracja patrz rozdział: Najlepsze praktyki.

Warunek - Element danych

Znacznik Warunek pozwala na wskazanie w tworzonym szablonie, fragmentu dokumentu (np. tekstu, innych znaczników, tabel, itp.), który ma zostać wyświetlony w wygenerowanym dokumencie (lub pozostać niewyświetlony) w razie spełnienia (lub niespełnienia warunku).

1. Wstaw do dokumentu znacznik Warunek.
2. W oknie Atrybuty wskaż pole typu Wartość logiczna.
3. Warunek domyślnie skonfigurowany jest w ten sposób, że tekst znajdujący się w szablonie dokumentu wewnątrz danego znacznika Warunek zostanie wyświetlony, gdy dla pola logicznego, które jest elementem danych wskazanym dla tego znacznika przekazana zostanie do dokumentu wartość Prawda, lub spełnione zostaną warunki zdefiniowane w formule w edytorze wyrażeń.

W znaczniku Warunek możesz wybrać typ warunku: Element danych lub Formuła.

Element danych

Elementem danych znacznika Warunek jest pole typu Wartość logiczna, które przyjmuje wartości Prawda lub Fałsz. Dla pola tego może zostać także przekazana wartość pusta, wtedy traktowana jest ona przez znacznik Warunek tak samo jak wartość Fałsz. Jako element danych może zostać wskazana także tabela lub relacja ze struktury danych – w tym wypadku warunek uznaje się za spełniony gdy tabela lub relacja będzie zawierała co najmniej jeden element.

Na przykładzie powyżej, zawartość dokumentu będąca wewnątrz znacznika Warunek zostanie wyświetlona w wygenerowanym dokumencie, tylko gdy dla pola logicznego CzyFirma będącego elementem danych dla tego Warunku, do dokumentu podczas generowania przekazana zostanie wartość Prawda. W przypadku, gdy dla pola CzyFirma zostanie przekazana wartość Fałsz, zawartość znacznika Warunek nie zostanie wyświetlona.

wskazówka

Możesz także skonfigurować znacznik w ten sposób, by zachowywał się odwrotnie - wyświetlał swoją zawartość tylko wtedy, gdy dla pola logicznego, o które jest oparty zostanie przekazana do dokumentu wartość Fałsz. Aby znacznik działał w ten właśnie sposób, w oknie Atrybuty dla tego znacznika zaznacz pole Negacja warunku.

Jeżeli dla tego samego warunku wybierzesz opcję Negacja warunku, wówczas zawartość dokumentu będąca wewnątrz znacznika Warunek zostanie wyświetlona w wygenerowanym dokumencie, tylko gdy dla pola logicznego CzyFirma będącego elementem danych dla tego Warunku, do dokumentu podczas generowania przekazana zostanie wartość Fałsz.

W przypadku, gdy dla pola CzyFirma zostanie przekazana wartość Prawda, zawartość znacznika Warunek nie zostanie wyświetlona.

W razie, gdy jako element danych dla znacznika Warunek została wskazana tabela lub relacja, to zawartość znacznika zostanie wyświetlona jeśli w danych przekazanych do dokumentu zostaną przekazane rekordy dla wskazanej tabeli/relacji. Jeśli rekordy takie nie zostaną przekazane, zawartość znacznika nie zostanie wyświetlona.

Warunek - Formuła

1. Wstaw do dokumentu znacznik Warunek.
2. W oknie Atrybuty przejdź do edytora definiowania formuły.
3. Wybierz typ warunku Formuła i wprowadź warunek poniżej w edytorze.
4. Kliknij dwukrotnie na dane pole, wówczas zostanie ono wstawione do edytora.

Jeżeli wybierzesz jako typ warunku Formuła, wówczas zostanie wyświetlony edytor wyrażeń, za pomocą którego można zdefiniować wyrażenie logiczne. Dzięki zastosowaniu tego typu warunku możesz tworzyć rozbudowane wyrażenia logiczne łącząc ze sobą różne elementy wchodzące w skład pojedynczego warunku. Więcej informacji o wyrażeniach i ich definiowaniu patrz: Wyrażenia.

W celu podpowiedzi składni kliknij Ctrl+Spacja.

W powyższym przykładzie zawartość wewnątrz znacznika Warunek zostanie wyświetlona jeżeli klient prowadzi firmę (CzyFirma == true) oraz jeżeli typ prowadzonej działalności to spółka akcyjna (Typ == "Spółka akcyjna"). Przykładowo jeżeli prowadzona działalność to jednoosobowa firma i takie dane zostaną przekazane do dokumentu, wówczas druga część warunku nie zostanie spełniona i tym samym też cały warunek, gdyż operator pomiędzy składowymi to && inaczej "i" czyli oba komponenty warunku muszą być spełnione.

wskazówka

Zakładamy tutaj także, że typ działalności gospodarczej jest w systemie polem słownikowym, dlatego przyrównujemy tutaj wartość pola typ do konkretnej wartości słownikowej, stąd ważne jest aby nie popełnić błędów w zapisie typu: literówki, małe czy duże litery tylko zastosować dokładnie taką nazwę elementu jaka jest zastosowana w słownikach tworzonej aplikacji.

Operatory:

&& - i - jeżeli użyjesz tego operatora pomiędzy składowymi warunku, wszystkie składowe formuły muszą być spełnione,

| - lub - jeżeli użyjesz tego operatora pomiędzy składowymi warunku, wówczas wystarczy, że tylko jeden z elementów formuły zostanie spełniony,

! - zaprzeczenie warunku/negacja - użyj tego znaku przed zdefiniowanym warunkiem, wówczas zawartość warunku zostanie wyświetlona gdy formuła nie będzie spełniona,

== - równe - wprowadzone dane, elementy składowe muszą przyjmować dokładnie taką wartość jak jest wskazana po operatorze == czyli w powyższym przypadku Typ działalności to dokładnie true ,

!= - różne - wprowadzone dane, elementy składowe mogą przyjmować każdą wartość poza tą wskazaną w formule, wówczas warunek jest spełniony.

( ) - nawias używamy do grupowania części składowych formuły.

wskazówka

Definiując warunek poza znacznikiem Iteracja, należy doprecyzować, z którego rekordu tabeli struktury danych pochodzą pola, użyte w wyrażeniu. Zrobić to można za pomocą funkcji wybierania z tabeli, takich jak np. first(), last(), Any(), All()

W poniższym przykładzie zostaną wyświetlone dane pierwszego wierzyciela z tabeli Dane_wierzyciela, którego forma prawna to Spółka akcyjna.

W granicach znacznika Iteracja używamy samych nazw pól bez funkcji wybierania z tabeli, ponieważ zawartość znacznika Iteracja już jest ograniczona do pojedynczego rekordu z tabeli: Typ == "Spółka akcyjna".

Definiowanie warunku w Iteracji

Przy konstruowaniu warunku z użyciem formuły oraz iterowaniu elementów należy pamiętać o poprawnym zdefiniowaniu danych. Jeżeli warunek jest poza iteracją wówczas sprawdzenie, czy określona formuła jest spełniona, wykona się na poziomie całej tabeli. Jeżeli chcemy sprawdzić poszczególne elementy czy spełniają warunek określony formułą, wówczas należy umieścić warunek wewnątrz iteracji.

Dla przykładu:

Wyświetl dane tych klientów, powiązanych z daną polisą, dla której jest on ubezpieczającym.

Prawidłowa kolejność definiowania iteracji i warunku to: Iteracja po tabeli Klient, następnie wewnątrz iteracji warunek sprawdzający czy rola klienta to Ubezpieczający (Rola=="Ubezpieczający"), a następnie znacznik wartości, która ma zostać wyświetlona w przypadku spełnienia warunku.

Dzięki temu, że warunek jest umieszczony wewnątrz iteracji, każdy rekord tabeli Klient zostanie sprawdzony pod kątem spełnienia określonego warunku i wyświetleni zostaną tylko ci klienci, którzy posiadają rolę Ubezpieczający.

W przeciwnym wypadku, gdyby warunek został umieszczony poza iteracją, wówczas sprawdzeniu uległ by tylko jeden wybrany rekord z całej tabeli Klient, wskazany w formule znacznika Warunek (na przykład, pierwszy – first(…), ostatni – last(…), etc.). Przy spełnieniu takiego warunku zawartość iteracji zostanie wygenerowana dla wszystkich rekordów, a w przeciwnym wypadku iteracja nie wygeneruje się wcale. Na przykład, przy warunku first(Klient\Rola) == "Ubezpieczający" jeżeli polisa posiadałaby 3 klientów i pierwszy z nich byłby ubezpieczającym to i tak wyświetleni zostaliby wszyscy trzej klienci.

Obraz

Znacznik Obraz służy do wstawiania do dokumentu obrazów o określonych formatach: bmp, gif, png, jpg.

Elementem danych, o który oparty jest znacznik Obraz jest pole binarne.

Na przykładzie poniżej przedstawiona jest konfiguracja znacznika Obraz. W strukturze danych stworzone zostało pole binarne Podpis, które następnie zostało wskazane jako element danych w atrybutach znacznika Obraz.

1. Rozmiar obrazu w dokumencie można dostosować do swoich potrzeb. W tym celu należy zmienić rozmiar obszaru przeznaczonego dla obrazu (oznaczonego kwadratem w kolorze fioletowym) wewnątrz znacznika Obraz. Można także wybrać opcję Oryginalny rozmiar, wtedy do dokumentu zostanie wstawiony obraz w swoim oryginalnym rozmiarze.
2. W atrybutach znacznika Obraz można także wskazać w polu Podpis pole tekstowe, którym do dokumentu zostanie przekazany w formie tekstowej podpis dla wstawionego obrazka.
3. W przypadku gdyby do znacznika Obraz i pola binarnego nie zostało nic przekazane, wówczas można wypełnić pole Alternatywny tekst czyli to co ma się wyświetlać w miejscu gdzie powinien zostać wyświetlony obraz.
4. Dodatkowo możesz wprowadzić źródło danych dla pola Adres hiperłącza w przypadku, gdyby obraz miał być elementem interaktywnym i przenosić na przekazany adres url.

Dokument

Znacznik Dokument umożliwia wstawienie do szablonu dokumentu treści/zawartości innego dokumentu w formacie docx.

wskazówka

Można wstawić tylko taki dokument, który nie posiada wewnątrz żadnych znaczników. Jeżeli chcesz wstawić dokument ze znacznikami użyj znacznika Podszablon.

Elementem danych, o który oparty jest ten znacznik jest pole binarne.

Poniższy przykład przedstawia konfigurację znacznika Dokument. Najpierw w strukturze danych utworzone zostało pole binarne WarunkiUmowy.

Następnie, pole to zostało wskazane jako element danych dla znacznika Dokument wstawionego w szablonie dokumentu.

W wygenerowanym dokumencie, w miejsce znacznika Dokument zostanie wstawiona cała treść dokumentu docx przekazanego do szablonu dokumentu w polu WarunkiUmowy.

ostrzeżenie

Znacznik Dokument musi być wstawiony w swojej pełnej formie czyli przed i za znacznikiem nie może znajdować się żaden biały znak typu spacja itp.

Podszablon

Znacznik Podszablon umożliwia wstawienie w jego miejsce zawartości innego wcześniej zdefiniowanego szablonu dokumentu zawierającego inne znaczniki.

Znacznik ten wykorzystywany jest przede wszystkim w sytuacji, gdy dany fragment szablonu dokumentu wykorzystywany jest wielokrotnie w różnych dokumentach. W takim przypadku, dany fragment zapisz w oddzielnym dokumencie docx, oraz, gdy jest to potrzebne, stwórz dla niego strukturę danych, wstaw do niego znaczniki i odpowiednio je skonfiguruj. Następnie w innych dokumentach wstaw znacznik Podszablon i w atrybutach znacznika wskaż skonfigurowany wcześniej dokument docx.

ostrzeżenie

Aby podszablon ze znacznikami działał prawidłowo, zarówno dokument będący podszablonem, jak i dokument, do którego wstawiamy podszablon muszą być oparte o tą samą strukturę danych.

Na przykładzie poniżej, w miejscu danych wierzyciela wstawiony został znacznik Podszablon. W atrybutach znacznika został wskazany plik podszablonu, treść którego ma zostać wstawiona w miejsce znacznika Podszablon w momencie generowania wniosku. Zarówno plik podszablonu jak i wniosek są oparte na tej samej strukturze danych. Podczas generowania wniosku, w miejscu znacznika Podszablon zostanie wygenerowana treść pliku podszablonu, w której w miejscu skonfigurowanych znaczników wstawione zostaną dane przesłane do dokumentu.

ostrzeżenie

Znacznik Podszablon musi być wstawiony w osobnym paragrafie/ nowej linii. Po znaczniku nie mogą znajdować się spacje oraz tekst.

Jeżeli używasz podszablonów należy pamiętać, że poszablon dziedziczy style z szablonu głównego. Podobnie nagłówek i stopka także dziedziczone są z szablonu głównego. Więcej o ograniczeniach poszablonu zobacz: Używanie podszablonów.

Symbol

Znacznik Symbol oparty jest na polu typu Wartość logiczna . Znacznik umożliwia skonfigurowanie w jego atrybutach treści lub symbolu, który ma zostać wyświetlony w jego miejscu w zależności od wartości (Prawda, Fałsz czy Wartość pusta) jaka zostanie przekazana dla pola logicznego, o które jest oparty.

Na przykładzie poniżej, w strukturze zostały stworzone pola logiczne w tabeli ZGODY.

Następnie, w treści dokumentu zostały wstawione znaczniki Symbol, które oparte są na stworzonych wcześniej polach. Dla każdego znacznika, jako element danych zostało wskazane pole logiczne, od wartości którego zależeć będzie, co ma zostać wyświetlone w miejscu znacznika. W atrybutach znacznika wpisz tekst (lub symbol) dla wartości Prawda, Fałsz lub dla Wartości nieistniejącej.

W atrybutach znacznika Symbol w polach Tekst dla fałszu, Tekst dla prawdy i Tekst dla nieistniejącej można wpisać zwykły tekst, który ma zostać wyświetlony, a następnie wskazać dla każdego pola czcionkę, która ma zostać dla tego tekstu użyta.

Dla uproszczenia wstawiania symboli możesz wykorzystać opcję Tablica znaków umieszczoną na wstążce VDS. Tablica znaków otwiera okno, w którym można przeglądać czcionki dostępne w Wordzie, wybrać znak do skopiowania, skopiować go, a następnie wkleić w polu Tekst dla fałszu, Tekst dla prawdy lub Tekst dla nieistniejącej. Należy zawsze pamiętać o tym by w polach tych wskazać czcionkę, która wyświetla skopiowany znak.

W wygenerowanym dokumencie, w miejscu znacznika Symbol wyświetlany jest tekst wskazany w polach dla fałszu, prawdy i wartości pustej w zależności od tego czy dla danego pola logicznego została przekazana wartość Prawda, Fałsz czy Wartość pusta.

Podział i Tabela

Znacznik Podział wykorzystywany jest w pracy z tabelą. Pozwala zdefiniować, ile kolumn może mieć tabela.

Szczegóły dotyczące znacznika opisane są w rozdziale Powtarzanie kolumn.

Znacznik Tabela wykorzystywany jest w pracy z tabelą. Pozwala zdefiniować, które kolumny i które wiersze mają być powtarzane w obrębie tabeli.

Szczegóły dotyczące znacznika opisane są w rozdziale Powtarzanie kolumn.

Kod

Znacznik Kod umożliwia wstawianie do wnętrza dokumentu kodów kreskowych określonego rodzaju. Jako element danych, znacznik przyjmuje pole tekstowe, którym do dokumentu musi zostać przekazany tekst w formacie odpowiednim dla wybranego kodu.

Na przykładzie poniżej, w strukturze zostało stworzone pole tekstowe, którym do dokumentu zostanie przekazana treść do wygenerowania kodu w formacie CODE_39 Pole to zostało wskazane jako element danych w atrybutach znacznika Kod.

W wygenerowanym dokumencie w miejscu znacznika zostanie wygenerowany kod kreskowy w formacie wskazanym w atrybutach znacznika.

ostrzeżenie

Aby kod kreskowy został poprawnie wygenerowany, w polu tekstowym do dokumentu musi zostać przekazana wartość tekstowa w formacie wymaganym dla danego kodu.

Poniżej przykład kodu 39 wygenerowanego w dokumencie dla wartości ABC123.

Wykres

Znacznik Wykres umożliwia wstawienie wykresu, który w wygenerowanym dokumencie zostanie uzupełniony danymi przesłanymi do dokumentu.

Generowanie dokumentów wspiera następujące typy wykresów:

1. Słupkowy/kolumnowy,
2. Słupkowy/kolumnowy 3D,
3. Liniowy,
4. Liniowy 3D,
5. Kołowy,
6. Kołowy 3D,
7. Warstwowy,
8. Warstwowy 3D,
9. Punktowy,
10. Giełdowy,
11. Bąbelkowy,
12. Radarowy.

Znacznik Wykres wymaga wskazania dla niego w atrybutach elementu danych typu Dane dla wykresu.

Na przykładzie poniżej, w strukturze danych zostało dodane pole typu Dane dla wykresu. Następnie w dokumencie został wstawiony znacznik Wykres, a pole DaneWykresu zostało wskazane jako element danych dla tego znacznika.

wskazówka

Wykres wstawiony w znaczniku Wykres może być formatowany przy wykorzystaniu wszystkich możliwości edycyjnych Worda.

Aby wykres został poprawnie wygenerowany, do dokumentu w polu typu Dane dla wykresu muszą zostać przekazane dane w formacie JSON. Na przykładzie poniżej podany jest przykład formatu danych przekazanych do wykresu w polu Dane do wykresu i wygenerowany wykres oparty o te dane.

[{'Name':'2016','Categories':
[{'Label':'Samochody czerwone','Value':'60.0'},
{'Label':'Samochody  niebieskie','Value':'40.0'}]},
{'Name':'2017','Categories':
[{'Label':'Kategoria 1','Value':'25.0'},
{'Label':'Kategoria  2','Value':'30.0'}]}]

Notka

Znacznik Notka – Po wygenerowaniu dokumentu, w przeciwieństwie do innych znaczników, pozostaje niezmieniony (dalej jest widoczny jako znacznik) i pozwala na uzupełnienie treści w kolejnych wersjach dokumentu.

Znacznik ten nie wymaga wskazania dla niego w atrybutach elementu danych. Nie ma możliwości korzystania ze znacznika wewnątrz iteracji.

Widok przykładowego dokumentu ze znacznikami, w tym znacznikiem Notką przed wygenerowaniem (lewa strona) i po wygenerowaniu (prawa strona):

Powyżej widać, że ze znaczników Wartość został wygenerowany tekst, natomiast znacznik Notka pozostał niezmieniony.

Hiperłącze

Znacznik umożliwia wstawianie do dokumentu hiperłączy.

W zależności od tego jak skonfigurujesz znacznik, masz wpływ na to jak zostanie wygenerowane hiperłącze.

1. Wstaw znacznik do szablonu dokumentu.
2. W środku znacznika wpisz tekst, który chcesz aby był hiperłączem.
3. W atrybutach znacznika wskaż pole ze struktury danych dokumentu, które jest źródłem danych dla znacznika. Przy tak zdefiniowanym znaczniku tekst tutaj będzie klikalny i będzie odsyłać do adresu, który zostanie przekazany do znacznika poprzez pole AdresLinku.

4. Wstaw kolejny znacznik Hiperłącze i wewnątrz znacznik Wartość. Zarówno dla znacznika Hiperłącze oraz dla znacznika Wartość ustaw ten sam element danych - pole AdresLinku. Przy tak zdefiniowanym znaczniku wszystko co jest wewnątrz znacznika Hiperłącze czyli adres przekazywany przez znacznik Wartość zostanie wygenerowane jako link.

5. Dodaj znacznik Obraz i w atrybutach znacznika wskaż adres hiperłącza poprzez wskazanie pola ze struktury danych dokumentu AdresLinku. Po wygenerowaniu obraz w dokumencie będzie elementem klikalnym i będzie odsyłać na przekazany adres.

ważne

Znacznik Hiperłącze nie może być pusty w środku. Zawsze należy wprowadzić tam tekst, który ma być hiperłączem lub znacznik Wartość, w którym zostanie przekazany adres hiperłącza.

W wygenerowanym dokumencie elementy klikalne/hiperłącza wyglądają następująco:

Jeżeli nie użyjesz żadnego formatowania, wówczas linki wygenerowane zostaną w taki sposób w jaki są zdefiniowane w szablonie dokumentu. Aby hiperłącza wyglądały jak link, sformatuj je odpowiednio poprzez opcje dostępne w MS WORD.

Funkcje zwracające adres url

Po przejściu do archITekt Studio oraz edytora wyrażeń dostępne są funkcje, które zwracają pełny adres url do podanego formularza lub listy.

1. Przejdź do okna edytora wyrażeń i wybierz funkcję GetFormAddress lub GetListAddress. W środku funkcji wskaż formularz lub listę, do której ma nawigować hiperłącze. Elementy serwera wersji znajdziesz na drzewie danych VS w edytorze wyrażeń.

W wygenerowanym dokumencie po kliknięciu w link zostaniesz przekierowany na wskazany formularz/listę.

W przypadku, jeżeli masz szyfrowane adresy url, wówczas skorzystaj z funkcji PrepareWebAppInternalAddress, która szyfruje podany adres url. Przy wykorzystaniu tej funkcji należy przekazać adres do strony w aplikacji webowej, który użytkownik sobie sam stworzył z wykorzystaniem parametru common.publicurl.webui. Funkcja zadba o to, żeby link działał dobrze niezależnie od flagi ustawiającej szyfrowanie URL w aplikacji

1. Jak na poniższym przykładzie wybierz funkcję PrepareWebAppInternalAddress
2. W środku funkcji wskaż z drzewa ConfigKeys parametr common.publicurl.webui

3. Kolejno do adresu dołącz pozostałe elementy czy w tym przypadku wartość stałą /Pages/Documents.aspx?FormId=", następnie formularz/listę lub inny element serwera wersji, na który ma przekierować hiperłącze oraz na końcu kolejny element stały &ElId=-1.

Symbol zastępczy

Znacznik Symbol zastępczy można umieścić tylko wewnątrz znacznika Wartość.

Zawartość znacznika jest generowana tylko wtedy, kiedy wartość pola ze struktury danych, które jest podpięte pod znacznik Wartość będzie puste.

Wewnątrz znacznika Symbol zastępczy:

1. możesz umieścić tekst stały, tekst zostanie wygenerowany z zachowaniem formatowania. W poniższym przypadku, jeżeli pole PESEL będzie puste wówczas zostanie wygenerowany tekst ze znacznika Symbol zastępczy.

2. możesz umieścić tekst stały a dodatkowo do znacznika podpiąć pole ze struktury danych, wówczas tekst stały zastępowany jest wartością z pola, z zachowaniem formatowania. W poniższym przypadku jeżeli wartość pusta będzie w polu PESEL wówczas zostanie wygenerowana wartość z pola TekstZastepczy, które jest źródłem danych dla znacznika Symbol zastępczy.

3. możesz umieścić wewnątrz znacznika Symbol zastępczy znacznik Obraz, wówczas generowany będzie obraz

Na wstążce w sekcji Projektowanie można włączyć/wyłączyć widoczność znaczników oraz znaczników typu Symbol zastępczy. Całkowite wyłączenie reprezentacji graficznej znacznika możesz zrobić poprzez odznaczenie opcji Znaczniki. Natomiast ukrycie zawartości i wizualne zmniejsznie znaczników Symbol zastępczy możesz zrobić poprzez odznaczenie opcji Symbole zastępcze.

HTML

Znacznik umożliwia dodawanie do generowanych dokumentów tekstu sformatowanego przy pomocy rozbudowanej kontrolki Edytor tekstu na formularzu. Z uwagi na to, że kontrolka formatując tekst zapisuje go jako html, znacznik można też wykorzystać do konwersji dowolnego fragmentu kodu HTML na tekst sformatowany w MS Word, PDF czy MHTML, jednak wiąże się to z pewnymi ograniczeniami opisanymi niżej, o których należy pamiętać i mieć je na uwadze.

Znacznik posiada dwa atrybuty:

1. Element danych – podobnie jak w innych znacznikach należy do tego atrybutu podpiąć pole tekstowe ze struktury danych, które przy generowaniu dokumentu zasilane będzie kodem HTML.
2. Typ konwersji – definiuje zachowanie konwertera w przypadku wykrycia jakichkolwiek błędów.

• Dokładny – w przypadku napotkania jakiegokolwiek błędu, przerywana jest konwersja i zgłaszany błąd. Dotyczy to np. niedomkniętego tagu html, błędnej składni, użycie niedozwolonego znacznika i tym podobne.
• Ignoruj błędy konwersji – ignoruje napotkane błędy w składni html i próbuje wygenerować tekst sformatowany najlepiej jak się da. W przypadku błędnych lub niedozwolonych znaczników są one ignorowane. Błąd jest zgłaszany jedynie w przypadku, gdy konwerter zwrócił pusty wynik (wszystkie znaczniki zostały zignorowane lub przekazany html nie renderuje żadnego tekstu).
• Zezwalaj na pusty wynik – analogicznie jak opcja „Ignoruj błędy konwersji”, lecz dodatkowo nie zgłasza błędu gdy wygenerowany tekst jest pusty (konwerter zwrócił pustą wartość, mimo, że dostarczony tekst html nie jest pusty).

ostrzeżenie

Należy pamiętać, że głównym zadaniem funkcjonalności jest przenoszenie formatowania do dokumentu.

Konwersja wykorzystuje istniejące style w dokumencie przy formatowaniu elementów takich jak Nagłówki, cytat, numerowanie czy lista wypunktowana, w związku z czym w zależności od zdefiniowanych styli czy też ich braku, wynik konwersji może się różnić pomiędzy dokumentami, a także skonwertowany do Worda html może się różnić od tego samego html wyrenderowanego w przeglądarce. Różnice mogą obejmować głównie wielkość czcionki i odstępy lub interlinie pomiędzy elementami / paragrafami.

ważne

Konwertowany html umieszczany jest w głównej sekcji dokumentu. Nie ma możliwości umieszczania kodu html w nagłówku oraz w stopce.

Konwersja tekstu sformatowanego w kontrolce Edytor tekstu

Znacznik wspiera wszystkie możliwości formatowania dostępne w kontrolce i przenosi formatowanie jako natywny sformatowany tekst w Wordzie, co pozwala na dalszą edycję dokumentu.

Konwersja własnego kodu HTML do dokumentu

ważne

Z uwagi na złożoność procesu konwersji kodu HTML na tekst sformatowany w dokumencie Word, należy się najpierw upewnić, czy wynik konwersji jest zadowalający i nie występują rozbieżności pomiędzy wynikiem konwersji a dostarczonym kodem HTML, zwłaszcza jeżeli atrybut Typ konwersji jest ustawiony na inny niż Dokładny.

Użycie znacznika pozwala na konwersję dowolnego kodu HTML na obiekty OpenXml rozumiane i natywnie wspierane przez MS Word, wiąże się to jednak z pewnymi ograniczeniami.

Konwersja nie obsługuje następujących znaczników HTML i ich wykorzystanie skutkuje błędem konwersji lub są one ignorowane w zależności od ustawienia atrybutu Typ konwersji:

<button> <head> <input> <script> <select> <style> <textarea> <xml>;

Rozmiar czcionki podany w formie wielkości bezwzględnej (np. font-size: x-large, font-size: small) są mapowane na odpowiednie wartości w Wordzie zgodnie z zasadą poniżej. Jeżeli chcemy precyzyjnie sterować rozmiarem czcionki, należy podawać dokładny rozmiar czcionki w HTML.

1. xx-small 7pt
2. x-small 9pt
3. Small 10pt
4. Medium 12pt
5. large 18pt
6. x-large 24pt
7. xx-large 36pt

Obrazki w formie znacznika <img> nie mogą nawigować do zasobów zewnętrznych (konwerter nie pobiera obrazów z internetu) i zgłasza błąd lub wstawia placeholder w formie szarego tła, w zależności od ustawienia atrybutu Typ konwersji. Możliwe jest jedynie umieszczanie obrazów w formacie base64.

W przypadku:

1. Podpis
2. Nagłówek 1-6
3. Hiperłącze
4. Przypis
5. Bibliografia
6. Cytat

konwerter próbuje przypisać tym elementom odpowiedni styl z dokumentu Word. Jeżeli któregoś z nich nie znajdzie, automatycznie tworzy nowy styl.

Przed konwersją następuje sprawdzenie HTML pod kątem:

1. Zamiana rozmiaru czcionki z formy bezwzględnej na liczbowy
2. Dodawanie tagów <body> oraz <html> jeżeli nie ma
3. Dodanie tagu <!DOCTYPE> na początku dokumentu jeżeli nie ma

Style zdefiniowane w zewnętrznych plikach .css oraz znacznikach <style> są ignorowane. Dotyczy to także zmiennych CSS. W takich przypadkach style należy przenieść do każdego znacznika, którego dotyczy.

Możliwe jest także zastosowanie istniejącego stylu z dokumentu. W tym celu należy w danym znaczniku dodać właściwość class z nazwą stylu jako parametr. Można podać kilka nazw styli oddzielonych spacjami, wówczas konwerter szuka po kolei każdego ze styli i stosuje pierwszy, który istnieje w dokumencie.

1. Np. dla elementu <p class="My\_Style Normal"> konwerter próbuje w dokumencie znaleźć styl My_Style i go zastosować, a jeżeli nie znajdzie, to Normal.

Konwerter opiera się na standardzie OpenXML, który nie posiada bezpośrednich odpowiedników dla nowoczesnych modułów CSS Layout (Flexbox oraz CSS Grid). W związku z tym właściwości display: flex oraz display: grid są ignorowane. Zaleca się stosowanie tradycyjnych układów opartych na tabelach <table> lub blokach, aby zachować strukturę dokumentu w formacie .docx.

1. Można tworzyć automatycznie przypisy na dole strony za pomocą znacznika <abbr>

Usuwanie, zaznaczanie znaczników

Znaczniki możesz usuwać korzystając z klawiszy Delete lub Backspace a także z opcji programu Word.

W przypadku znacznika iteracja należy mieć na uwadze, iż wszystko co jest wewnątrz znacznika również zostanie usunięte (przykładowo inne znaczniki, tekst itp).

1. W takim przypadku kliknij w znacznik iteracja (lub zaznacz znacznik) i wybierz opcję Zlokalizuj.
2. Aktywuj kartę Znaczniki. Znacznik iteracja, który zaznaczyłeś w dokumencie jest podświetlony na karcie Znaczniki.
3. Kliknij prawym i wybierz z menu Usuń znacznik.
4. W ten sposób zostanie usunięty znacznik Iteracja a jego zawartość pozostanie bez zmian.

Jeżeli wewnątrz iteracji lub warunku znajduje się dużo znaczników precyzyjne zaznaczanie znaczników jest możliwe:

1. za pomocą klawiatury (przechodzenie po tekście strzałkami w lewo i prawo)

2. za pomocą panelu Znaczniki. Kliknij dwukrotnie w znacznik, wówczas kursor zostanie umieszczony wewnątrz znacznika na dokumencie. Dzięki temu masz pewność, że jesteś w kontekście odpowiedniego znacznika.

Zobacz również

Walidacja dokumentu

Sprawdzanie poprawności styli – znacznik Podszablon

Lokalizacja znaczników w dokumencie