• Overview
• Define an action
  • Properties
  • title
  • icon
  • showOnActionBox
  • showOnTable
  • showOnDetail
  • needConfirmation
  • confirmModal
  • emptySelectionWarning
  • checkEmptySelection
• Action Form
  • ModalForm
• Required fields
  • Customized list of fields
  • Access data in handle() method
• Manual Handle
• Register action
• Built-in actions
  • Inline editing
  • ExportAction

---

Actions

Overview #

One of the greatest core features of Admin Panel is to allow you to create custom actions on records of resource.

Define an action #

<?php
use \koolreport\dashboard\admin\actions\Action;

class MyAction extends Action
{
    protected function onCreated()
    {
        $this->title("My Action")
        ->icon("far fa-users")
        ->showOnActionGroup(true)
        ->showOnDetail(true)
        ->needConfirmation(true)
        ->confirmText("Do you want to take this action?")
    }

    /**
     * Perform actions
     * @param ActionForm $form Form object that contains all widgets
     * @param DataStore $models Contains list of selected records to be actioned on
     * @return INotification It could be null or an Inoti
     */
    protected function handle($form, $models) 
    {
        //You handle your action here, you have $form result and list of $models
        //in DataStore form.

        //Later you can return a notification like Note, Confirm or Alert
        return Note::success("Action is done!");
    }
}

Properties #

title #

Get/Set the title of action

$this->title("My Determined Action");

icon #

Get/Set the icon of action

$this->icon("far fa-users");

showOnActionBox #

Get/set whether this action will be shown in ActionBox

$this->showOnActionBox(true);

showOnTable #

Get/set whether this action will be shown in AdminTable

$this->showOnTable(true);

showOnDetail #

Get/set whether this action will be shown in DetailScreen

$this->showOnDetail(true);

needConfirmation #

Get/set whether this action will need confirmation before execute.

$this->needConfirmation(true);

confirmModal #

Get/set the confirm modal

$this->confirmModal()->type("danger");

emptySelectionWarning #

Get/set the selection note. This warning is appeared when user chooses an action without selecting any rows. You may set this property to null to disable the warning.

$this->emptySelectionWarning()
        ->type("warning")
        ->text("Please select some rows");

$this->emptySelectionWarning(null);// Disable warning

checkEmptySelection #

Get/set whether action should check no rows selection from user. When true, the emptySelectionWarning note will be shown when no rows are selected. When false, action will not check the none selections and carry out the action.

$this->checkEmptySelection(false); //Disable empty selection warning

Action Form #

You can make a form to request necessary information before taking actions of records. For example, you need to email list of users with custom title and content. To make a form that open before user take actions, you just need to provide list of inputs into form() method.

<?php
use \koolreport\dashboard\actions\Action;
use \koolreport\dashboard\inputs\TextBox;
use \koolreport\dashboard\inputs\TextArea;

use \koolreport\dashboard\notification\Note;

class MyAction extends Action
{
    ...
    protected function form()
    {
        return Action::modalForm([
            "Subject"=>TextBox::create("subject")->placeHolder("Subject"),
            "Body"=>TextArea::create("body")->placeHolder("Email body"),
        ]);
    }

    protected function handle($form, $models)
    {
        $emailSubject = $form->input("subject")->value();   //Get value from subject textbox
        $emailBody = $form->input("body")->value();         //Get value from body textarea

        //Now you have email subject and body from user input
        //You also have list user inside $models
        //You can start email now

        //Open a success note at client to notify user that we have email successfully.
        return Note::success("Email successfully");
    }
}

From above code, you see that we have provided a modal form with textbox for email subject and a textarea for email body inside form() method.

Later in the handle(), you will get the the $form object. You use this form to access the input from user.

ModalForm #

ModalForm is derived from Modal with form content. You can create the modal form simply with Action::modalForm() method like above example.

Below are properties

Example:

