Raporty Telerik

Przeczytasz w 29 min.

Spis treści

Streszczenie
Deklaracja raportu
Web Report Designer
Definiowanie parametrów raportu
Definiowanie źródła danych SQL
Przypisanie źródła danych do raportu
Grupowanie danych w raportach
Wykres
1. Kategorie, serie i wartosci
Tabela przestawna
1. Tabela przestawna typu drill-down
Ustawienia regionalne w raportach
Filtrowanie rekordów według uprawnień ACL

Streszczenie

W artykule opisano funkcję projektowania raportów na potrzeby wizualnej prezentacji danych przetwarzanych w aplikacjach nAxiom. Stanowi on rozwinięcie ogólnych zasad pracy z raportami w nAxiom opisanych w Leksykonie nAxiom (rozdział Raporty).

Funkcjonalność projektowania szablonów raportów w nAxiom opiera się na module Web Report Designer produktu Telerik® Reporting firmy Telerik. Dokumentacja tego produktu jest dostępna online, a pod adresem https://docs.telerik.com/reporting/creating-the-report znajduje się wprowadzenie do projektowania raportów.

Od wersji 1.10.1 szablony raportów definiowane przez konsultanta są zapisywane domyślnie w tabeli core.ReportDefinitions w bazie danych.

Deklaracja raportu

Aby zaprojektować raport, kliknij menu Szablony w sekcji NARZĘDZIA w menu back-office i kliknij polecenie Szablony raportów. Kliknij przycisk Nowy raport na wyświetlonej stronie, aby zadeklarować nowy szablon raportu. W wyświetlonym oknie wypełnij pola Kod, Nazwa, Aplikacja i Moduł, a następnie kliknij przycisk Zapisz. Definicja szablonu raportu zostanie zapisana, a w nowej karcie przeglądarki zostanie otwarta strona Web Report Designer.

Jeśli w przeglądarce włączono blokowanie wyskakujących okienek, strona Web Report Designer zostanie zablokowana. Należy wówczas kliknąć przycisk Designer w prawym dolnym rogu okna dialogowego.

Web Report Designer

Na stronie Web Report Designer można wyróżnić następujące obszary:

Pasek menu zawiera:

rozwijane menu z poleceniami:
- New Report (Nowy raport): tworzy nowy raport.
- New Combined Report (Nowy raport połączony): tworzy nowy raport, który łączy w sobie kilka raportów (report book)
- Open (Otwórz): otwiera jeden z ostatnio utworzonych raportów.
- Open Recent (Otwórz ostatni): wyświetla listę ostatnio modyfikowanych raportów.
- Save (Zapisz): zapisuje zmiany w projekcie raportu.
- Save As (Zapisz jako): zapisuje raport pod nową nazwą.
- Close (Zamknij): zamyka projekt raportu.
- Close All But This (Zamknij wszystko, oprócz tego): zamyka projekty innych raportów, oprócz bieżącego.
- Asset Manager (Menedżer zasobów): służy do zarządzania folderami zasobów: Recent, Reports i resources (zawiera podfoldery Data, Images i Styles). Pozwala tworzyć podfoldery i dodawać pliki zasobów (przycisk Upload).
Pliki zasobów dodawane przez użytkowników są zapisywane lokalnie w folderze instalacyjnym witryny nAxiom. Na przykład folder resources znajduje się w ścieżce folder_instalacyjny_naxiom\reportsapi\resources. Pliki te nie są objęte funkcjonalnością eksportu aplikacji.
- Workspace preferences (Preferencje obszaru roboczego): pozwala określić preferencje w kwestii przyciągania elementów raportu do linii siatki oraz do linii przyciągania.
nazwa pliku raportu: nazwa pliku raportu jest domyślnie tworzona z kodu raportu i rozszerzenia trdp.
okienko wyszukiwarki: umożliwia szukanie właściwości, komponentów i elementów raportu.
przyciski Undo (Cofnij) i Redo (Ponów).
przycisk Preview (Podgląd), który wyświetla podgląd raportu; w trybie podglądu ten przycisk zmienia się na Design (Projekt) i służy do powrotu do trybu projektowania.

