• Bootstrap
  • General
  • Boostrap in a MVC framework
• Adding dashboards to sidebar
  • Sidebar grouped dashboards
  • 3rd level of menu
• Properties
• Methods
• Authentication
  • Enable Login page
  • Set user directly
• Authorization
  • App's access authorization
  • Permissions
• Security
  • CSRF Protection
  • App Key
• Assets
  • General usage
  • Auto-configure Assets with other MVC Frameworks
• Menu
  • Main menu
  • Top menu
  • Account menu
• Language
• Theme
• Events

---

Application

Bootstrap #

General #

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
{

}

Boostrap in a MVC framework #

When you use Dashboard Framework inside MVC frameworks like Yii2 or Laravel, you will put the bootstrap code inside an action of controller class. Some of the framework will try to send header after action completed, that sometimes causes error Header is already sent. To avoid this issue, you can put exit; at the end of action method to terminate the server response. For example:

    // Create Dashboard inside Yii2 action
    public function actionIndex()
    {
        App::create()->run();
        exit; // Terminate the response
    }

The same solution is applied to other frameworks like Laravel or Symfony.

Adding dashboards to sidebar #

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

use koolreport\dashboard\Application;

class App extends Application
{
    protected function sidebar()
    {
        //Provide list of dashboards on sidebar
        return [
            "Sale Report"=>SaleReport::create(),
            "Human Resource"=>HumanResource::create(),
        ];
    }
}

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

Sidebar grouped dashboards #

use \koolreport\dashboard\menu\Group;

class App extends Application
{
    protected function sidebar()
    {
        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 sidebar()
    {
        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
        ->appKey("any-unique-string-is-accepted")
        ->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"])
        ->jsonRender(false);
    }
}

//Set properties outside App class

App::create()
    ->appKey("any-unique-string-is-accepted")
    ->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"])
    ->jsonRender(false)
    ->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();

App Key #

App's key is an unique string for your app that will be used later by Dashboard's Framework to secure your session and cookie. Set the app's key is very simple with appKey property of Application.

use \koolreport\dashboard\security\CSRF;
class App extends Application
{
    //..
    protected function onCreated()
    {
        $this->appKey("any-unique-string");
    }
}

Another way to set appKey

App::create()
->appKey("any-unique-string")
->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"
        ];
    }
}

Alternatively, you can set assets directly in theme, more information

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;
    ...
}

Menu #

Main menu #

The main menu is on your left-hand side and it lists all available dashboards. By providing list of dashboards, the main menu will be populated automatically.

Click here to learn how to provide list of dashboards to the main menu.

Top menu #

Top menu is horizontal menu located on top of application. By default, there is no menu items. To make top menu appear, you provide list of menu item into topMenu() method:

use \koolreport\dashboard\menu\MenuItem;
use \koolreport\dashboard\menu\MegaMenu;
use \koolreport\dashboard\menu\Group;

use \koolreport\dashboard\Client;

class App extends Application
{
    ...
    protected function topMenu()
    {
        return [
            "Simple link"=>MenuItem::create()
                ->href("https://www.anywebsite.com")
                ->target("_blank"),

            "With Icon and Badge"=>MenuItem::create()
                ->href("https://www.example.com")
                ->icon("fa fa-book")
                ->badge(["NEW","danger"]),
            
            "Execute javascript"=>MenuItem::create()
                ->onClick("alert('hola')"),
            
            "Load Dashboard"=>MenuItem::create()
                ->onClick(Client::dashboard("SaleBoard")->load()),

            "Mega Menu"=>MegaMenu::create()->sub([
                "Group 1"=>Group::create()->sub([
                    "Item 11"=>MenuItem::create(),
                    "Item 12"=>MenuItem::create(),
                ]),
                "Group 2"=>Group::create()->sub([
                    "Item 21"=>MenuItem::create(),
                    "Item 22"=>MenuItem::create(),
                ]),
            ])            

            "Disabled Item"=>MenuItem::create()->disabled(true),    
        ];
    }
}

Account menu #

Account menu is located on top right of application and only shown when you we have user login. By default, account menu is provided with "Log out" menu item but you can customize all:

use \koolreport\dashboard\menu\MenuItem;
use \koolreport\dashboard\Client;

class App extends Application
{
    ...
    protected function accountMenu()
    {
        return [
            "Simple link"=>MenuItem::create()
                ->href("https://www.anywebsite.com")
                ->target("_blank"),

            "With Icon and Badge"=>MenuItem::create()
                ->href("https://www.example.com")
                ->icon("fa fa-book")
                ->badge(["NEW","danger"]),
            
            "Execute javascript"=>MenuItem::create()
                ->onClick("alert('hola')"),
            
            "Load Dashboard"=>MenuItem::create()
                ->onClick(Client::dashboard("SaleBoard")->load()),

            "Disabled Item"=>MenuItem::create()->disabled(true),
            
            "Logout"=>MenuItem::create()
                ->onClick(Client::logout()),
        ];
    }
}

Language #

In order to set language, we do:

use \koolreport\dashboard\Application;
use \koolreport\dashboard\languages\ES;

class App extends Application
{
    protected function onCreated()
    {
        $this->language(ES::create());
    }
}

Click here to learn more about language

Theme #

In order to set theme, we do:

use \koolreport\dashboard\Application;
use \koolreport\amazing\dashboard\Amazing;
use \koolreport\appstack\dashboard\AppStack;

class App extends Application
{
    protected function onCreated()
    {
        //$this->theme(Amazing::create());
        $this->theme(AppStack::create());
    }
}

Click here to learn more about themes.

Events #

Application emits events during its process and we can catch those events to make customize our application.

Learn more about Application's events