Actions and buttons

Sometimes a module needs to run an action over a record or a group of records. In an order, for example, you may need to change the order status, which also sends a notification to the courier. Custom buttons cover those cases. They are rendered in the record table, and clicking one sends a request to the server where you can run any action and return a message to the user.

Creating a button

php artisan admin:button ChangeOrderStatusButton

The command creates the button class in app/Admin/Buttons/ChangeOrderStatusButton.php. Subdirectories in the name become namespaces, admin:button Orders/SendInvoice creates App\Admin\Buttons\Orders\SendInvoice.

Registering a button

Assign the button to an admin model through the $buttons property. Buttons can also be returned by a buttons() method, or extended with setButtonsProperty($buttons).

app/Models/Order.php

use App\Admin\Buttons\ChangeOrderStatusButton;

class Order extends AdminModel
{
    protected $buttons = [
        ChangeOrderStatusButton::class,
    ];
}

Once registered, the button appears in the side panel of every record.

A button that can run over several records is placed in the action bar once records are checked.

Custom action in the action bar above selected records

Configuring the button

A button is a PHP class holding its properties and the methods that run when it is clicked.

app/Admin/Buttons/ChangeOrderStatusButton.php

namespace App\Admin\Buttons;

use Admin\Buttons\Button;

class ChangeOrderStatusButton extends Button
{
    public $type = 'button';

    // Name of the button on hover
    public $name = 'Send delivery email';

    // Bootstrap button class
    public $class = 'btn-default';

    // Font Awesome icon
    public $icon = 'fa-truck';
}

Type

Where the button is available depends on its type and on the methods it defines. The default type is button.

Type	Behaviour
`button`	Shown in the record side panel, runs `fire($row)`.
`action`	Shown in the side panel when it has `fire()`, and in the action bar of checked records when it has `fireMultiple()`.
`multiple`	Shown in the action bar of checked records, runs `fireMultiple($rows)`.

public $type = 'multiple';

// The action bar shows the button from 2 checked records
public $minimum = 2;

Class and colour

A Bootstrap button class: btn-default, btn-primary, btn-success, btn-warning, btn-danger.

public $class = 'btn-success';

Running the action

fire runs the action over a single record clicked in the side panel. fireMultiple runs over the checked records. Both return a response in the form of a message or your own component.

app/Admin/Buttons/ChangeOrderStatusButton.php

use Admin\Eloquent\AdminModel;
use Admin\Buttons\Button;
use Illuminate\Support\Collection;

class ChangeOrderStatusButton extends Button
{
    public function __construct($row)
    {
        $this->class = $row->status == 'new' ? 'btn-success' : 'btn-default';

        $this->active = $row->status == 'new';
    }

    public function fire(AdminModel $row)
    {
        $row->update(['status' => 'sent']);
        $row->notify(new SendOrderNotification($row));

        return $this->message('The order has been sent.');
    }

    public function fireMultiple(Collection $rows)
    {
        $rows->each->update(['status' => 'sent']);

        return $this->success($rows->count().' orders have been sent.');
    }
}

In __construct you can change the button for the record passed to it. $active = false hides the button for that record, and the server refuses to run it for the record.

Message title and text

To return plain text or HTML, use one of message, success, error or warning.

return $this->title('Order sent')
            ->message('The courier has been notified.');

Redirect

return $this->redirect('https://example.com/orders');

A RedirectResponse returned from fire() works the same way:

return redirect()->route('orders.print', $row);

New window

return $this->open('https://example.com/orders/print');

Open a record

open() with a model opens that record in a modal instead of a URL.

public function fire(AdminModel $row)
{
    $invoice = $row->createInvoice();

    return $this->open($invoice);
}

Custom Vue component

return $this->title('Order statistics')
            ->component('OrderStats.vue');

Create the component with php artisan admin:component OrderStats and choose the button component type. Components are resolved as described in component directories, e.g. component('orders/OrderStats.vue') for a subdirectory.

Actions with a confirmation

The question method receives the first request and returns a confirmation as a message or a component. Once confirmed, fire or fireMultiple runs. The example below asks a question through a component with an input, whose value is then sent to fire.

app/Admin/Buttons/PostponeDelivery.php

public function question(AdminModel $row)
{
    return $this->title('Postpone delivery')
                ->component('PostponeDelivery.vue', [
                    'order' => $row,
                ]);
}

public function fire(AdminModel $row)
{
    $row->update(['delivery_at' => request('date')]);

    return $this->success('Delivery postponed to '.request('date').'.');
}

resources/views/admin/components/buttons/PostponeDelivery.vue

<template>
    <div>
        <p>Order no. {{ data.order.number }}</p>
        <label>New delivery date</label>
        <input type="date" v-model="request.date" class="form-control">
    </div>
</template>

<script>
export default {
    props: ['model', 'row', 'rows', 'request', 'data'],
};
</script>

The second argument of component($component, $data) passes data available in the Vue component through the data prop.

Multi-step actions

action('method') in a response makes the next confirmation call that method of the button.

app/Admin/Buttons/SyncOrdersButton.php

public function question(AdminModel $row)
{
    return $this->warning('Download orders from the e-shop?')->action('confirmSync');
}

public function confirmSync(AdminModel $row)
{
    $count = $row->syncOrders();

    return $this->success("Synchronized {$count} orders.");
}

Getting started

Upgrade guide

Admin interface

Validation

Frontend

Website

Actions and buttons

Creating a button

Registering a button

Configuring the button

Type

Class and colour

Running the action

Message title and text

Redirect

New window

Open a record

Custom Vue component

Actions with a confirmation

Multi-step actions

​Creating a button

​Registering a button

​Configuring the button

​Type

​Class and colour

​Running the action

​Message title and text

​Redirect

​New window

​Open a record

​Custom Vue component

​Actions with a confirmation

​Multi-step actions

Creating a button

Registering a button

Configuring the button

Type

Class and colour

Running the action

Message title and text

Redirect

New window

Open a record

Custom Vue component

Actions with a confirmation

Multi-step actions