Znaczniki rodzaju Zestawienie służą do umieszczania w treści generowanej z szablonu wielu rekordów w formie tabeli lub listy.

Mogą być wykorzystywane między innymi w:

• pismach,
• wiadomościach e-mail,
• generowanych plikach,
• wiadomościach tekstowych.

W miejsce pojedynczego znacznika program może wstawić dowolną liczbę wierszy zawierających dane obiektów wskazanej klasy.

1.1. Przykładowe zastosowania #

Znacznik rodzaju Zestawienie może służyć na przykład do umieszczenia w dokumencie:

• listy faktur kontrahenta,
• pozycji oferty handlowej,
• listy produktów,
• otwartych zleceń serwisowych,
• innych zestawień rekordów spełniających określone warunki.

2. Powiązanie zestawienia z obiektem szablonu #

Obiekty wyświetlane przez znacznik rodzaju Zestawienie mogą, ale nie muszą, być powiązane z obiektem, w kontekście którego generowany jest cały szablon.

2.1. Przykład zestawienia faktur kontrahenta #

Załóżmy, że szablon jest powiązany z klasą Kontrahent i jest używany podczas redagowania pisma dotyczącego konkretnego kontrahenta.

Znacznik rodzaju Zestawienie może w takim przypadku prezentować obiekty klasy Faktura.

Jeżeli zastosujemy odpowiednie filtrowanie, zestawienie może zawierać wyłącznie faktury należące do kontrahenta, dla którego aktualnie generowany jest dokument.

Możliwe jest również przygotowanie zestawienia niezależnego od bieżącego obiektu szablonu.

3. Tworzenie znacznika rodzaju Zestawienie #

Po dodaniu nowego znacznika i wybraniu rodzaju Zestawienie należy skonfigurować jego podstawowe parametry.

3.1. Wybór klasy obiektów zestawienia #

Najważniejszym i obowiązkowym ustawieniem jest pole:

Obiekty w zestawieniu

W tym polu wskazuje się klasę obiektów, których rekordy mają być prezentowane przez znacznik.

Przykładowo, jeżeli zestawienie ma przedstawiać faktury, należy wskazać klasę:

Faktura

Od tej chwili każdy wiersz zestawienia będzie reprezentował jeden obiekt tej klasy.

3.2. Symbol znacznika #

Po utworzeniu znacznika bs4 core nadaje mu automatycznie symbol.

Symbol można:

• skopiować i ręcznie wkleić do odpowiedniego szablonu,
• przeciągnąć do szablonu za pomocą edytora drag and drop.

Podczas generowania dokumentu symbol zostanie zastąpiony właściwym zestawieniem.

4. Definiowanie wyglądu zestawienia #

Za wygląd treści generowanej przez znacznik odpowiada pole:

Treść

Pole zawiera edytor HTML, w którym definiowany jest wzór zestawienia.

4.1. Budowa wzoru #

Treść znacznika może składać się jednocześnie z:

• kodu HTML określającego wygląd tabeli,
• innych znaczników zwracających dane poszczególnych obiektów,
• specjalnych symboli odnoszących się do kolumn,
• sekcji sterujących powtarzaniem wierszy.

Dzięki temu administrator może samodzielnie określić zarówno wygląd zestawienia, jak i dane prezentowane w poszczególnych kolumnach.

5. Korzystanie z innych znaczników wewnątrz zestawienia #

W polu Treść znacznika rodzaju Zestawienie można umieszczać inne wcześniej zdefiniowane znaczniki.

5.1. Zgodność klasy obiektów #

Znaczniki używane we wzorze pojedynczego wiersza powinny być powiązane z klasą obiektów prezentowanych przez zestawienie.

Przykładowo, jeżeli:

Obiekty w zestawieniu = Faktura

to znaczniki używane do prezentowania danych wiersza powinny wychodzić od klasy Faktura.

Pozwala to w każdym powtarzanym wierszu pobierać informacje dotyczące aktualnie przetwarzanej faktury.

6. Korzystanie z kolumn klasy #

Zamiast standardowych znaczników można — i w wielu przypadkach jest to rozwiązanie zalecane — korzystać z wcześniej zdefiniowanych kolumn danej klasy.

Jeżeli zestawienie prezentuje obiekty klasy Faktura, można używać kolumn powiązanych z klasą Faktura.

6.1. Symbol kolumny #

Odwołanie do kolumny jest umieszczane w klamrach i zawiera prefiks zx oraz numeryczny identyfikator kolumny.

Schemat:

{zxID_KOLUMNY}

Przykładowo, jeżeli kolumna zwracająca numer faktury ma identyfikator 5000050, jej symbol ma postać:

