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

Server Action Registration

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

$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:

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

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.

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

The optional actionCallback is a function with a single parameter:

var callback = function(res) {
}

The actionCallback res parameter is an object.

{
    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.

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.