Structure Of A Report

Creating report with KoolReport is very simple. All of us love simplicity, do we? A report created with KoolReport normally has two separated parts: process and view. The process part deal with data connection and data processing. And the view part visual processed data in form of table or chart.

What we will complete today

In this tutorial we will create a report to summarize sales of top 10 customers.

Setup KoolReport

I guess that you have downloaded the KoolReport from our website. If you do not, please go to Get Started and hit to [Download KoolReport].

Data

Our data is from csv file containing name of customers and amount of their orders. it will look like this:

You may download the orders.csv to try on your own.

Setup Your Report

Folder structure

Under the htdocs folder, we put koolreport folder which contains core library. We create the sale_report folder which will contains our report. Our folder structure will look like below:

htdocs
├── koolreport
├── sale_report
│   ├── orders.csv
│   ├── SalesByCustomer.php
│   ├── SalesByCustomer.view.php
│   └── index.php		

The SalesByCustomer.php is your report's controller file in which you define how report retrieve and process data. The SalesByCustomer.view.php is your report's view file to determine how your report will be displayed. The index.php is the bootstrap file to initiate report.

Controller class

SalesByCustomer.php is the file holding the SaleByCustomer report class:

<?php

// Require autoload.php from koolreport library
require_once "../koolreport/core/autoload.php";

//Specify some data processes that will be used to process
use \koolreport\processes\Group;
use \koolreport\processes\Sort;
use \koolreport\processes\Limit;

//Define the class
class SalesByCustomer extends \koolreport\KoolReport
{    
    protected function settings()
    {
        //Define the "sales" data source which is the orders.csv 
        return array(
            "dataSources"=>array(
                "sales"=>array(
                    "class"=>'\koolreport\datasources\CSVDataSource',
                    "filePath"=>"orders.csv",
                ),        
            )
        );
    }
  
    protected function setup()
    {
        //Select the data source then pipe data through various process
        //until it reach the end which is the dataStore named "sales_by_customer".
        $this->src('sales')
        ->pipe(new Group(array(
            "by"=>"customerName",
            "sum"=>"dollar_sales"
        )))
        ->pipe(new Sort(array(
            "dollar_sales"=>"desc"
        )))
        ->pipe(new Limit(array(10)))
        ->pipe($this->dataStore('sales_by_customer'));
    }
}

Code explanation:

1. The report starts with requiring the "autoload.php" file from KoolReport library. This is all you need to get started with KoolReport. If you install KoolReport library with Composer, you will not need to include this autoload file because it will be loaded together with composer's vendor/autoload.php.
2. In order to get top 10 sales by customers, we will need to group data by customers, sort it in descending order and then take top 10. So in the report, we use some necessary processes which are Group, Sort and Limit to complete the job.
3. We define SalesByCustomer class with two methods settings() and setup().
4. The settings() method will define the necessary settings for report including list of data sources. Here we only use single datasource from orders.csv and we name the source as "sales". Since the source is CSV file so we need to use CSVDataSource to handle csv file.
5. The setup() method is where we define how data will flow. Consider your data like a water flow running from the source passing through a lot of water processing until it reaches the water's damp. In the same manner, your data will run from the source through Group process then Sort process then Limit process and finally to the data store named "sales_by_customers".

View file

SalesByCustomer.view.php is the file holding the report display. It is pure php file containing HTML, CSS and KoolReport's Widget to visualize the report data.

<?php 
    use \koolreport\widgets\koolphp\Table;
    use \koolreport\widgets\google\BarChart;
?>

<div class="report-content">
    <div class="text-center">
        <h1>Sales By Customer</h1>
        <p class="lead">This report shows top 10 sales by customer</p>
    </div>

    <?php
    BarChart::create(array(
        "dataStore"=>$this->dataStore('sales_by_customer'),
        "width"=>"100%",
        "height"=>"500px",
        "columns"=>array(
            "customerName"=>array(
                "label"=>"Customer"
            ),
            "dollar_sales"=>array(
                "type"=>"number",
                "label"=>"Amount",
                "prefix"=>"$",
                "emphasis"=>true
            )
        ),
        "options"=>array(
            "title"=>"Sales By Customer",
        )
    ));
    ?>
    <?php
    Table::create(array(
        "dataStore"=>$this->dataStore('sales_by_customer'),
            "columns"=>array(
                "customerName"=>array(
                    "label"=>"Customer"
                ),
                "dollar_sales"=>array(
                    "type"=>"number",
                    "label"=>"Amount",
                    "prefix"=>"$",
                )
            ),
        "cssClass"=>array(
            "table"=>"table table-hover table-bordered"
        )
    ));
    ?>
</div>

Code explanation:

1. We use BarChart and Table to display report's data.
2. We define "dataSource" for BarChart which actually the dataStore "sales_by_customer" we created in the report's controller class.
3. The BarChart will have the height of 500px and full width
4. We define which columns will be use in the charts. The first column is "customerName" which will be used as label in the chart. The second column is "dollar_sales" which will be the value in the chart.
5. We have some settings for "dollar_sales", we label it as "Amount" rather than its default name is "dollar_sales" when display in the chart. We assign the "number" type for this column together with "$" prefix. By doing so, our "dollar_sales" will be format in form of "$50,000".
6. The Table has similar settings like BarChart. It defined "dataSource" pointing to the "sales_by_customers" data store. it defined the list of columns to be shown on table.

Running file

index.php is the file to run and render report:

<?php 

require_once "SalesByCustomer.php";
$salesbycustomer = new SalesByCustomer;
$salesbycustomer->run()->render();

Code explanation:

1. We include the report's controller class file so that we have SalesByCustomer class definition.
2. We create $salebycustomer object which is the instance of SalesByCustomer class
3. We run report and render it.
4. When the report runs, data will be pulled from csv file, piped to process and stored in "sales_by_customer" data store.
5. When the report renders, "sales_by_customer" datastore will be available to supply data to the BarChart and Table widgets.

Result

Now to run the report, we go to browser and enter following url:

https://localhost/sale_report/index.php

You will see top 10 customers with amount of purchase showing in the BarChart and Table of your report.

Source Code

Download this tutorial's source code.

Summary

Congratulation! You have completed very first basic report with KoolReport. What you have learned so far:

1. Structure of a report
2. How to setup the processing part
3. How to setup view part with simple table and chart.
4. Understand the flow of data
5. Understand how data will be rendered within views.

If you have any question, you may reply to this email.

See you in the next tutorial.

Resources

1. Get started
2. Sale Report Example
3. ScreenCast: Get started with KoolReport

<3 koolreport team