Panel z zakładkami Components (Komponenty) i Explorer (Eksplorator) z lewej strony.

Explorer: drzewo struktury raportu; dla pustego raportu zawiera następujące elementy:
- DataSources (Źródła danych): źródła danych, których można używać w raporcie; domyślnie dostępne są wszystkie widoki i tabele standardowego modelu danych (dokument biznesowy) zdefiniowane w bazie danych bieżącej witryny.
- Parameters (Parametry): zdefiniowane parametry raportu; predefiniowane parametry to _LangId (identyfikator języka), _UserId (identyfikator zalogowanego użytkownika) oraz _Id (identyfikator bieżącej instancji dokumentu biznesowego)
- Styles (Style): reguły stylu zdefiniowane dla różnych selektorów - typów obiektów na raporcie.
- CrossSectionItems (Elementy podziału sekcji): wizualne wyróżniki sekcji raportu, zazwyczaj grup danych.
- Groups (Grupy): zdefiniowane grupowania danych raportu
- pageHeaderSection1 (Nagłówek strony1): sekcja nagłówka strony
- detailSection1 (Sekcja szczegółów1): sekcja szczegółów strony
- pageFooterSection1 (Stopka strony1): sekcja stopki strony

Ponadto na panelu Explorer pojawiają się pozycje odpowiadające wszystkim obiektom dodawanym do raportu podczas projektowania.

Components: przybornik z obiektami, które można dodawać do raportu:
- Report Items (Elementy raportu): pole tekstowe, pole tekstowe HTML, pole obrazu, pole wyboru, pole kodu kreskowego, kształt, panel
- Tables (Tabele): lista, tabela, tabela przestawna, kreator tabeli, kreator tabeli przestawnej
- Report (Raport): podraport
- Maps (Mapy): mapa, kartogram
- Charts (Wykresy): słupkowy, kolumnowy, powierzchniowy, liniowy, kołowy
- Report Sections (Sekcje raportu): nagłówek strony, stopka strony, nagłówek raportu, stopka raportu, spis treści
- Data Sources (Źródła danych): źródło danych SQL, źródło danych CSV, źródło danych WebService, źródło danych JSON, obiektowe źródło danych

W środku obszaru roboczego znajduje się arkusz projektowanego raportu. W przypadku nowego raportu arkusz zawiera trzy sekcje: nagłówek strony, szczegóły i stopkę strony.

Z prawej strony znajduje sie panel właściwości elementu wybranego na raporcie lub w drzewie struktury raportu z lewej strony.

Definiowanie parametrów raportu

Przed przystąpieniem do definiowania źródeł danych należy zdefiniować parametry raportu, które następnie można będzie powiązać z parametrami definiowanymi w zapytaniu źródła danych. W tym celu należy kliknąć w dowolnym pustym miejscu obszaru projektowania lub pozycję raportu na panelu Explorer, aby na panelu właściwości wyświetlić parametry raportu.

Rozwiń sekcję DATA i kliknij symbol + z prawej strony pozycji ReportParameters. Wypełnij pola w wyświetlonym oknie dialogowym:

AllowBlank: zezwala na pustą wartość parametru typu string
AllowNull: zezwala na pustą wartość parametru
AutoRefresh: automatycznie odświeża raport po zmianie wartości parametru w trybie podglądu (wymaga włączenia opcji Visible)
AvailableValues: pozwala określić listę dostępnych wartości parametru na podstawie indywidualnego źródła danych:
- DataSource: źródło danych dla listy wartości parametru
- DisplayMember: pole źródła danych, którego wartości będą wyświetlane na liście
- Filters: filtr wartości wyświetlanych na liście
- Sortings: sortowanie wartości dostępnych na liście
- ValueMember: pole źródła danych, którego wartości będą ustawiane jako wartości parametru
Mergeable: decyduje, czy w przypadku raportów łączonych wartości parametru mją być scalane z wartościami parametrów równoważnych
MultiValue: określa, czy jako wartość parametru może zostać podana kolekcja wartości (pozwala użyć parametru z operatorem IN)
Name: nazwa parametru; może zawierać tylko znaki alfanumeryczne i znak podkreślenia, nie może zaczynać się od cyfry
Text: etykieta tekstowa parametru wyświetlana w obszarze wartości parametrów po włączeniu opcji Visible
Type: typ danych parametru
Value: wartość parametru używana do wyświetlania roboczego podglądu
Visible: umożliwia interaktywną zmianę wartości parametrów podczas wyświetlania podglądu