{zx5000050}

Symbol można umieścić w odpowiedniej komórce wzorca tabeli.

6.2. Przykład #

Jeżeli tabela zawiera kolumnę Numer faktury, w komórce wzorcowego wiersza odpowiadającej tej kolumnie można umieścić:

{zx5000050}

Dla każdego rekordu bs4 core podstawi w tym miejscu numer właściwej faktury.

7. Wiersz wzorcowy zestawienia #

W treści znacznika nie definiuje się ręcznie wszystkich wierszy wynikowych.

Administrator przygotowuje jeden wiersz wzorcowy, który bs4 core automatycznie powiela dla każdego rekordu zwróconego przez zestawienie.

7.1. Powielanie wiersza #

Jeżeli zestawienie zwróci:

• 1 rekord — program wygeneruje 1 wiersz,
• 5 rekordów — program wygeneruje 5 wierszy,
• 20 rekordów — program wygeneruje 20 wierszy.

W każdym z nich znaczniki i symbole kolumn zostaną zastąpione wartościami odpowiedniego obiektu.

8. Sekcja „wiersz” #

Dynamiczna część wzorca, która ma być powielana, powinna zostać oznaczona specjalnymi komentarzami HTML.

Początek sekcji:

<!--wiersz-->

Koniec sekcji:

<!--wiersz_end-->

8.1. Wiersz tabeli HTML #

W przypadku tabeli HTML pomiędzy tymi dwoma znacznikami powinien znajdować się jeden pełny wiersz tabeli, czyli kod rozpoczynający się od <tr> i kończący </tr>.

Schemat:

<!--wiersz-->
<tr>
    ...
</tr>
<!--wiersz_end-->

Cały fragment pomiędzy komentarzami jest traktowany jako wzorzec, który należy powtórzyć dla każdego rekordu.

9. Edycja kodu HTML #

W edytorze pola Treść można przełączać się pomiędzy:

• widokiem wizualnym,
• edycją kodu HTML.

W tym celu należy skorzystać z opcji:

Zmień tryb

Edycja czystego HTML jest szczególnie przydatna podczas definiowania sekcji dynamicznych i specjalnych komentarzy sterujących zestawieniem.

10. Zestawienie w treści tekstowej #

Znacznik rodzaju Zestawienie nie musi być wykorzystywany wyłącznie w dokumentach i wiadomościach HTML.

Może zostać zastosowany również w:

• e-mailu tekstowym,
• wiadomości SMS,
• innych treściach tekstowych.

10.1. Wzorzec bez HTML #

W takim przypadku nadal stosuje się sekcje:

<!--wiersz-->

oraz

<!--wiersz_end-->

ale wewnątrz nie używa się elementów <tr> i </tr>.

Poszczególne rekordy można rozdzielać na przykład:

• przejściem do nowej linii,
• przecinkiem,
• innym wybranym separatorem.

10.1.1. Przykład #

Jeżeli znacznik ma zwrócić listę numerów faktur, rezultatem może być:

FV/001/2026, FV/002/2026, FV/003/2026

Zestawienie nie musi więc zawsze przyjmować postaci tabeli.

11. Nagłówek i stopka zestawienia #

Poza dynamiczną sekcją wiersz można utworzyć elementy wyświetlane tylko raz dla całego zestawienia.

Mogą to być:

• nagłówek,
• nazwy kolumn,
• rozpoczęcie tabeli,
• stopka,
• podsumowania.

11.1. Nagłówek tabeli #

Przed sekcją dynamicznego wiersza można zdefiniować kod rozpoczynający tabelę oraz nagłówki poszczególnych kolumn.

Ta część nie będzie powielana.

11.2. Stopka tabeli #

Po zakończeniu sekcji wiersz można utworzyć stopkę tabeli, w której znajdą się na przykład:

• sumy,
• liczba pozycji,
• inne podsumowania.

12. Sumowanie wartości kolumn #

Poza sekcją powtarzanego wiersza można używać specjalnego symbolu pozwalającego zsumować wartości wskazanej kolumny.

Do standardowego symbolu kolumny należy dodać prefiks:

sum

12.1. Przykład #

Jeżeli kolumna kwoty ma identyfikator 5000051, wewnątrz pojedynczego wiersza jej wartość można wyświetlać symbolem:

{zx5000051}

Natomiast sumę tej kolumny dla wszystkich rekordów można wyświetlić poza sekcją wiersz za pomocą:

{sumzx5000051}

Pozwala to przygotować w stopce tabeli automatyczne podsumowanie wartości.

13. Kreator wzorca zestawienia #

