Własne raporty

WP Tao umożliwia tworzenie własnych raportów. Każdy raport składa się z dwóch powiązanych ze sobą elementów: raport skrócony wyświetlany w postaci kafelka w Panelu WP Tao oraz raport szczegółowy wyświetlany na osobnej podstronie.

Kiedy będzie potrzebny własny raport?

Najczęściej nowy raport będzie potrzebny gdy chcemy zaprezentować dane zebrane przez własne, wcześniej zarejestrowane zdarzenie. Poniższy poradnik jest kontynuacją czynności, które zostały wykonane w artykule Własne zdarzenia, w którym znajduje się instrukcja rejestracji własnych zdarzeń śledzących wejścia na strony z błędem 404. W poniższym tekście zakładamy, że użytkownik posiada już zarejestrowane zdarzenie 'error_404'.

W tym artykule zostanie wyjaśnione w jaki sposób dodać nowy:

  1. Kafelek do panelu WP Tao, wyświetlający zsumowaną liczbę wszystkich zarejestrowanych wystąpień błędu 404 w przeciągu ostatnich 30 dni
  2. Raport szczegółowy z zestawieniem ostatnich 30 dni i sumy wystąpień błędu 404 dla każdego dnia

Krok 1 – Rejestracja raportu

Każdy raport WP Tao jest obiektem PHP. Do przygotowania raportu będzie trzeba utworzyć nową klasę PHP dziedziczącą po klasie WTBP_WPTAO_Admin_Reports.
Do rejestracji raportu będzie wykorzystana funkcja wptao_register_report( $slug_name, $class_name ) przyjmująca dwa parametry:

  • slug string – unikatowa nazwa raportu będąca za razem jego identyfikatorem oraz nazwą wyświetlaną jako parametr URL. Wartość ta nie może zawierać spacji i niedozwolonych znaków
  • class_name string – unikatowa nazwa klasy która rozszerza klasę WTBP_WPTAO_Admin_Reports

Krok 2 – Przygotowanie klasy z raportem

Poniżej znajduje się uproszczona postać klasy w której zostanie utworzony raport. Do klasy będą dodawane nowe metody. Na końcu wpisu będzie do wglądu gotowa klasa obsługująca pełny raport.

Krok 3 – Pobranie informacji z bazy danych

Informacje wykorzystywane w raportach należy pobrać bezpośrednio z bazy danych korzystając z obiektu globalnego WPDB. Dzięki temu twórcy raportów WP Tao mogą pobierać bardzo złożone dane.

W klasie rodzica WTBP_WPTAO_Admin_Reports ustawione są zmienne przechowujące domyślny zakres dat (timestamp) dla ostatnich 30 dni. Nie będziemy ich nadpisywać. Zmienne te zostaną wykorzystane w zapytaniu SQL.

Poniżej znajduje się dwie metody klasy Basic_Report_Error_404_Class_Name pobierające kluczowe dane z bazy danych.

  • get_sum() – pobiera sumę wystąpień błędu 404 dla ostatnich 30 dni
  • get_sum_per_days() – pobiera sume wystąpień błędu 404 z podziałem na dni

Krok 4 – Dodanie kafelka do panelu WP Tao (raport espresso)

W tym kroku zostanie utworzona metoda odpowiedzialna za dodanie kafelka na głównym panelu WP Tao. Na kafelku będzie wyświetlona suma wszystkich wystąpień błędu 404 z ostatnich 30 dni oraz link do raportu szczegółowego.
Poniżej znajduje się metoda rejestrująca kafelek. Zmienna $this->sum przechowuje liczbę wystąpień błędu, która została obliczona w poprzednim kroku przez metodę get_sum().

W celu dodania kafelka będzie trzeba wywołać metodę klasy rodzica add_widget( $args ), w której jako parametr niezbędne jest przekazanie tablicy z ustawieniami. Tablica ta przyjmuje następujące wartości:

  • id string (required) – unikatowa nazwa kafelka bez spacji i znaków specialnych
  • size string (optional) – jeden z rozmiarów predefiniowanych. Dostępne: small, middle, middle-col, big. Domyślne: small
  • value_number int (optional) – wynik postaci liczby. Jeżeli kafelek powinien wyświetlać samą liczbę, to jej wartość należy podać w tym polu.
  • value_text string (optional) – wynik w postaci tekstu. Jeżeli kafelek powinien wyświetlać tekst, to należy pominąć pole value_number i w tym polu wpisać treść.
  • category string (optional) – nazwa kategorii pomagająca rozróżnić rodzaje raportów. Dostępne: traffic, commerce, user, contact.
  • title string (optional) – nazwa raportu skróconego widoczna na kafelku w panelu WP Tao.
  • report_slug string (optional) – nazwa raportu szczegółowego które ma być skojarzony z kafelkiem. Po podaniu prawidowej nazwy na kafelku zostanie wyświetlona ikona z linkiem do raportu szczegółowego.
  • report_link string (optional) – adres URL raportu szczegółowego z zewnętrznego źródła. Link do raportu szczegółowego zostanie pobrany automatycznie po podaniu pola report_slug. Jeżeli jest podany report_slug to to pole powinno pozostać puste.
  • css_class string (optional) – nazwa klasy CSS kafelka.
  • priority int (optional) – kolejność wyświetlania. Domyślnie 50
  • custom_html string (optional) – w przypadku kiedy wartości prezentowane na kafelku są zbyt złożone, można wyświetlić je używając własnego kodu HTML.

Krok 5 – Wyświetlenie wyników raportu szczegółowego

W celu wyświetlenia wyników należy odpowiednio przygotować metodę body(). W tym artykule będziemy wyświetlać wyniki z uwzględnieniem dat. Klasa po której nasz raport dziedziczy (WTBP_WPTAO_Admin_Reports) udostępnia przydatną zmienną $this->days, która przechowuje tablicę z dniami uwzględniającą aktualny filtr czasowy $this->start_date i $this->end_date. Dzięki temu będzie można w łatwy sposób utworzyć pętle foreach dla ustawionego zakresu dat (ostatnie 30 dni).

Poniżej znajduje się przygotowana zawartość metody body() na potrzeby tego poradnika.

Podsumowanie

Własne raporty są szczególnie istotne podczas integracji WP Tao z autorskimi rozwiązaniami. Dzięki możliwości tworzenia własnych zdarzeń i własnych raportów, deweloperzy mogą dostosować WP Tao do swoich potrzeb. Istnieje możliwość zbierania niestandardowych danych i wyświetlania ich w przyjaznych raportach. Dodatkowym atutem jest to, że własne raporty są spójne z innymi raportami WP Tao i wyświetlane w spójnym intuicyjnym interfejsie.

W tym artykule utworzyliśmy gotowy raport wyświetlający informacje o błędach 404. Poniżej znajduje się spójny, całościowy kod, który zawiera wszystko to co zostało opisane wyżej.