W prezentowanym przykładzie zdefiniowano dwa parametry _WojId (identyfikator województwa) oraz _NamePart (dowolny ciąg znaków, który ma zawierać nazwa miejscowości). Ponadto dostępne są standardowe parametry _LangId, _UserId oraz _Id.

Definiowanie źródła danych SQL

W jednym raporcie można korzystać z kilku źródeł danych. Źródło danych można przypisać na poziomie raportu, listy, tabeli, tabeli przestawnej i wykresu (właściwość DATA > DataSource). Aby utworzyć nowe źródło danych SQL, na panelu Components kliknij DATA SOURCES > SQL Data Source. Zostanie wyświetlony kreator, który w kilku krokach pomaga zdefiniować źródło danych SQL.

Wybór połączenia danych
Zaakceptuj wybór domyślnego połączenia nAxiom i kliknij Next.
Opcje połączenia danych
Zaakceptuj domyślnie wybraną opcję Use as shared connection, dzięki której to połączenie danych będzie współużytkowane przez wszystkie raporty. Kliknij Next.
Skonfiguruj polecenie źródła danych
Wpisz instrukcje zapytania SQL, która zwróci dane do raportu. Alternatywnie można zaznaczyć opcję Stored procedure i podać nazwę procedury składowanej z bazy danych.

Aby podczas generowania raportu można było używać parametrów, w zapytaniu należy dodać klauzulę WHERE i zastosować w niej deklaracje parametrów w formie @nazwa (w przykładowym zapytaniu @prm_idwoj i @prm_part).

Definiowanie źródła danych
Konfigurowanie parametrów źródła danych
Powiąż parametry użyte w zapytaniu z parametrami raportu.

Parametry raportu
Konfigurowanie roboczych wartości parametrów
Wpisz wartości parametrów, które będą używane do generowania roboczego podglądu danych ze źródła.
Podgląd
Określ liczbę rekordów ze źródła danych i kliknij przycisk Execute Query, aby wyświetlić podgląd danych ze źródła.

Podgląd danych ze źródła

Kliknij przycisk Finish. Teraz zdefiniowane źródło danych można przypisać do raportu lub np. do tabeli.

Przypisanie źródła danych do raportu

Aby przypisać źródło danych do raportu, wyświetl właściwości raportu na panelu z prawej strony, rozwiń sekcję DATA i wybierz źródło danych z listy rozwijanej DataSource. Teraz wystarczy przeciągnąć pola z definicji źródła danych do sekcji szczegółów formularza i wyświetlić testowy podgląd wartości dla zadanych parametrów.

Następnie, z panelu Components można dodać nagłówek raportu i dodać w nim tytuł raportu, a w nagłówku strony dodać nagłówki kolumn raportu. Ponieważ jednak nagłówek strony jest domyślnie wyświetlany przed nagłówkiem raportu na pierwszej stronie, należy anulować zaznaczenie pola wyboru PrintOnFirstPage w sekcji BEHAVIOUR oraz skopiować nagłówki kolumn raportu do nagłówka raportu poniżej tytułu. Dzięki temu nagłówki kolumn pojawią sie pod tytułem raportu na pierwszej stronie.

Aby dodać numerowanie stron raportu, dodaj pole tekstowe do stopki strony i skonfiguruj jego wartość, jak na ilustracji (właściwość Value w sekcji APPEARANCE).

Ilustracja poniżej przedstawia przykładowy projekt raportu. Trzeba pamiętać o dopasowaniu wysokości sekcji szczegółów, aby między kolejnymi wierszami nie było zbyt dużych odstępów.

