Export

Overview #

Exporting feature is one of the must-have feature in any reporting system. Dashboard is able to export Widget and Dashboard to PDF/PNG/JPG in version 2.0.

Setup Exporting #

In order to turn on exporting capability, you need to provide an export handler to export() method Application class

use \koolreport\dashboard\ExportHandler;
use \koolreport\dashboard\export\ChromeHeadlessio;
use \koolreport\dashboard\Application;
class App extends Application
{
    ...
    protected function export()
    {
        return ExportHandler::create()
                ->storage(dirname(__DIR__)."/storage")
                ->pdfEngine(
                    ChromeHeadlessio::create()->token("your-token")
                );
    }
}

Code explanation:

  1. We create an export() method under App
  2. We return an instance of ExportHandler inside export() method
  3. We set the storage where exported files will be stored.
  4. We provide the PDF engine to pdfEngine() method. In this case we use ChromeHeadlessio as our engine.
  5. The ChromeHeadlessio requires token key which you can create after registered our chromeheadless service.

PDF/PNG/JPG Engines #

We provided 2 engines that use to generate PDF, PNG and JPG which are LocalExport and ChromeHeadlessio. While the LocalExport will use the Export package of KoolReport Pro to generate exported files, the ChromeHeadlessio will use CloudExport package to do so.

LocalExport #

Namedescription
defaultConfig(array $settings)Provide default export settings

Example:

use \koolreport\dashboard\ExportHandler;
use \koolreport\dashboard\export\LocalExport;
use \koolreport\dashboard\Application;
class App extends Application
{
    ...
    protected function export()
    {
        return ExportHandler::create()
                ->storage(dirname(__DIR__)."/storage")
                ->pdfEngine(
                    LocalExport::create()
                        ->defaultConfig([
                            "format"=>"A4",
                            "margin"=>"1in",
                            "orientation"=>"portrait"
                        ])
                )
                ->jpgEngine(
                    LocalExport::create() //You can use defaultConfig() to set exporting config for jpg
                )
                ->pngEngine(
                    LocalExport::create() //You can use defaultConfig() to set exporting config for png
                );
    }
}

ChromeHeadlessio #

Namedescription
defaultConfig(array $settings)Provide default export settings
token(string $token)Provide the token key to use ChromeHeadlessio service

Example:

use \koolreport\dashboard\ExportHandler;
use \koolreport\dashboard\export\ChromeHeadlessio;
use \koolreport\dashboard\Application;
class App extends Application
{
    ...
    protected function export()
    {
        return ExportHandler::create()
                ->storage(dirname(__DIR__)."/storage")
                ->pdfEngine(
                    ChromeHeadlessio::create()
                        ->token("your-token")
                        ->defaultConfig([
                            "format"=>"A4",
                            "margin"=>[
                                "top"=>"1in",
                                "bottom"=>"1in",
                                "left"=>"1in",
                                "right"=>"1in",
                            ],
                        ])
                )
                ->jpgEngine(
                    ChromeHeadlessio::create()
                        ->token("your-token") 
                    //You can use defaultConfig() to set exporting config for jpg
                )
                ->pngEngine(
                    ChromeHeadlessio::create()
                        ->token("your-token") 
                    //You can use defaultConfig() to set exporting config for png
                );
    }
}

XLS/CSV Engines #

To be provided in next version of Dashboard

Widget Export #

Settings #

To make an widget exportable to PDF, you do:

class MyDashboard extends Dashboard
{
    protected function widgets()
    {
        return [
            MyChart::create()
                ->pdfExportable(true) // Turn on this feature
        ];
    }
}

If you need to make a custom exporting settings for your widget, you insert your settings in form of array into exportable function

class MyDashboard extends Dashboard
{
    return [
        MyChart::create()
            ->pdfExportable([
                "format"=>"Letter",
            ])
    ];
}

The same settings is applied for other exporting types

Namedescription
->pdfExportable(mixed $params)Turn on PDF exportable for widget, the parameters could be boolean or an extra export settings for that widget
->pngExportable(mixed $params)Turn on PNG exportable for widget, the parameters could be boolean or an extra export settings for that widget
->jpgExportable(mixed $params)Turn on JPG exportable for widget, the parameters could be boolean or an extra export settings for that widget
->xlsxExportable(mixed $params)Turn on XLSX exportable for widget, the parameters could be boolean or an extra export settings for that widget
->csvExportable(mixed $params)Turn on CSV exportable for widget, the parameters could be boolean or an extra export settings for that widget

