• Overview
• Define Resource
  • Minimum settings
  • Alternate query
  • Fields
  • Filters
  • Actions
  • Glasses
  • Relations
  • Highlights
• Register Resource
• Advanced data manipulation
  • Create Record
  • Update Record
  • Delete Record
• Resource events

Resources

Overview #

Admin Panel is an powerful administration dashboard so the main functionality of it is to manage your underlying database. Admin Panel complete this by providing you a Resource class that corresponds to each table in your database.

Define Resource #

Minimum settings #

<?php

use \koolreport\dashboard\admin\Resource;
use \koolreport\dashboard\fields\ID;
use \koolreport\dashboard\fields\Text;

class Customer extends Resource
{
    protected function onCreated()
    {
        $this
        ->manageTable("customers")      // Manage the table "customers"
        ->inSource(AutoMaker::class);   // In AutoMaker datasource
    }

    protected function fields()
    {
        return [
            ID::create("customerNumber"),   // Define customerNumber as ID column
            Text::create("customerName"),   // Define "customerName" as Text
        ];
    }
}

Above is a minimum settings of an Resource, we specify the name of table that it manages with manageTable() method and the name of datasource class with inSource() method. The AutoMaker is just a MySQL data source class. If you have not known about how to create datasource, you can read more here.

In the fields() method, we provide list of all fields needed to be shown in admin table.

Alternate query #

By default, Resource will manage all rows in specified table in datasource. However, if we need to alternate the default query, we can use the query() method.

Example 1: Manage only those customers with creditLimit is greater than 10,000.

<?php

use \koolreport\dashboard\admin\Resource;
use \koolreport\dashboard\fields\ID;
use \koolreport\dashboard\fields\Text;

class Customer extends Resource
{
    protected function onCreated()
    {
        $this
        ->manageTable("customers")      // Manage the table "customers"
        ->inSource(AutoMaker::class);   // In AutoMaker datasource
    }

    protected function query($query)
    {
        return $query->where("creditLimit",">",10000);
    }
}

Example 2: Join with other table to get more information

<?php

use \koolreport\dashboard\admin\Resource;
use \koolreport\dashboard\fields\ID;
use \koolreport\dashboard\fields\Text;
use \koolreport\dashboard\fields\Number;

class Customer extends Resource
{
    protected function onCreated()
    {
        $this
        ->manageTable("customers")      // Manage the table "customers"
        ->inSource(AutoMaker::class);   // In AutoMaker datasource
    }

    protected function query($query)
    {
        return 
            $query
            ->join("payments","customers.customerNumber","=","payments.customerNumber")
            ->groupBy("customers.customerNumber")
            ->sum("payments.amount")->alias("totalPayment")
            ->select("customers.customerNumber","customerName");
    }

    protected function fields()
    {
        return [
            ID::create("customerNumber"),   // Define customerNumber as ID column
            Text::create("customerName"),   // Define "customerName" as Text
            Number::create("totalPayment"), // Define totalPayment as Number
        ];
    }    
}

Fields #

As you can see in above example, we have define some fields in fields() method of Resource. The ID field is always required in any resources. Beside ID and Text, we have many field types.

use \koolreport\dashboard\fields\ID;
use \koolreport\dashboard\fields\Text;
use \koolreport\dashboard\fields\Image;
use \koolreport\dashboard\fields\DateTime;

class Post extends Resource 
{
    ...
    protected function fields()
    {
        return [
            ID::create("post_id"),
            Text::create("title"),
            DateTime::create("created_at"),
            Image::create("image_file"),
        ];
    }
}

Explore list of Fields.

Filters #

You can provide a list of filters to filters() method of Resource. The provided filters will allow your users customize the query condition and draw out the wanted data.

Example:

class Post extends Resource 
{
    ...
    protected function filters()
    {
        return [
            CountrySelect::create(),
        ];
    }
}

Learn about creating Filter

Actions #

In Admin Panel, We provide 3 default actions which are DetailAction, UpdateAction, DeleteAction that have been added to application by default.

protected function actions()
{
    return [
        Resource::detailAction(),
        Resource::updateAction(),
        Resource::deleteAction(),
    ];
}

Beside those default actions, you can create your own action and add them to the list. Learn more about Actions.

Glasses #