Kolejna ilustracja przedstawia podgląd przykładowego raportu.

Grupowanie danych w raportach

Przykładowy raport zawiera wykaz nazw miejscowości, które zawierają podawany jako parametr ciąg znaków. Nazwy są wyświetlane w kolejności alfabetycznej. Dla nazw miejscowości naturalnymi grupowaniami będą jednostki administracyjne, do których należą te miejscowości, a więc gminy, powiaty i województwa. W tej sekcji zostanie opisane dodanie grupowania na poziomie raportu oraz dodatkowo skonfigurowanie możliwości zwijania i rozwijania grup.

W celu dodania grupy, wyświetl panel właściwości raportu i rozwiń sekcję DATA. Następnie kliknij pozycję Groups i kliknij znak + z prawej strony, aby dodać nową grupę. Kliknij pozycję Groupings i wyświetlonym oknie dialogowym w polu Expression wybierz pole, które zostanie użyte do grupowania danych (w przykładzie jes to pole Wojewodztwo). Zapisz grupowanie i nadaj grupie nazwę, np. gr_woj. Aby grupy były posortowane według nazwy województwa, dodaj sortowanie (Sortings > Expression = Fields.Wojewodztwo).

Zdefiniowanie grupy powoduje dodanie na raporcie nagłówka i stopki grupy bezpośrednio nad i pod sekcją szczegółów. Przenieś do nagłówka grupy pole województwo z sekcji szczegółów i wyświetl podgląd raportu.

Kolejny krok to skonfigurowanie zwijania i rozwijania szczegółów przez kliknięcie wartości grupującej. Zaznacz pole z nazwą województwa w nagłówku grupy i na panelu właściwości rozwiń sekcję INTERACTIVITY. W pozycji Action wybierz Toggle visibility z listy Type, a z listy Toggle targets wybierz sekcję szczegółów. Następnie kliknij symbol + obok listy, aby dodać tę sekcję do listy miejsc docelowych.

Konfiguracja zwijania/rozwijania szczegółów grupy

Teraz na podglądzie raportu nazwy miejscowości będą pogrupowane według województw, a kliknięcie nagłówka grupy spowoduje jej zwinięcie. Aby odwrócić sytuację, to jest wyświetlać grupy jako domyślnie zwinięte, należy anulować zaznaczenie pola wyboru Visible w sekcji BEHAVIOR dla sekcji szczegółów raportu. Dodatkowo warto anulować zaznaczenie pola wyboru Toggle mark initially expanded (sekcja INTERACTIVITY, panel właściwości nagłówka grupy), aby symbol wyświetlany obok nagłówka grupy zmienił się z domyślnego - (grupa rozwinięta) na + (grupa zwinięta).

Po wykonaniu powyższych czynności na podglądzie raportu grupy rekordów są domyślnie zwinięte, a obok nagłówka grupy jest wyświetlany symbol +. Kliknięcie nagłówka powoduje rozwinięcie grupy.

Wykres

W module Telerik Web Reporting wykresy są elementami danych, to jest obiektami, które mogą mieć osobne źródło danych. Aby skonfigurować raport, wykonaj poniższe czynności:

Kliknij odpowiedni typ wykresu na panelu Components w sekcji Charts (np. Column).
Na panelu z prawej strony w polu Column chart type wybierz podtyp wykresu (np. Clustered Column).
Z listy Data Source wybierz zdefiniowane wcześniej źródło danych. Zostaną wyświetlone pola źródła danych.
Przeciągaj kolejno pole źródła danych do sekcji Categories (opcjonalnie), Series i Values.
W razie potrzeby zmień funkcję agregującą dodaną automatycznie do pola w sekcji Values, klikając pionowy wielokropek z prawej strony i wybierając Functions > Nazwa funkcji.
Kliknij przycisk Create, aby utworzyć wykres.

Kategorie, serie i wartosci

