• Properties
• Methods
• View file
  • Naming
  • Receive parameters
  • Dashboard reference
• Ajax form submit
• Javascript submit
• Notes

CustomBoard

CustomBoard class is derived from Dashboard. While Dashboard may limit you to design your own dashboard interface, CustomBoard allows you to define your own graphic interface, virtually no limitation.

CustomBoard is designed following MVC pattern which has a controller class with list of actions. In each action, data query and business logic will be performed. After done, processed data will be sent to view to render.

Example:

This is controller class

<?php
//OfficeBoard.php
use \koolreport\dashboard\CustomBoard;

class OfficeBoard extends CustomBoard
{
    protected function actionIndex()
    {
        $offices = AutoMaker::table("offices")->run();
        $this->renderView("index",[
            "offices"=>$offices
        ]);
    }
}

Here comes the view index.view.php

//index.view.php

<div>
    <h1>My office list</h1>
    <?php
    \koolreport\widgets\koolphp\Table::create([
        "dataSource"=>$this->params()["offices"];
    ])
    ?>
</div>

Now we can add our OfficeBoard to Application

class App extends Application
{
    ...
    protected function sidebar()
    {
        return [
            "Office List"=>OfficeBoard::create()
        ];
    }

}

Properties #

Note: Those above properties follows this code rules.

Examples:

use \koolreport\dashboard\CustomBoard;

class MyDashboard extends CustomBoard
{
    protected function onCreated()
    {
        //From now, the CustomBoadrd will look for view file inside "views" folder.
        $this->viewFolder(__DIR__."/views");
    }
}

Methods #

Examples:

use \koolreport\dashboard\CustomBoard;

class MyDashboard extends CustomBoard
{
    protected function actionIndex($request, $response)
    {
        //Suppose you have a view fle Anyview.view.php
        $this->renderView("Anyview",[
            "key"=>"value"
        ]);
    }
}

View file #

Naming #

The view file is always suffixed with view.php. For example, if you would like to have view with name "bobby", you create file "bobby.view.php" and to render this view you do:

$this->renderView("bobby"); // Render view without parameter

$this->renderView("bobby"[
    "age"=>37
]); //Render view with parameters

Receive parameters #

When you pass parameters to the view, those parameters can be retrieved from $this->params() in the file view, for example:

<div>
    <b><?php echo $this->params()["age"]; ?></b>
</div>

Dashboard reference #

In the view, you can always refer to dashboard via $this->board(), for example:

class MyBoard extends CustomBoard
{
    ...
    public function getWelcome()
    {
        return "Welcome to CustomBoard";
    }
    ...
}

In this view you can call getWelcome() like following

<div>
    <h1><?php echo $this->board()->getWelcome(); ?></h1>
</div>

Ajax form submit #

CustomBoard has a special mechanism to allow client-side form to be posted to CustomBoard action via AJAX. You just need to mark the form with method="ajax" to trigger this mechanism. Also you can choose which action of CustomBoard to handle the request by setting "action" property of the form.

Example:

You have a SaleBoard.php which derived from CustomBoard

<?php

use \koolreport\dashboard\CustomBoard;

class SaleBoard extends CustomBoard
{
    /**
     * Render index view with datepicker
     */
    protected function actionIndex($request, $response)
    {
        $this->renderView("index");
    }

    /**
     * Receive the data posted from client, query data and send to result view
     */
    protected function actionProcess($request, $response)
    {
        $params = $request->params();
        $date = $params["datePicker"];

        $dataStore = AutoMaker::table("payments")
                    ->where("paymentDate",$date)
                    ->run();

        $this->renderView("result",[
            "dataStore"=>$dataStore
        ]);
    }
}

The SaleBoard.php has two view files index.view.php and result.view.php

<!-- index.view.php -->
<form method="ajax" action="process">
    <div>Please enter a date:</div>
    <?php koolreport\inputs\DateTimePicker::create([
        "name"=>"datePicker"
    ]);?>
    <button class="btn btn-primary">Submit</button>
</form>

<!-- result.view.php -->

<?php 
    $params = $this->params();
    $dataStore = $params["dataStore"];
?>

<?php \koolreport\widgets\koolphp\Table::create([
    "dataSource"=>$dataStore
]);?>

Code explanation:

1. On the first load, the actionIndex() will be called and index.view.php will be rendered.
2. In the index.view.php, there is a form with a DateTimePicker and a submit button.
3. The form inside index.view.php has been marked with method="ajax" and action="process", meaning that when user hit Submit button, the form data will be posted via ajax and be handled at actionProcess()
4. At actionProcess() you receive all parameters from $request->params() and get the date selection from $params["datePicker"]. You make query to get data from database and pass result as parameter to the view result.view.php
5. In the result.view.php, you get result $dataStore from $this->params() and feed into your table to show result.
6. In this example we use AutoMaker as example datasource. The query code will translate into SQL statement SELECT * FROM payments WHERE paymentDate='@date'. The run() method at the end will trigger data pulling from database.

Javascript submit #

Above, we learn how to submit a form to a dashboard's action. Alternatively, you can use javascript action($action, $params) to call any dashboard's action. For example:

<button onclick="action('index');">Go to Index</button>

In some cases, you want to add some parameters, you do like following example:

//Perform ajax call to actionProcess() with $request containing parameters
action('process',{
    datePicker:'2021-01-01'
});

Notes #

There are some notes about CustomBoard that you need to know

1. CustomBoard acts like MVC framework with supported modern singe page technology
2. You can not use dashboard's widgets inside view of CustomBoard due to different mechanism
3. You can freely use KoolReport widgets inside view of CustomBoard
4. You can construct your own html interface inside CustomBoard
5. Using CustomBoard, you sacrifice the quickness and easiness of Dashboard's widgets for the freedom of creativity.

Thank you very much!