Przypadki uzycia czy sposób tworzenia warunków (placeholderów) w szablonach dokumentów Word dla generatora dokumentów Fintin poprzez wtyczkę w MS Word.
Składnia warunków jest bardzo czuła na zmiany oraz nie akceptuje kazdych warunków (np. z JavaScript). Należy dokładnie przestrzegać przedstawionych formatów, gdyż nawet drobne modyfikacje mogą spowodować nieprawidłowe działanie generatora, a co za tym idzie bład przy generowaniu wydruku.
Podstawowe funkcjonalności
Iterowanie przez listy
Gdy chcesz wyświetlić dane z listy obiektów, użyj sekcji rozpoczynającej się od {#nazwaListy} i kończącej się {/nazwaListy}. Wewnątrz tej sekcji możesz odwoływać się do pól każdego obiektu z listy.
Przykład podstawowy:
{#supplier.addresses}
{city}
{/supplier.addresses}
Opis: Ten kod przechodzi przez wszystkie adresy dostawcy i wyświetla nazwę miasta dla każdego z nich. Jeśli dostawca ma 3 adresy, w dokumencie pojawią się 3 nazwy miast, każda w nowej linii.
Przykład zaawansowany z zagnieżdżonymi listami:
{#account.representatives}
{#addresses [loopOver: "content"]}
{#type.key=="HQ"}
{city}
{/}
{/addresses}
{/account.representatives}
Opis: Ten kod przechodzi przez wszystkich przedstawicieli konta, następnie przez ich adresy i wyświetla miasto tylko dla tych adresów, które są oznaczone jako siedziba główna (HQ). Praktycznie - jeśli firma ma kilku przedstawicieli w różnych miastach, pokaże tylko miasta gdzie są siedziby główne.
Warunkowe wyświetlanie danych
Aby warunkowo wyświetlać zawartość, użyj formatu {#warunek}zawartość{/}. Fragment zostanie wyświetlony tylko wtedy, gdy warunek zostanie spełniony.
Przykład:
{#type.key=="S"}
{city}
{/}
Opis: Ten kod sprawdza czy typ adresu to "S" (np. adres służbowy) i tylko wtedy wyświetla nazwę miasta. Jeśli adres nie jest typu "S", miasto w ogóle się nie pojawi w dokumencie.
Warunki ternarne (alternatywne wyświetlanie)
Do wyświetlania jednej z dwóch wartości w zależności od warunku użyj składni: {warunek ? wartośćJeśliTrue : wartośćJeśliFalse}
Przykłady:
{application.isPartnerInsurance==true ? "Tak" : "Nie"}
Opis: Sprawdza czy we wniosku wybrano ubezpieczenie partnera. Jeśli tak, wyświetli "Tak", jeśli nie - wyświetli "Nie". Przydatne do jasnego oznaczania wyboru klienta w dokumencie.
{application.assets.length > 1 ? "PRZEDMIOTY" : "PRZEDMIOT"}
Opis Sprawdza ile przedmiotów jest we wniosku. Jeśli więcej niż jeden, wyświetli "PRZEDMIOTY" (liczba mnoga), jeśli jeden lub zero - wyświetli "PRZEDMIOT" (liczba pojedyncza). Zapewnia poprawną gramatykę w dokumencie.
Zaawansowane operacje
Wyłuskiwanie danych z filtrami
Do złożonego filtrowania i pobierania specyficznych danych użyj wyrażenia expression:
Wyłuskiwanie adresu siedziby:
{#case.application.parties [expression: "value.filter(el => (el.roles || []).find(r => r.key == 'APPLICANT')).flatMap(p => p.addresses || []).filter(address => (address.types || []).find(type => type.key == 'HQ'))"]}{prefix} {street} {buildingNumber}{premises ? '/' + premises : ''}, {postcode} {city}, {country.value}{/}
Opis: Ten kod znajduje wnioskodawcę w sprawie, następnie spośród wszystkich jego adresów wybiera tylko adres siedziby głównej (HQ) i wyświetla go w pełnym formacie z ulicą, numerem budynku, kodem pocztowym, miastem i krajem. Jeśli jest lokal, dodaje go po ukośniku. Przydatne do automatycznego wstawiania adresu firmy do umów.
Złożone warunki z wieloma filtrami
Filtrowanie z wieloma warunkami:
{#case.application.parties [expression: "value.filter(el =>(el.roles || []).find(r => r.key == 'ASSIGNEE'))"]}
{#personInCompany [expression: "value.filter(el =>(el.roles || []).find(r => r.key == 'RE'))"]}
{fullName}
{/personInCompany}
{/case.application.parties}
Opis: Ten kod znajduje cesjonariusza (osobę/firmę na którą przeniesiono prawa) w sprawie, a następnie spośród osób w tej firmie wybiera przedstawiciela prawnego (RE) i wyświetla jego pełne imię i nazwisko. Przydatne w dokumentach gdzie trzeba wskazać konkretną osobę uprawnioną do działania.
Warunek z sprawdzaniem formy prawnej:
{#case.application.parties [expression: "value.filter(el =>(el.roles || []).find(r => r.key == 'ASSIGNEE') && el.legalForm?.key == '001')"]}
{fullName}
{/case.application.parties}
Opis: Ten kod znajduje cesjonariusza, ale tylko jeśli ma konkretną formę prawną (kod '001' - np. spółka z o.o.) i wyświetla jego pełną nazwę. Używane gdy różne formy prawne wymagają różnego traktowania w dokumentach.
Operacje na danych
Formatowanie liczb
Podstawowe formatowanie liczb:
{calculation.ownContribution.net | numberFormat}
Opis: Ten kod pobiera kwotę wkładu własnego (netto) z kalkulacji i formatuje ją zgodnie z polskimi standardami - dodaje spacje jako separatory tysięcy (np. 123 456,78 zł). Przydatne do wyświetlania kwot pieniężnych w czytelnej formie.
Zaawansowane formatowanie z separatorami tysięcy:
{case.application.offer.mileage [module: "Script", function: "evaluate", expression: "Number.isInteger(value) ? value.toLocaleString('pl-PL').replace(/\\u00A0/g, ' ') : (Math.floor(value).toLocaleString('pl-PL').replace(/\\u00A0/g, ' ') + '.' + Math.round((value - Math.floor(value)) * 100).toString().padStart(2, '0'))" ]}
Opis: Ten kod formatuje przebieg pojazdu z oferty. Jeśli przebieg to liczba całkowita (np. 50000), wyświetla ją z separatorami tysięcy (50 000). Jeśli ma część dziesiętną, wyświetla ją z dokładnością do 2 miejsc po przecinku (np. 50 000.25). Zapewnia jednolite formatowanie przebiegów w dokumentach.
Operacje matematyczne
Sumowanie wartości z listy:
{case.application.parties [module: "Script", function: "evaluate", expression: "(value || []).map(el => el.invoiceNetValue || 0).reduce((a, b) => a + b, 0)" ]}
Opis: Ten kod przechodzi przez wszystkich uczestników sprawy, pobiera wartość netto ich faktur i sumuje je. Jeśli ktoś nie ma faktury, traktuje jako 0. Wynik to łączna wartość wszystkich faktur netto. Przydatne do kalkulacji całkowitych kosztów w sprawie.
Zarządzanie zmiennymi
Ustawianie zmiennych lokalnych
Możesz tworzyć zmienne lokalne do przechowywania danych, które będą używane w różnych miejscach szablonu:
Ustawianie zmiennej:
{case [module: "Script", function: "set", variable: "partiesUsers", expression: "value.parties"]}
Opis: Ten kod tworzy zmienną "partiesUsers" i zapisuje w niej wszystkich uczestników sprawy. Przydatne gdy chcesz wielokrotnie odwoływać się do tej samej listy uczestników w różnych miejscach dokumentu, bez konieczności każdorazowego pobierania danych.
Używanie zmiennej:
{#partiesUsers [expression: "value?.filter(el => el?.role == 'APPLICANT')"]}{firstName}{/partiesUsers}
Opis: Ten kod używa wcześniej zapisanej zmiennej "partiesUsers", filtruje tylko wnioskodawców i wyświetla ich imiona. Dzięki użyciu zmiennej kod jest bardziej czytelny i wydajny.
Przykład praktyczny z liczeniem poręczycieli:
{case [module: "Script", function: "set", variable: "guarantorNumber", expression: "(value.application.parties || []).filter(el => (el.roles || []).some(r => r.key == 'GUARANTOR')).length"]}
{#guarantorNumber=="ONLINE"}Nie ma poręczyciela{/guarantorNumber}
{#guarantorNumber==1}Jest jeden poręczyciel{/guarantorNumber}
{#guarantorNumber==2}Jest dwóch poręczycieli{/guarantorNumber}
Opis: Ten kod najpierw liczy ile jest poręczycieli w sprawie i zapisuje liczbę do zmiennej. Następnie sprawdza tę liczbę i wyświetla odpowiedni komunikat: "Nie ma poręczyciela", "Jest jeden poręczyciel" lub "Jest dwóch poręczycieli". Przydatne do automatycznego generowania opisów stanu sprawy.
Operacje na tablicach i obiektach
Zapisywanie stringów do tablicy:
{attachments [module: "Script", function: "set", variable: "attachmentsData", expression: "value.map(num => Object.fromEntries([['key', num]]))"]}
{#attachmentsData}{key}{/attachmentsData}
Opis: Ten kod przekształca listę załączników w specjalną strukturę danych, gdzie każdy załącznik ma pole "key". Następnie przechodzi przez tę strukturę i wyświetla wartości. Przydatne do tworzenia list załączników w określonym formacie.
Zapisywanie obiektów do zmiennej:
{accounts [module: "Script", function: "set", variable: "account", expression: "value?.[0]"]}
Opis: Ten kod pobiera pierwszy element z listy kont i zapisuje go do zmiennej "account". Przydatne gdy sprawie przypisane jest kilka kont, ale w dokumencie potrzebujesz odwołać się tylko do pierwszego (głównego) konta.
Specjalne funkcjonalności
Generowanie kodów kreskowych
System obsługuje generowanie kodów kreskowych na podstawie danych z modelu:
Z modelu: barcodeNumber
Kodowanie: code-2of5 interleaved
Opis: Ta funkcjonalność pozwala na automatyczne wstawienie kodu kreskowego do dokumentu na podstawie numeru zapisanego w sprawie. Kod kreskowy jest generowany w standardzie "code-2of5 interleaved", który jest często używany w branży logistycznej i magazynowej. Przydatne do dokumentów wysyłkowych, etykiet czy faktur.
Najlepsze praktyki
- Zachowaj dokładną składnię - generator jest bardzo czuły na błędy składniowe
- Testuj warunki - zawsze sprawdź działanie warunków na przykładowych danych
- Używaj zmiennych - dla złożonych operacji zapisuj wyniki do zmiennych lokalnych
- Dokumentuj szablony - opisuj skomplikowane warunki komentarzami w dokumencie
- Sprawdzaj typy danych - upewnij się, że porównujesz odpowiednie typy wartości
- Ukrywaj warunki w dokumencie - zaznacz tekst z warunkiem i użyj skrótu Ctrl+D (Windows) lub Cmd+D (Mac), a następnie wybierz opcję "Ukryj". Dzięki temu warunki nie będą widoczne w finalnym dokumencie, ale będą działać podczas generowania
- Pisz warunki w jednej linii - unikaj używania klawisza Enter wewnątrz warunków. Cały warunek powinien być napisany w jednej linii bez podziałów, aby system mógł go poprawnie zinterpretować
Przed implementacją złożonych warunków w szablonie, przetestuj je na mniejszych fragmentach danych, aby upewnić się, że działają prawidłowo.