• Bootstrap
• Adding dashboards
  • Grouped dashboards
  • 3rd level of menu
• Properties
• Methods
• Authentication
  • Enable Login page
  • Set user directly
• Authorization
  • App's access authorization
  • Permissions
• Security
  • CSRF Protection
• Assets
  • General usage
  • Auto-configure Assets with other MVC Frameworks
• Language
• Theme

Application

Bootstrap #

Application is the main entrant to start KoolReport Dashboard

Bootstrap the application

//index.php

 //Load composer autoload will load koolreport/core/autoload.php
require_once "vendor/autoload.php";

require_once "App.php";

App::create()->run();

// App.php
use \koolreport\dashboard\Application;

class App extends Application
{

}

Adding dashboards #

You need to provide list of dashboards to the dashboards() method like following.

class App extends Application
{
    protected function dashboards()
    {
        return [
            "Home"=>HomeBoard::create(),
            "Sale"=>SaleBoard::create(),
        ];
    }
}

Above example will produce 2 dashboards Home and Sale appearing on the menu of application. Learn how to create a dashboard.

Grouped dashboards #

use \koolreport\dashboard\menu\Group;

class App extends Application
{
    protected function dashboards()
    {
        return [
            "Home"=>HomeBoard::create(),
            "Sale Reports"=>Group::create()->icon("fa fa-line-chart")->sub([
                "Overview"=>SaleOverviewBoard::create(),
                "Main Products"=>MainProductBoard::create(),
            ]),
            "Cost Reports"=>Group::create()->icon("fa fa-pie-chart")->sub([
                "Overview Cost"=>CostOverviewBoard::create(),
                "BreakDown Cost"=>BreakDownCostBoard::create(),
            ])
        ];
    }
}

3rd level of menu #

You can add another layers of menu breakdown which called Section

use \koolreport\dashboard\menu\Section;
use \koolreport\dashboard\menu\Group;

class App extends Application
{
    protected function dashboards()
    {
        return [
            "Home"=>HomeBoard::create(),
            "Sale and Cost"=>Section::create()->sub([
                "Sale Reports"=>Group::create()->icon("fa fa-line-chart")->sub([
                    "Overview"=>SaleOverviewBoard::create(),
                    "Main Products"=>MainProductBoard::create(),
                ]),
                "Cost Reports"=>Group::create()->icon("fa fa-pie-chart")->sub([
                    "Overview Cost"=>CostOverviewBoard::create(),
                    "BreakDown Cost"=>BreakDownCostBoard::create(),
                ])
            ])
        ];
    }
}

Properties #

Note: Those above properties follows this code rules.

Examples:

//Set property within App class:
class App extends Application
{
    protected function onCreated()
    {
        $this
        ->title("My Dashboard")
        ->logo("<b>My Dashboard</b>")
        ->favicon("images/superman.ico")
        ->footerLeft("Dashboard@KoolReport")
        ->footerRight("Powered by KoolReport")
        ->csrf(\koolreport\dashboard\security\CSRF::create())
        ->css("extra.css") //->css(["extra1.css","extra2.css"])
        ->js("extra.js") //->js(["extra1.js","extra2.js"]);
    }
}

//Set properties outside App class

App::create()
    ->title("My Dashboard")
    ->logo("<b>My Dashboard</b>")
    ->favicon("images/superman.ico")
    ->footerLeft("Dashboard@KoolReport")
    ->footerRight("Powered by KoolReport")
    ->csrf(\koolreport\dashboard\security\CSRF::create())
    ->css("extra.css") //->css(["extra1.css","extra2.css"])
    ->js("extra.js") //->js(["extra1.js","extra2.js"])
    ->run();

Methods #

Authentication #

Enable Login page #

By default, any one can access the dashboard. If you would like to have dashboard's login, you do as following:

use \koolreport\dashboard\Application;
use \koolreport\dashboard\pages\Login;
use \koolreport\dashboard\User;

class App extends Application
{
    protected function login()
    {
        return  Login::create()
                ->authenticate(function($username,$password){
                    if($username==="admin@example.com" && $password==="admin_password")
                    {
                        // If authenticated, return User object
                        return User::create()
                            ->id(1)
                            ->name("Admin")
                            ->avatar("avatars/8.jpg")
                            ->roles(["admin"]);
                    }
                    // If unauthenticated, return null
                    return null;
                });
    }
}