Glasses are the ways we look at data. You can created many glasses to provide different views of your data and provided into glasses() method of resource.

protected function glasses()
{
    return [
        MostViewedPost::create(),
        TopComments::create(),
    ];
}

In glasses, we can alternate the query, changing the set of actions or filters.

Learn more about Glasses

Relations #

Each resource can have a relationship to other resources. Such as Customer resource can have many Order resource. In admin panel, you can provide the relationship of one resource to another in relations() method:

use \koolreport\dashboard\admin\Resource;

use \koolreport\dashboard\admin\relations\HasMany;

class Customer extends Resource
{
    /**
    * List of relations of Customer resource
    */
    protected function relations()
    {
        return [
            HasMany::resource(Order::class)
                ->link([
                    "customerNumber"=>"customerNumber"
                ]),
        ];
    }
}

Learn more about Relations

Highlights #

Highlights are simply a group of widgets (any widgets) you want to add on top of admin table. It could be metrics that show current status of business or application like number of new users, number of posts etc.

protected function highlights()
{
    return [
        NumberUserMetric::create(),
        UserByPayment::create(),
    ];
}

Learn more about Highlights

Register Resource #

The way to register your resource into Application is the same with the way a Dashboard is registered in Application.

<?php>

use \koolreport\dashboard\Application;

class App extends Application
{
    protected function sidebar()
    {
        return [
            "Customers"=>Customer::create()->icon("far fa-users"),
            ...
        ];
    }
}

Advanced data manipulation #

Create Record #

When a record of a resource is created the method createRecord() will be called with data of record will be created. You can override this method to provide your own way to create record for your specific resource.

    /**
     * Create a new record with data
     * @param mixed $data Data in form of associate to insert to database's resource
     * @return bool
     */
    public function createRecord($data)
    {
        $query = $this->getQuery()->insert($data);
        if($query->run()===false) {
            throw new \Exception("[SQL Error] ".$query->errorMessage()." : ".$query);
        }
        return true; // If action is success
    }

Update Record #

When resources are updated, the method updateRecord() will be called. You can override this methods to provide your own updating record procedure for your specific resource.

    /**
     * Handle update into database
     * @param mixed $ids List of id of rows needed to be updated
     * @param mixed $data The associate array data to update
     * @return bool Whether update is suceeeded
     */
    public function updateRecord($ids, $data)
    {
        $idColName = $this->getIDField()->colName();
        if($idColName===null) {
            throw new \Exception("ID field is required");
        }
        $query = $this->getQuery()->whereIn($idColName,$ids)->update($data);
        if($query->run()===false) {
            throw new \Exception("[SQL Error] ".$query->errorMessage()." : ".$query);
        }
        return true;
    }

Delete Record #

When a record is deleted, the application will call deleteRecord(), you can override this method to do your own deleting task for your specific resource.

    /**
     * Delete list of records with ids
     * @param mixed $ids List of ids of records to be deleted from DB
     * @return bool Whether action is successful
     */
    public function deleteRecord($ids)
    {
        $idColName = $this->getIDField()->colName();
        if($idColName===null) {
            throw new \Exception("ID field is required");
        }
        $query = $this->getQuery()->whereIn($idColName,$ids)->delete();
        if($query->run()===false) {
            throw new \Exception("[SQL Error] ".$query->errorMessage()." : ".$query);
        }
        return true;
    }

Resource events #

|Event|description| |onRecordDeleting|To be fired before resource performs deleting| |onRecordDeleted|To be fired after resource performs deleting| |onRecordUpdating|To be fired before resource performs updating| |onRecordUpdated|To be fired after resource performs updating|

Example:

class MyResource extends \koolreport\dashboard\admin\Resource
{
    ...
    protected function onRecordDeleting($params)
    {
        //List of ids of records to be deleted
        $ids = $params["id"];

        return true;// Allow deleting to be occurred
        //return false;
    }

    protected function onRecordDeleted($params)
    {
        $ids = $params["id"];
        var_dump($ids);
    }

    protected function onRecordUpdating($params)
    {
        //List of ids of records to be updated
        $ids = $params["id"];

        return true;// Allow updting to be occurred
        //return false;
    }

    protected function onRecordUpdated($params)
    {
        $ids = $params["id"];
        var_dump($ids);
    }
    ...

}