Dane przedstawiane na wykresie można pogrupować w kategorie (opcjonalnie) i serie. Na przykład, aby przedstawić na wykresie liczbę gmin w każdym województwie z podziałem na rodzaje gmin, należy wybrać pole Wojewodztwo jako kategorię, a pole RodzajGminy jako serię. Natomiast wartością będzie funkcja agregująca CountDistinct(Fields.Gmina).

Wykres słupkowy; kategoria: województwo; seria: rodzaj gminy

Jeśli zamienić serie z kategoriami, wykres będzie przedstawiał rodzaje gmin z podziałem na województwa. Aby zwiększyć czytelność, można dodać filtr, który będzie wybierał np. 5 województw z największą liczbą gmin. W tym celu trzeba zmodyfikować serię danych (DATA > SeriesGroup > NazwaSerii) we właściwościach wykresu, dodając filtr jak na ilustracji poniżej.

Wykres z zamienionymi seriami i kategoriami wygląda jak poniżej.

Wykres słupkowy; kategoria: rodzaj gminy; seria: województwo

Tabela przestawna

Tabela przestawna to podobnie jak wykres element danych, a więc obiekt raportu, który może mieć własne źródło danych. Dodatkowo tabela przestawna pozwala przedstawiać dane zagregowane w dwóch wymiarach: w wierszach i kolumnach. Aby dodać tabelę przestawną do raportu, kliknij sekcję szczegółów i kliknij pozycję Crosstab Wizard w sekcji TABLES na panelu Components. Z prawej strony zostanie wyświetlony panel kreatora podobny jak dla wykresu.

Wybierz źródło danych (DataSource), a następnie przeciągaj pola ze źródła do obszarów Column Groups, Row Groups i Detail Values. Dodatkowo możesz wybrać sposób prezentowania podsum i sum łącznych (brak, poniżej, powyżej wierszy).

W obszarach Column Groups i Row Groups można zdefiniować kilka poziomów grupowania.

Po kliknięciu przycisku Create w sekcji szczegółów raportu zostanie wyświetlony projekt tabeli, który można zmodyfikować. Poniższe ilustracja przedstawiają projekt tabeli przestawnej i podgląd raportu z tabelą przestawną.

Tabela przestawna typu drill-down

W prosty sposób można dodać funkcjonalność zwijania grup wierszy w tabeli przestawnej. W przykładzie są dwa poziomy grupowania: województwo i powiat. Aby umożliwić „rozwijanie” województw wykonaj poniższe czynności.

Kliknij pole, w którym jest nazwa województwa ([=Fields.Wojewodztwo]).
Na panelu właściwości tego pola rozwiń sekcję INTERACTIVITY i podsekcję Action.
Z listy Type wybierz pozycję Toggle Visibility.
Z listy Toggle targets wybierz sekcję docelową dla przełączania widoczności (powiat1).
Kliknij symbol + z prawej strony listy Toggle targets.
Wyczyść pole wyboru Toggle mark initially expanded.
Na panelu Explorer z lewej strony kliknij pozycję powiat1 (element tabeli crosstab1 ).
Na panelu właściwości tego elementu rozwiń sekcję BEHAVIOR i wyczyść pole wyboru Visible.

Po wprowadzeniu tych modyfikacji tabela przestawna będzie wyświetlana w formie zwiniętej, a kliknięcie symbolu + przed nazwą województwa pokaże liczbę rodzajów miejscowości w poszczególnych powiatach tego województwa.

Ustawienia regionalne w raportach

Moduł Telerik Reporting domyślnie używa systemowych ustawień regionalnych, które określają format waluty, daty i godziny oraz liczb (separatorów tysięcy i dziesiętnego). Kiedy zachodzi potrzeba wygenerowania raportów dla innych niż systemowe ustawień regionalnych, można użyć funkcji FormatWithCulture. Ta funkcja ma następującą składnię:

FormatWithCulture(cultureName, format, args)

Gdzie:

cultureName: symbol ustawień regionalnych zgodny z RFC 1766, np. “pl-PL”
format: określenie formatu wartości wskazanej jako trzeci argument; ma formę “{0:formatSymbol}”, np. “{0:D}”; wykaz symboli formatów można znaleźć na stronie https://github.com/telerik/kendo-intl/blob/develop/docs/date-formatting/index.md; w tym argumencie można także dodać dowolny tekst przed formatowanym wyrażeniem lub po nim
args: referencje do pól źródła danych, z których wartości mają być formatowane, w formie Fields.NazwaPola

Wartość zwracana przez funkcję FormatWithCulture jest typu string.

Aby zdefiniować funkcję na raporcie, kliknij pole raportu, w którym chcesz użyć innych ustawień regionalnych. Następnie kliknij wielokropek w polu Value w sekcji APPEARANCE na panelu właściwości tego pola. Zostanie wyświetlone okno konstruktora wyrażeń. Kliknij kolejno Functions > Text na panelu z lewej strony u dołu. Kliknij dwukrotnie pozycję FormatWithCulture na środkowym panelu u dołu. W polu edycji u góry wpisz symbol ustawień regionalnych i wyrażenie formatujące, a następnie kliknij pozycję Fields na panelu z lewej i kliknij dwukrotnie nazwę pola na panelu środkowym, aby w definicji funkcji wstawić odwołanie do tego pola. Pamiętaj, aby dwa pierwsze argumenty ująć w cudzysłów. Przykładowa definicja może wyglądać jak na ilustracji poniżej.

Filtrowanie rekordów według uprawnień ACL

Uprawnienia do odczytu, aktualizacji i usuwania rekordów (RUD) definiowane w nAxiom jako szablony uprawnień ACL są weryfikowane tylko na poziomie widoków listy i formularzy generowanych automatycznie z modelu danych. Aby uprawnienia ACL były także uwzględniane w raportach, konieczne jest odpowiednie skonstruowanie źródła danych dla raportu.

W bazie danych nAxiom dostępna jest funkcja tabelaryczna core.GetAclIds, która zwraca wartości AclId dokumentów, do których ma uprawnienia użytkownik o podanym identyfikatorze. Funkcja przyjmuje trzy parametry:

userId: identyfikator użytkownika
businessDocumentId: (opcjonalny) identyfikator definicji dokumentu
aclType: kategoria szablonów uprawnień, dla których zostaną zwrócone uprawnienia; dostępne wartości:
- Instance: funkcja zwróci tylko dokumenty, do których uprawnienia użytkownika określono w szablonach dla instancji,
- Status: funkcja zwróci tylko dokumenty, do których uprawnienia użytkownika określono w szablonach dla poszczególnych statusów,
- InstanceWithStatus: funkcja zwróci dokumenty, do których uprawnienia użytkownika określono zarówno w szablonach instancji, jak i statusów.

Funkcję GetAclIds wywołuje się następująco:

SELECT * FROM core.GetAclIds('3F53097E-BFE6-4690-E075-08D6CEBA7D84',NULL,'InstanceWithStatus')

Funkcja zwraca identyfikator dokumentu (Id), identyfikator ACLId dokumentu oraz identyfikator definicji dokumentu BusinessDocumentId.

W źródle danych do raportu należy użyć operatora JOIN do złączenia tabeli zawierającej rekordy do wyświetlenia w raporcie z tabelą zwracaną przez funkcję GetAclIds, jak w przykładzie poniżej:

SELECT * FROM [dbo].[MyTable_View](@_LangId) tbl
JOIN [core].[GetAclIds](@UserId, @BussinesDocId, 'InstanceWithStatus') acl
ON tbl.ACLId = acl.ACLId

Parametry @_LangId i UserId są obsługiwane systemowo. Obsługę parametru BussinesDocId należy skonfigurować w raporcie w sposób opisany wcześniej w tym artykule. Bezpośrednie użycie wartości identyfikatora definicji dokumentu nie jest zalecane, ponieważ ta wartość może ulec zmianie po eksporcie aplikacji.

Aby można było wyświetlić podgląd raportu w module Web Report Designer, należy podać identyfikator użytkownika z uprawnieniami ACL jako wartość parametru _UserId, jak na ilustracji poniżej.