---
title: 'Grav Admin Media Actions Plugin'
url: 'https://www.twelvetone.tv/docs/developer-tools/grav-plugins/grav-admin-media-actions-plugin'
markdown: 'https://www.twelvetone.tv/docs/developer-tools/grav-plugins/grav-admin-media-actions-plugin.md'
date: '2026-09-25'
description: 'A plugin that extends Grav with an API for adding actions to media items in the page media bin. Other'
taxonomy:
  category:
    - docs
  devtype:
    - mit
---

[](#)  [ Home ](https://www.twelvetone.tv/docs/)     [ Developer Tools ](https://www.twelvetone.tv/docs/developer-tools)     [ Grav Plugins ](https://www.twelvetone.tv/docs/developer-tools/grav-plugins)      Grav Admin Media Actions Plugin    

This product is in active development and has been released under the [MIT license](https://opensource.org/licenses/MIT).

A plugin that extends Grav with an API for adding actions to media items in the page media bin.

Other plugins can register media item actions and react to commands on both the client and the server.

# Features

![](https://www.twelvetone.tv/docs/user/pages/03.developer-tools/06.grav-plugins/06.grav-admin-media-actions-plugin/media%20with%20sample%20actions.png)![](https://www.twelvetone.tv/docs/user/pages/03.developer-tools/06.grav-plugins/06.grav-admin-media-actions-plugin/plugin%20settings.png)

## Server Action Registration

Clients should obtain the *media-actions* service and then register actions.

```php
$mediaActions = $this->grav['media-actions'];

// Sample Action
/**
* @param $actionId A unique id for the action.  Must be a valid Javascript function name.
* @param $caption The caption for the action.  Used for the tooltip.
* @param $icon The font-awesome icon name.  The 'fa-' prefix is optional.
* @param $handler A handler for the action. (page, mediaName, payload) => object
*/
$mediaActions->addAction("Action1", "Action 1", "fa-arrows", function ($page, $mediaName, $payload) {
    return "ok";
});
```

The return value is a JSON encodable object to be sent back to the page's Javascript fetch invocation under the key *result*.

## Client Action Registration

### Default client handler

The default handler on the page simply calls the action handler on the server with an empty string as the payload.

This is the equivalent stub for an action with ID *Action1*:

```php
function onMediaAction_Action1(actionId, mediaName, mediaElement) {
    submitMediaAction(actionId, mediaName, "");
}
```

To remove the mediaElement from the page without refreshing, call $(mediaElement).remove();

### Submitting a media action

The method *submitMediaAction* can be called from anywhere in your Javascript to post a request. This is normally called from the client handler after form input, validating, confirmation, etc.

```php
submitMediaAction(actionId, mediaName, payload, callback, modal);
```

The optional actionCallback is a function with a single parameter:

```javascript
var callback = function(res) {
}
```

The actionCallback *res* parameter is an object.

```json
{
    error:"A Boolean value",
    result:"The JSON object returned from the handler"
}
```

### Show a form on the client

If a client wants to show a form and/or post custom data to the server's handler, a Javascript function must be declared using a function called *onMediaAction\_XXX* where *XXX* is the registered actionID.

```php
function onMediaAction_Action1(actionId, mediaName, mediaElement) {
    // Use your preferred form API
    showForm().then(result => {
        if (!result.cancel){
            val actionCallback = function(r) {
                if (!r.error){
                    closeForm();
                }
            };
            _submitMediaAction(actionId, mediaName, '{ "field1":"value1", "field2":"value2" }', actionCallback);
        }
    });
}
```

# Issues

No known issues.

 [ ](https://www.twelvetone.tv/docs/developer-tools/grav-plugins/grav-stackeditor-plugin) [](https://www.twelvetone.tv/docs/developer-tools/grav-plugins/grav-admin-media-move-plugin)

---

## Navigation

- Parent: [Grav Plugins](https://www.twelvetone.tv/docs/developer-tools/grav-plugins.md)
- Previous: [Grav Stackeditor Plugin](https://www.twelvetone.tv/docs/developer-tools/grav-plugins/grav-stackeditor-plugin.md)
- Next: [Grav Admin Media Move Plugin](https://www.twelvetone.tv/docs/developer-tools/grav-plugins/grav-admin-media-move-plugin.md)