Basically, to turn on authentication feature, we will need to provide Login page with authenticate() method. In the anonymous function provided inside authenticate(), we will receive $username and $password as parameters, we will check whether they are valid login. If they are correct, we will return User object. If not, we will return null value indicating that login is failed.

Set user directly #

If you establish dashboard as a part of your existed application, there is high chance that you have login system already and when authenticated user access dashboard, we do not want user to do login again. In this case, we can set user like following:

//index.php

App::create()
->user(
    User::create()
    ->id($id)
    ->name($name)
    ->avatar("avatars/user.jpg")
    ->roles(["user"])
)
->run();

By providing user object, the dashboard app will bypass the Login page.

Authorization #

App's access authorization #

allowAccess() method is the front gate keeper of authorization. return false; from the method will block the request and return Unauthorized response. We can use the method to pre-check the request received and user's permission to decide whether request is authorized to go through.

use \koolreport\dashboard\Application;

class App extends Application
{
    protected function allowAccess($request)
    {
        $user = $request->user();
        $route = $request->route();
        $action = $request->action();
        $params = $request->params();

        //Allow true to allow access and false otherwise
        return true; 
    }
}

Permissions #

By deriving the permission() method and provide Permit object, we are able to set authorization rules for users and requests. For more information of Permit class, please click here.

use \koolreport\dashboard\Application;

class App extends Application
{
    protected function permission()
    { 
        return Permit::create();
    }
}

Security #

CSRF Protection #

Cross-site request forgeries are a type of malicious exploit whereby unauthorized commands are performed on behalf of an authenticated user. Dashboard Framework makes it easy to protect your dashboard from Cross-Site Request Forgery (CSRF).

To enabled CSRF you only need to add csrf() method inside your application class and return the CSRF class like following:

use \koolreport\dashboard\security\CSRF;
class App extends Application
{
    //..
    protected function csrf()
    {
        return CSRF::create();
    }
}

Create your own csrf token:

use \koolreport\dashboard\security\CSRF;
class App extends Application
{
    //..
    protected function csrf()
    {
        return CSRF::create()
                ->name("_token")
                ->token(function(){
                    return "Your own generated token";
                });
    }
}

The name is the name of csrf token posted from client, the default value is "_token" but you can change to any value.

If you use dashboard inside Laravel and would like to use laravel-compatible CSRF, you do:

use \koolreport\dashboard\security\CSRF;
class App extends Application
{
    //..
    protected function csrf()
    {
        return CSRF::create()
                ->name("_token")
                ->token(csrf_token());
    }
}

Another way of set csrf token is when you create application:

App::create()
->csrf(\koolreport\dashboard\security\CSRF::create())
->run();

Assets #

The assets of dashboard like js file or css file may be located inside prohibited folder like "vendor" so the browser may not access them. So we will need to set a public place whether assets will be populated to.

General usage #

In order to set assets location, you only need to provide assets() method inside Application and return assets settings:

class App extends Application
{
    protected function assets()
    {
        return [
            "url"=>"/assets",
            "path"=>"../../public/assets"
        ];
    }
}

Auto-configure Assets with other MVC Frameworks #

Laravel:

class App extends Application
{
    use \koolreport\dashboard\inside\Laravel;
    ...
}

CodeIgniter:

class App extends Application
{
    use \koolreport\dashboard\inside\CodeIgniter;
    ...
}

Yii2:

class App extends Application
{
    use \koolreport\dashboard\inside\Yii2;
    ...
}

Language #

In order to set language, we do:

use \koolreport\dashboard\Application;

class App extends Application
{
    use \koolreport\dashboard\languages\ES;

}

Theme #

In order to set theme, we do:

use \koolreport\dashboard\Application;

class App extends Application
{
    use \koolreport\dashboard\amazing\Theme;

}

Currently, Amazing theme is default and the only theme of Dashboard app. This Amazing theme will be used regardless you set theme. In the future, more themes will be available.