use \koolreport\dashboard\validators\RequiredFieldValidator;
use \koolreport\dashboard\validators\NumericValidator;

...
protected function form()
{
    return Action::modalForm([
        "Name"=>TextBox::create("name"),
        "Age"=>TextBox::create("age"),
    ])
    ->validators([
        RequiredFieldValidator::create()->inputToValidate("name"),
        NumericValidator::create()->inputToValidate("age"),
    ])
    ->type("info")
    ->confirmButtonText("Just do it")
    ->cancelButtonText("Hell no");
}

Required fields #

Customized list of fields #

If you need to customized the list of fields available for your action's handling, you can provide those list into fields() function of your action:

protected function fields()
{
    return [
        ID::create("customerNumber"),
        Text::create("customerName"),
        Text::create("customerEmail"),
    ];
}

If you do provide list of fields with fields() method, then the action will use default list of fields that you provide in your resource class.

Access data in handle() method #

protected function handle($form, $customers) 
{
    foreach($customers as $customer) {
        $name = $customer["customerName"];
        $email = $customer["customerEmail"];

        // You can do anything here
        // For example, send him an email
    }
}

Manual Handle #

By default, we will get selected records with all necessary information, storing them in a dataStore that we called $models. This $models will be sent to handle() method for you to make actions on those models.

However, if you feels that you need to take control of above process, you can override the manualHandle() to make your own query.

protected function manualHandle($form, $ids, $query) 
{
    //$form is available if you provide form.
    //$ids is an array of selected ids.
    //$query is original query

    //Here you can make your own query to handle requested actions.

    return Note::success("Handle is done!");
}

Register action #

To register action, you put your new action into list in actions() of Resource or Glass.

protectd function actions()
{
    return [
        MyAction::create(),
    ];
}

Built-in actions #

In Admin Panel, we have 3 basic actions that you can use inside actions():

use \koolreport\dashboard\admin\actions\DetailAction;
use \koolreport\dashboard\admin\actions\UpdateAction;
use \koolreport\dashboard\admin\actions\DeleteAction;
...
protectd function actions()
{
    return [
        DetailAction::create(),
        UpdateAction::create(),
        DeleteAction::create(),
    ];
}

1. The DetailAction will take user to detail screen to view detail information of a record.
2. The UpdateAction will take user to update screen to update information of a record.
3. The DeleteAction will delete the resource record.

Above code can be shorted to be like this:

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

We provide above static functions to Resource so that you can reduce the class name declaration with use statement

Inline editing #

If you wish to have inline editing/updating on list table, you can use the InlineEditAction

use \koolreport\dashboard\admin\actions\InlineEditAction;
...
protectd function actions()
{
    return [
        InlineEditAction::create(),
        ...
    ];
}

ExportAction #

If you need to export the data from resource's table, you can use ExportAction. When ExportAction is registered, it will be shown in the action box on top of resource's table. Users will be provided options to select the preferred range of data and preferred output format to export.

use \koolreport\dashboard\admin\actions\ExportAction;
...
protected function actions()
{
    return [
        ExportAction::create()
            ->formatOptions(["csv","xlsx","pdf","png","jpg"])
            ->rangeOptions(["selected-rows","current-page","all-pages"])
            ->defaultFormat("csv")
            ->defaultRange("current-page")
            ->fileName("Customers")
            ->csv([
                // CSV settings if needed
                "delimiter"=>";",
            ])
            ->xlsx([
                // Excel settings if needed
            ])
            ->pdf([
                // PDF settings if needed
            ])
            ->png([
                // PNG settings if needed
            ])
            ->jpg([
                // Jpg settings if needed
            ])
            ->modalType("primary")
            ->confirmButtonText("Export")
            ->cancelButtonText("Cancel")
        ...
    ];
}

The ExportAction comes with below properties

Note:

1. ExportAction requires you to setup ExportHandler in Application in order to work. Read more
2. The extra settings for those properties csv, xlsx, pdf, png, jpg can be found in here