Actions // Statamic Docs

Defining an action

You may create an action using the following command, which will generate a class in the App\Actions namespace.

php please make:action

Basics

The most basic action should have a run method.

use Statamic\Actions\Action;
 
class Delete extends Action
{
    public function run($items, $values)
    {
        $items->each->delete();
 
        return trans_choice('Item deleted.|:count items deleted.', $items);
    }
}

The run method is for executing the task. You will be provided with a collection of $items, and any submitted $values (more about those later).

You may customize the outcome of the action by providing a response.

Redirects

If you want to redirect after your action completes, override the redirect method and return a route or URL:

public function redirect($items, $values)
{
    return route('some.where.over.the', $rainbow);
}

Downloads

To produce a download, override the download method and return a file path or download response:

public function download($items, $values)
{
    return storage_path('some/file.pdf');
}

Registering an Action

Any action classes in the App\Actions namespace will be automatically registered.

If you would like to store them elsewhere, you can manually register an action in a service provider by calling the static register method on your action class.

public function boot()
{
    Your\Action::register();
}

Setting a Title

Each action button will have an automatic name provided by the HasTitle trait that can be set with a static title() method on your action class.

public static function title()
{
    return __('That's Some Sweet Action');
}

Filtering Actions

You may limit which items an action can be applied to using the visibleTo method. For example, if you want your action to only be used by entries, you can return a boolean like this:

use Statamic\Contracts\Entries\Entry;
 
public function visibleTo($item)
{
    return $item instanceof Entry;
}

Best Practice

Don’t include authorization in your visibleTo method. Instead, use the authorize method below.

Authorizing Actions

Before any actions are run, Statamic will make sure the user is allowed to run them. You can return a boolean like this:

public function authorize($user, $item)
{
    return $user->can('edit', $item);
}

By default, there is no authorization.

Dangerous Actions

You can mark an action as dangerous, which will give it red text and more sinister looking confirmation dialog.

protected $dangerous = true;

Context

Each action may have additional contextual data passed to it depending on which listing its being used within. For example, you may find the collection handle when used inside an entry listing, or the asset container handle when used in an asset listing

$this->context; // ['collection' => 'blog']

You may find this useful when building confirmation dialog fields:

Adding Fields

By default, an action will prompt you with an “Are you sure?” dialog.

You’re free to add additional fields to the action by adding a $fields property with a fieldset-style definition. Each will be added to the confirmation dialog.

protected $fields = [
    'message' => [
        'type' => 'text',
        'validate' => 'required|min:40',
    ]
];

If you need more control over the fields, you can use the fieldItems method instead. Within this method, you can use $this->context. Then return the same array as described above.

protected function fieldItems()
{
    return [
        'message' => ['type' => 'text'],
    ];
}

The values entered into these fields when a user runs the action will be passed into the run method.

Responses

Within an action’s run method, you may return different things.

Void

Returning nothing will result in a generic success toast notification saying “Action Completed”.

public function run($values)
{
    // do something, but don't return anything
}

String

Returning a string will customize the toast notification text.

public function run($values)
{
    // do something
 
    return __('The thing was done.');
}

Array

You may return an array with a message key in it. The message will be shown in the toast notification. Any additional keys will be passed into the event handler, useful if you are implementing your own listing component.

public function run($values)
{
    // do something
 
    return [
        'message' => 'This will be in the toast.',
        'foo' => 'bar',
    ];
}

<data-list-bulk-actions ... @completed="completed" />

completed(success, response) {
  this.$toast.success(response.message);
  this.doSomethingWithFoo(response.foo);
}

Custom JavaScript Callback

You may return an array with a callback key in it. This should be an array with the name of the callback, and any arguments it should receive.

public function run($values)
{
    // do something
 
    return [
        'callback' => ['myCallback', 'arg1', 'arg2'],
    ];
}

You can provide the callback from your JavaScript.

Statamic.$callbacks.add('myCallback', function (foo, bar) {
  console.log(foo, bar); // "arg1", "arg2"
});

Hot Tip!

A common reason for wanting to use JavaScript here is to copy a value to the user’s clipboard. There’s a native callback you can use so you don’t need to write the JavaScript yourself:

return [
    'callback' => ['copyToClipboard', 'text to copy']
];

Disabling the toast

You may wish to disable the toast notification, perhaps if you are planning to trigger your own notification as part of your JavaScript callback. You can disable it by passing a value of false.

public function run($values)
{
    // do something
 
    return [
        'message' => false,
    ];
}

Actions