CustomDrillDown

Overview #

CustomDrillDown extends the capability to the max. It does not limit the number of charts in a level, you can show any custom content inside a level of drilldown. Due to flexibility, CustomDrillDown is a little more complicated to handle than normal drilldown above. To summarize the comparison between CustomDrillDown and DrillDown

  1. CustomDrillDown is faster than DrillDown since CustomDrillDown use the SubReport technology.
  2. When callback, only subreport of CustomDrillDown runs so it is more efficient while DrillDown will run the whole main report so it is less efficient.
  3. In CustomDrillDown, you need to setup subreport and connecting them with parameters while in DrillDown, you do not need to, we handle all for you.
  4. In sum, DrillDown vs CustomDrillDown is the trade-off between the convenience and the powerfulness, the easiness and the complexity.

Step By Step Tutorial #

Step 1: Create CountrySale report #

The CountrySale report is created in the same way you create a single report. In this CountrySale report, we summarize sale by country and display all countries. When user select a country, it called DrillDown next() function to pass the selection parameters to the next level.

<?php
class CountrySale extends \koolreport\KoolReport
{
    protected function settings()
    {
        return array(
            "dataSources"=>array(
                "mydatabase"=>array(
                    "connectionString"=>"mysql:host=localhost;dbname=mydata",
                    "username"=>"root",
                    "password"=>"",
                    "charset"=>"utf8"
                )
            )
        );
    }

    protected function setup()
    {
        $this->src("mydatabase")
        ->query("SELECT country, sum(amount) AS sale_amount FROM orders GROUP BY country")
        ->pipe($this-dataStore("sale_by_country"));
    }
}
<?php 
    //CountrySale.view.php
    use \koolreport\widgets\google\ColumnChart;
    $drilldown = $this->params["@drilldown"]
?>

<level-title>All Countries</level-title>

<?php
ColumnChart::create(array(
    "dataSource"=>$this->dataStore("sale_by_country"),
    "clientEvents"=>array(
        "itemSelect"=>"function(params){
            $drilldown.next({country:params.selectedRow[0]});
        }"
    )
))
?>

Step 2: Create StateSale report #

The StateSale report is created in the same way that you create a single report. StateSale report will receive a parameter called "country" which is the selected country from user. It will summarize the sale_amount by state in that country.

<?php
class StateSale extends \koolreport\KoolReport
{
    protected function settings()
    {
        return array(
            "dataSources"=>array(
                "mydatabase"=>array(
                    "connectionString"=>"mysql:host=localhost;dbname=mydata",
                    "username"=>"root",
                    "password"=>"",
                    "charset"=>"utf8"
                )
            )
        );
    }

    protected function setup()
    {
        $this->src("mydatabase")
        ->query("
            SELECT 
                state, sum(amount) AS sale_amount 
            FROM orders
            WHERE
                country=:country
            GROUP BY state
        ")
        ->params(array(
            ":country"=>$this->params["country"]
        ))
        ->pipe($this-dataStore("sale_by_state"));
    }
}
<?php 
    //CountrySale.view.php
    use \koolreport\widgets\google\ColumnChart;
    $drilldown = $this->params["@drilldown"]
?>

<level-title>States of <?php echo $this->params["country"]; ?></level-title>

<?php
ColumnChart::create(array(
    "dataSource"=>$this->dataStore("sale_by_state"),
))
?>

Step 3: Create MainReport #

The MainReport defines the CountrySale and StateSale as subreports and create CustomDrillDown at the view.

<?php
class MainReport extends \koolreport\KoolReport
{
    use \koolreport\clients\Bootstrap;
    protected function settings()
    {
        return array(
            "subReports"=>array(
                "countrysale"=>CountrySale::class,
                "statesale"=>StateSale::class
            )
        );
    }

    protected function setup()
    {
    }
}
<?php 
    //MainReport.view.php
    use \koolreport\drilldown\CustomDrillDown;
?>

<html>
    <head>
        <title> Sale By Location</title>
    </head>
    <body>
        <?php
        CustomDrillDown::create(array(
            "name"=>"locationSale"
            "title"=>"Sale By Location",
            "subReports"=>array("countrysale","statesale"),
        ))
        ?>
        ```
    </body>
</html>

As result of above settings, now you have a drilldown report that will show all countries with the sales achived in each country. When user selects a particular country, the drilldown will show the sale_amount by each states in that country. Awesome, is it?

Each levels of drill-down report is handled by a sub report which virtually you can customize the interface in the way you want. All you need to do is to call next() function of drill down, sending all selected values then wait for drilldown to move to next level.

Properties #

nametypedefaultdescription
namestring*Required Name of drill down
titlestringTitle that is showed on top of drill-down report.
subReportsarray*Required List of sub report name in level order
showLevelTitlebooltrueWhether title of each level is shown
btnBackmixedtrueBy default, the button Back will shown, give it value false you will off the Back button. This property can receive array() to customize cssClass and text of button "btnBack"=>array("text"=>"Go Back","class"=>"btn btn-default btn-warning")
cssmixedDefined css for the most important elements in the widgets, see the $css properties for more details.
panelStylestring"default"Set the panel style, accept value "default", "danger", "success", "info"
scopearray/functionAny params you want to included for sub report in form of associated array. You also may use a function and return associate array
clientEventsarrayRegister client-event, please see the Client Events for more details

Css Properties #

nametypedefaultdescription
panelstringDefine css style for top panel
levelTitlestringDefine css style for section that holds titles of level
btnBackstringAdd css style for Back button
bodystringDefined css style for body

Client events #

CustomDrillDown support following events:

namedescription
nextingFired when CustomDrillDown is preparing to go to next level. Return false to cancel action.
nextedFired when CustomDrillDown went to next level successfully.
backingFired when CustomDrillDown is going to go back to previous level. Return false to cancel action.
backedFired when CustomDrillDown went back to previous level
changedFired when CustomDrillDown changed level

Example

<?php
CustomDrillDown::create(array(
    ...
    "clientEvents"=>array(
        "nexting"=>"function(params){
            return false;//Cancel action
        }",
        "nexted"=>"function(params){
            console.log('Nexted to'+params.level);
        }",
    );
));
?>