Aby ułatwić przygotowanie kodu tabeli, w edytorze znacznika dostępna jest zakładka:

Kreator

13.1. Automatyczne generowanie wzorca #

W Kreatorze można:

1. wskazać kolumny, które mają zostać wykorzystane w zestawieniu,
2. wybrać Wyczyść wzór i wygeneruj nowy.

bs4 core utworzy automatycznie wzorzec tabeli zawierający wskazane kolumny.

Wygenerowany kod można następnie ręcznie zmieniać i rozbudowywać.

14. Numeracja wierszy #

W sekcji dynamicznego wiersza można zastosować symbol:

{LP}

Symbol ten zwraca kolejny numer wiersza.

Jeżeli zestawienie zawiera cztery rekordy, wartości będą kolejno wynosić:

1, 2, 3, 4.

Można dzięki temu łatwo utworzyć kolumnę Lp.

15. Liczba wszystkich wyników #

Poza sekcją wiersz można użyć symbolu:

{total_count}

Zwraca on całkowitą liczbę rekordów znalezionych przez zestawienie.

Może być wykorzystany na przykład do prezentacji informacji:

Liczba pozycji: 12

16. Grupowanie zestawienia #

Znacznik rodzaju Zestawienie może grupować wyniki według wskazanej kolumny.

Służy do tego pole:

Grupuj zestawienie według kolumny

16.1. Przykład grupowania #

Jeżeli zestawienie zawiera faktury, można pogrupować je według kolumny Rodzaj faktury.

Wtedy osobno mogą zostać przedstawione na przykład:

• faktury zwykłe,
• faktury korygujące.

17. Nagłówki grup #

Każda grupa może posiadać własny nagłówek.

Sekcję nagłówka grupy oznacza się komentarzami:

<!--separator-->

oraz:

<!--separator_end-->

Treść znajdująca się pomiędzy nimi jest generowana dla każdej kolejnej grupy.

18. Podsumowanie grup #

Poszczególne grupy można również podsumowywać lokalnie.

Do oznaczenia sekcji podsumowania grupy służą:

<!--separator_bottom-->

oraz:

<!--separator_bottom_end-->

Pozwala to przygotować dodatkową treść wyświetlaną na końcu każdej grupy, na przykład jej częściowe podsumowanie.

19. Ograniczanie liczby wyników #

W edytorze znacznika dostępny jest limit wyników.

Pozwala on określić maksymalną liczbę rekordów, które mogą zostać zwrócone.

Przykładowo można ustawić limit:

10

W takim przypadku nawet jeśli warunki spełnia więcej rekordów, w zestawieniu pojawi się maksymalnie 10 pozycji.

20. Określenie pierwszego zwracanego wiersza #

Można również wskazać, od którego rekordu ma rozpocząć się zestawienie.

Funkcja pozwala między innymi podzielić większe zestawienie na kilka części.

20.1. Przykład podziału na strony #

Jeżeli na jednej stronie dokumentu ma znaleźć się maksymalnie 10 rekordów:

• pierwszy znacznik może prezentować rekordy 1–10,
• drugi znacznik może prezentować rekordy 11–20.

Pozwala to kontrolować rozmieszczenie danych w generowanym dokumencie.

21. Sortowanie wyników #

Dla zestawienia można określić:

• kolumnę, według której wyniki mają być sortowane,
• kierunek sortowania.

Dostępne jest sortowanie:

• rosnące,
• malejące.

22. Uzupełnianie pustymi wierszami #

Można skonfigurować zestawienie tak, aby brakujące pozycje były uzupełniane pustymi wierszami.

22.1. Przykład #

Jeżeli:

• limit wyników wynosi 10,
• zestawienie zwraca 8 rekordów,

program może dodać 2 puste wiersze.

Dzięki temu tabela zawsze może mieć stałą wysokość niezależnie od rzeczywistej liczby wyników.

23. Ograniczenie do zaznaczonych wierszy #

Pole:

Ogranicz do zaznaczonych wierszy

jest wykorzystywane w sytuacji, gdy użytkownik uruchamia generowanie szablonu bezpośrednio z poziomu zestawienia, po wcześniejszym zaznaczeniu wybranych rekordów.

23.1. Przykład #

Użytkownik znajduje się w zestawieniu faktur i:

1. zaznacza trzy wybrane faktury,
2. uruchamia opcję Redaguj do kontrahenta,
3. generuje treść z szablonu.

Jeżeli w znaczniku włączono Ogranicz do zaznaczonych wierszy, zestawienie umieszczone w dokumencie będzie zawierało tylko trzy zaznaczone faktury.

24. Zamiana linków na tekst #

Opcja:

Zamień linki na tekst

