Custom reports

WP Tao allows you to create custom reports. Each report consists of two interrelated components: an abbreviated report displayed as a tile in the WP Tao Panel and a detailed report displayed on a separate subpage.

When will you need a custom report?

Most often the new report will be needed if we want to present the data collected by our own pre-registered event. The following tutorial is a continuation of the activities that have been performed in the article Custom events, which is a guide to registering custom events that track the visits to an error 404 page. In the following text, we assume that you have already registered an 'error_404' event.

This article will explain how to add a new item, such as:

  1. A tile to the WP Tao Panel, displaying the total number of all recorded instances of the error 404 within the last 30 days.
  2. A detailed report with the summary of the last 30 days, and the sum of occurrences of the error 404 for each day.

Step 1 – Registering the report

Each report in WP Tao is a PHP object. For the preparation of the report, it will be required to create a new PHP class that inherits from WTBP_WPTAO_Admin_Reports.
For the registration of the report the function wptao_register_report( $slug_name, $class_name ) will be used that assumes two parameters:

  • slug string – a unique name of the report which is both its identification and a name that is displayed as a URL parameter. This value cannot contain spaces and illegal characters.
  • class_name string – a unique name of the class that extends the class WTBP_WPTAO_Admin_Reports

Step 2 – Preparation of the class with a report

Below is a simplified form of the class in which the report will be created. New methods will be added to the class. At the end of an entry, there will be a ready class that supports the full report.

Step 3 – Retrieving information from the database

Information used in the reports should be downloaded directly from the database using the global object WPDB. As a result, the developers creating WP Tao reports can download very complex data.

In the parent class WTBP_WPTAO_Admin_Reports the variables are set that store the default date range (timestamp) for the last 30 days. We will not overwrite them. These variables will be used in the SQL query.

Below are two methods of class Basic_Report_Error_404_Class_Name retrieving key data from the database.

  • get_sum() – gets the sum of 404 views for the last 30 days
  • get_sum_per_days() – gets the sum of 404 views by days

Step 4 – Adding a tile to the WP Tao Panel (an espresso report)

In this step a method will be created responsible for adding a tile on the main panel of WP Tao. The tile will display the sum of all instances of error 404 from the last 30 days and a link to a detailed report.
The following is a method of registering a tile. The variable $this->sum stores the number of occurrences of the error, which was calculated in the previous step by the method get_sum().

To add a tile you will need to trigger a parent class method add_widget( $args ), in which as the parameter it is necessary to provide an array with settings. This array assumes the following values:

  • id string (required) – a unique tile name without spaces or special characters
  • size string (optional) – one of the predefined sizes. Available: small, middle, middle-col, big. Default: small
  • value_number int (optional) – the result as a number. If the tile should display a number only, then its value should be entered in this field.
  • value_text string (optional) – the result as a text. If the tile should display a text, you must omit the field value_number and enter the content in this field.
  • category string (optional) – the name of a category that helps to distinguish between types of reports. Available: traffic, commerce, user, contact.
  • title string (optional) – the name of an abbreviated report visible on a tile in the WP Tao Panel.
  • report_slug string (optional) – the name of a detailed report that is to be associated with the tile. After providing the correct name, the tile will display an icon with a link to a detailed report.
  • report_link string (optional) – the URL of a detailed report from an external source. A link to the detailed report will be downloaded automatically after providing the field report_slug. If report_slug is given, then this field should be left empty.
  • css_class string (optional) – the name of the CSS class of a tile.
  • priority int (optional) – the order of display. By default, 50
  • custom_html string (optional) – where the value displayed on the tile are too complex, you can display them using your own HTML code.

Step 5 – Displaying the results of a detailed report

To view the results, it is necessary to prepare the body() method properly. In this article we will display the results with regard to dates. The class after which our report inherits (WTBP_WPTAO_Admin_Reports) provides a useful variable $this->days, which holds an array with days taking into account the current time filter $this->start_date and $this->end_date. This will allow to easily create a foreach loop for the established date range (last 30 days).

The following is the contents of the body() method prepared for the purposes of this tutorial.

Summary

Custom reports are especially important when integrating WP Tao with one’s own solutions. Thanks to the possibility to create custom events and custom reports, developers can customize WP Tao to their needs. You can collect custom data and display is in friendly reports. Another advantage is that custom reports are consistent with other WP Tao reports and are displayed in a consistent intuitive interface.

In this article, we have created a ready-made report displaying information about errors 404. The following is a coherent, comprehensive code that contains everything what has been described above.