Reports

Reports can be found in the Utilities module of Jadu Central. Many useful reports are provided out of the box but you can also add your own to show information on whatever you like - whether that's surfacing information from standard database tables, showing information from another of your own custom developments or something else entirely.

Adding a custom report

Start by creating a new class that implements Jadu\Reports\ReportInterface and extends Jadu\Reports\Report\AbstractReport:

<?php

namespace MyProject\Reports;

use Jadu\Reports\Chart;
use Jadu\Reports\ReportInterface;
use Jadu\Reports\Report\AbstractReport;

class MyReport extends AbstractReport implements ReportInterface
{
    // ...

The AbstractReport will implement many of the methods required by the ReportInterface but you can also override these if required.

AbstractReport has protected properties $db which contains an ADOConnection to the current site's database and $input which is an instance of JaduFramework\Http\Input, populated based on the current request.

Key methods

You will need to implement the following methods in your report class:

getShowMeStatement(): string

This method should return a string to tell the user what items are being listed in the report.

getFileName(): string

This should return a file name unique to the report to be used when generating a CSV file.

run()

This is the method that will do all of the work in your report!

The method does not need to return any data but should instead assign the report data to the reportData property. The value assigned just needs to be an array containing an item for each row of the report.

Other methods

You may also wish to override some of the following methods:

clearReportDataArrays()

In the abstract, this method clears out the reportData and graphData properties.

getCSV()

This method should write out each row of the report data to a CSV file.

getChart()

This must return a Jadu\Reports\Chart object.

getColumnType($index)

This method is deprecated.

getHeaders()

This method should return an array of strings to be used as headings for the report table.

getPanel()

Populate this method for your report to optionally contain an additional info or warning panel on the page. This should return an array containing the panel's icon and text. For example:

    public function getPanel()
    {
        return [
            'body' => 'Please note - only the top 100 items are included in this report.',
            'icon' => 'info-sign',
        ];
    }

getParameterOptions()

If your report requires parameters where multiple options can be selected you can use this method to specify those options. Return an array of Jadu\Reports\Parameter objects.

    public function getParameterOptions()
    {
        $status = new Parameter();
        $status->setName('status')
            ->setLabel('Status')
            ->setType('select')
            ->setOptions([
                'live' => 'Live',
                'nonlive' => 'Not live',
            ]);

        return [$status];
    }

getParameterValues()

Generate a URL string of the parameter values. This is implemented for you in AbstractReport.

getReportData()

This should return the reportData property.

getReportResultStatement()

This is expected to return a string stating how many results were found. This is implemented for you in AbstractReport.

getWhereStatements()

This is expected to return a string giving a description of the results based on the parameters given. This is presented to the end user.

For example, if one of the report parameters indicates "live" state and the user has selected the "live" option, this method would return the text "status is live".

isEnabled()

Return a boolean value to indicate whether or not this report should be enabled for use.

setParameterValues()

Set the value of each of the report's parameters based on the request input. A version of this is implemented for you in AbstractReport.

setReportData()

This is the equivalent to run().

showChart()

Return a boolean value to indicate whether the chart option should be presented.

showParameterModal()

Return a boolean value to indicate whether or not to open the parameters modal. The modal should not be opened if valid parameters have already been submitted, so this method is expected to check and return an appropriate value.

Registering your report

Once you have created your report class and implemented all the methods you require you must add it to the JaduReport database table for each site you wish for it to be available to.

You will need to insert a record with the title of your report, the full path of your class and a type which will be used to present the report within a tab labelled with the value given for type. There are no set options for type and the value you provide does not need to match any existing tab.

Example migration:

    namespace DoctrineMigrations;

    use Doctrine\Migrations\AbstractMigration;
    use Doctrine\DBAL\Schema\Schema;

    class Version20200527123457 extends AbstractMigration
    {
        private $className = '\MyProject\Reports\MyReport';

        public function up(Schema $schema)
        {
            $sql = <<<SQL
                INSERT INTO JaduReport (title, type, class)
                VALUES (
                    'My Report',
                    'Custom',
                    :class_name
                );
            SQL;

            $this->addSql($sql, [$this->className]);
        }

        public function down(Schema $schema)
        {
            $this->addSql("DELETE FROM JaduReport WHERE class = :class_name", [$this->className]);
        }
    }