powoduje, że odnośniki znajdujące się w zestawieniu nie są prezentowane jako aktywne linki.

Zamiast nich wyświetlany jest zwykły tekst.

Może to być przydatne szczególnie przy generowaniu dokumentów przeznaczonych do wydruku.

25. Blokady filtrów #

Jednym z najważniejszych elementów konfiguracji znacznika rodzaju Zestawienie są blokady filtrów.

Pozwalają one ograniczyć zestawienie wyłącznie do rekordów spełniających określone kryteria.

25.1. Definiowanie blokady #

W zakładce:

Blokady filtrów

można:

1. wskazać filtr, który ma zostać zastosowany,
2. określić wartość podstawianą do tego filtra.

Szczegółowe zasady działania filtrów i blokad filtrów są opisane w osobnej części dokumentacji.

26. Powiązanie wyników z bieżącym obiektem szablonu #

Szczególnie istotnym zastosowaniem blokad filtrów jest ograniczenie zestawienia do rekordów powiązanych z obiektem, dla którego aktualnie generowany jest szablon.

W konfiguracji źródła wartości blokady dostępny jest wariant odpowiadający ID obiektu, w którego kartotece znajduje się użytkownik.

26.1. Przykład — faktury kontrahenta #

Załóżmy, że użytkownik znajduje się w kartotece konkretnego kontrahenta i generuje pismo zawierające jego faktury.

W znaczniku zestawienia należy:

1. ustawić klasę obiektów na Faktura,
2. dodać blokadę filtra,
3. wskazać filtr oparty na polu Kontrahent lub Nabywca faktury,
4. jako źródło wartości wskazać ID obiektu, w którego kontekście generowany jest szablon.

Dzięki temu zestawienie zwróci wyłącznie faktury bieżącego kontrahenta.

27. Powiązanie zestawienia z obiektem triggera #

Ten sam mechanizm może być wykorzystywany, gdy szablon jest generowany automatycznie przez trigger.

Jeżeli trigger jest powiązany z konkretnym obiektem, wartość tego obiektu może zostać wykorzystana do ograniczenia zestawienia.

27.1. Przykład — faktury kontrahenta #

Jeżeli trigger działa w kontekście konkretnego kontrahenta, znacznik można ograniczyć tak, aby zwrócił tylko faktury tego kontrahenta.

27.2. Przykład — pozycje oferty #

Jeżeli trigger działa w kontekście konkretnej oferty handlowej, można przygotować znacznik Zestawienie prezentujący pozycje oferty.

Do zestawienia należy wtedy zastosować filtr ograniczający wyniki do tych pozycji, których pole Oferta wskazuje na bieżącą ofertę powiązaną z triggerem.

W efekcie wygenerowany dokument lub plik będzie zawierał wyłącznie produkty należące do tej konkretnej oferty.

28. Wartość blokady pobierana ze znacznika #

Blokada filtra nie musi pobierać wartości wyłącznie bezpośrednio z bieżącego obiektu.

Można również wybrać wariant, w którym źródłem wartości jest wskazany znacznik, opcjonalnie działający w kontekście bieżącego obiektu.

Pozwala to tworzyć bardziej złożone zależności, w których:

1. jeden znacznik wyznacza określoną wartość,
2. wartość ta trafia do filtra,
3. filtr ogranicza rekordy prezentowane przez znacznik rodzaju Zestawienie.

29. Podsumowanie #

Znaczniki rodzaju Zestawienie są przeznaczone do generowania list i tabel zawierających wiele rekordów.

Podczas konfiguracji należy przede wszystkim:

1. wskazać klasę obiektów zestawienia,
2. przygotować wzorzec treści,
3. zdefiniować jeden dynamicznie powtarzany wiersz,
4. umieścić w nim odpowiednie znaczniki lub symbole kolumn,
5. w razie potrzeby skonfigurować filtrowanie, sortowanie, grupowanie i podsumowania.

Mechanizm umożliwia między innymi:

• automatyczne powielanie wierszy,
• numerowanie rekordów,
• sumowanie kolumn,
• wyświetlanie liczby wyników,
• grupowanie rekordów,
• podsumowywanie grup,
• ograniczanie liczby wyników,
• generowanie stałej liczby wierszy,
• korzystanie tylko z rekordów zaznaczonych przez użytkownika,
• kontekstowe ograniczanie wyników do bieżącego obiektu,
• wykorzystanie wartości zwracanych przez inne znaczniki.

Dzięki temu jeden znacznik może obsłużyć zarówno proste listy, jak i rozbudowane tabele wykorzystywane w ofertach, pismach, e-mailach i innych dokumentach generowanych przez bs4 core.