Trigger Exporting #

Now, you have set up your exporting engines and also turn on exportable capability in your widget, now you can do trigger exporting

class MyDashboard extends Dashboard
{
    protected function widgets()
    {
        return [
            MyChart::create()->pdfExportable(true),
            Button::create()->text("Export to PDF")->onClick(
                Client::widget("MyChart")->exportToPDF()
            )
        ];
    }
}

Code explanation:

  1. You have MyChart widget with ability to export to PDF
  2. You have a button with text "Export to PDF".
  3. When user click to that button, it will tell the widget MyChart to export to PDF.
  4. The file will be generated and sent to browser to download

Custom Parameters #

In some case, you want to trigger exporting with some custom parameters, you can do:

class MyDashboard extends Dashboard
{
    protected function widgets()
    {
        return [
            MyChart::create()->pdfExportable(true),
            Button::create()->text("Export to PDF")->onClick(
                Client::widget("MyChart")->exportToPDF(["key"=>"value"]) //You have some parameters
            )
        ];
    }

}

You can catch those parameter with onExporting event in MyChart:

class MyChart extends ColumnChart
{
    ...
    protected function onExporting($params)
    {
        $value = $params["value"];

        //Base on parameters received, you can do custom settings for your chart
        //before it getting exported.

        return true; //Return true to allow exporting, return false will cancel exporting
    }
    ...
}

Dashboard Export #

Settings #

To turn on the exporting feature in Dashboard, you do:

class MyDashboard extends Dashboard
{
    protected function onCreated()
    {
        $this
        ->pdfExportable(true)    //Allow exporting dashboard to PDF
        ->jpgExportable(true)    //Allow exporting dashboard to JPG
        ->pngExportable(true)    //Allow exporting dashboard to PNG
        ->xlsxExportable(true)   //Allow exporting dashboard to XLSX
        ->csvExportable(true);   //Allow exporting dashboard to CSV
    }
}

Extra exporting settings can be applied:

class MyDashboard extends Dashboard
{
    protected function onCreated()
    {
        // Turn on exporting to pdf and provide extra settings for the export
        $this->pdfExporting([
            "format"=>"A4",
            "margin"=>[
                "top"=>"1in",
                "bottom"=>"1in",
                "left"=>"1in",
                "right"=>"1in",
            ],
        ]);
    }
}

Trigger Exporting #

In order to export the dashboard to pdf, you use exportToPDF() from client

class MyDashboard extends Dashboard
{
    protected function onCreated()
    {
        $this->pdfExportable(true);
    }

    protected function widgets()
    {
        return [
            Button::create("Export dashboard to PDF")->onClick(
                Client::dashboard($this)->exportToPDF()
            )
        ]
    }
}

Custom Parameters #

Sometime, you want to export dashboard with some custom parameters, you can do

class MyDashboard extends Dashboard
{
    protected function onCreated()
    {
        $this->pdfExporting(true);
    }

    protected function onExporting($params)
    {
        $value = $params["key"];

        // Here, base on value you receieved from $params
        // you can make any custom change to dashboard
        // before it gets exported.
        
        return true; //Return true to approve exporting, return false will cancel exporting
    }

    protected function widgets()
    {
        return [
            Button::create("Export dashboard to PDF")->onClick(
                Client::dashboard($this)->exportToPDF(["key"=>"value"])
            )
        ]
    }
}

Customize Exported Content #

By default, Dashboard will export only the view of the dashboard or widget you want to export. However, in many cases you want to change the exported view a little such as: adding header, description for the exported content.

Both Dashboard and Widget have a public method called exportedView() which you can derive and alternate the exported content.

Example:

use \koolreport\dashboard\containers\Html;

class MyWidget extends \koolreport\dashboard\widgets\Table
{
    ...
    public function exportedView($params)
    {
        //We add header on top of Widget content
        return  Html::div()->class("text-center")->sub([
                    Html::h1("Big Center Header")
                ]).
                $this->view(); // This is widget content
    }
    ...
}

The same way of customizing exported content is applied for dashboard class.

Get started with KoolReport

KoolReport will help you to construct good php data report by gathering your data from multiple sources, transforming them into valuable insights, and finally visualizing them in stunning charts and graphs.