ACTIONS: Library functions for calling Craft CMS controllers from JavaScript

_actions.twig

{#
Call Craft web controller actions from JavaScript and display success/error notices

Usage:

Template:
{% include '@extras/_actions.twig' with {baseUrl: currentSite.baseUrl|trim('/', 'right')} only %}

See ACTIONS.md for details.

Note:
For simplicity and having just one file, all JS/HTML/CSS is included directly in each page's source code.

Consider including this template only on pages where it is needed.

Page template:
{% do _globals.set('requireActions', true) %}

...

Layout template:
{% if _globals.get('requireActions') %}
    {% include '@extras/_actions.twig' with {} only %}
{% endif %}
#}

{# Set to baseUrl of currentSite for multi-site projects #}
{% set baseUrl = baseUrl ?? parseEnv('$PRIMARY_SITE_URL') %}

<template id="actions-data"
          data-baseurl="{{ baseUrl }}"
          data-action-trigger="{{ craft.app.config.general.actionTrigger }}"
          data-csrf-token="{{ craft.app.request.csrfToken }}">
</template>

<div id="notices-wrapper" class="notices-wrapper"></div>

{% js %}

const actionData = document.getElementById('actions-data').dataset

window.Actions = {};

window.Actions.postAction = async function(action, data = {}, callback = null, params = {}) {
    const {
        timeout = 20000,
        handleFailuresInCallback = false,
        logLevel = 'none',
        indicatorSelector = null,
        indicatorClass = 'fetch-request'
    } = params;

    const abortController = new AbortController();
    let timeoutId;
    if (timeout > 0) {
        timeoutId = setTimeout(
            () => abortController.abort(),
            timeout
        );
    }

    const indicator = indicatorSelector ? document.querySelector(indicatorSelector) : null;
    if (indicator) {
        indicator.classList.add(indicatorClass);
    }

    try {
        const response = await fetch(actionData.baseurl + '/' + actionData.actionTrigger + '/' + action, {
            method: 'POST',
            headers: {
                'Accept': 'application/json',
                'Content-Type': 'application/json',
                'X-Requested-With': 'XMLHttpRequest',
                'X-Csrf-Token': actionData.csrfToken
            },
            body: JSON.stringify(data),
            signal: abortController.signal
        });

        if (logLevel === 'info') {
            console.log('Response: ', response);
        }

        if (timeout > 0) {
            clearTimeout(timeoutId);
        }

        if (indicator) {
            indicator.classList.remove(indicatorClass);
        }

        const {status, ok} = response;

        const contentType = response.headers.get("content-type");
        let body = null;
        if (contentType && contentType.includes("application/json")) {
            body = await response.json();
        } else {
            body = await response.text();
        }

        if (logLevel === 'info') {
            console.log(status, body);
        }

        const message = body.message || '';

        switch (status) {
            case 200:
                if (callback) {
                    callback(body, status, ok);
                } else {
                    Actions.notice({type: 'success', text: message});
                }
                break;

            case 400:
                if (handleFailuresInCallback) {
                    if (callback) {
                        callback(body, status, ok);
                    }
                    break;
                }

                throw new Error(message, {cause: 'Failure'});

            case 403:
                throw new Error('403 - Forbidden. Not logged in or insufficient permissions.', {cause: 'Failure'});

            default:
                throw new Error(status + ' - ' + (message || 'Unspecified Error'));
        }
    } catch (error) {
        if (logLevel === 'info' || logLevel === 'error') {
            console.log('Catch: ', error);
        }

        if (indicator) {
            indicator.classList.remove(indicatorClass);
        }

        let errorText = error.message;

        if (error.name === 'AbortError' || error.name === 'TimeoutError') {
            errorText = 'Request timed out.';
        } else if (error.name === 'TypeError' && error.message === 'Failed to fetch') {
            errorText = 'Could not connect to server.';
        }

        Actions.notice({type: 'error', text: errorText});
    }
}

window.Actions.errorsToString = function(errors, includeAttributeNames = false) {
    let errorMessage = '';
    for (const field in errors) {
        const messages = errors[field];
        errorMessage += (includeAttributeNames ? `${field.charAt(0).toUpperCase() + field.slice(1)}: ` : '') + messages.join(' ') + ' ';
    }
    return errorMessage;
}

window.Actions.notice = function(data) {
    if (data.text === '') {
        return;
    }
    window.dispatchEvent(new CustomEvent('actions.notice', {detail: data}));
}

window.Actions.success = function(message) {
    window.Actions.notice({type: 'success', text: message})
}

window.Actions.error = function(message) {
    window.Actions.notice({type: 'error', text: message})
}

class NoticesHandler {
    constructor() {
        this.notices = [];
        this.visible = [];
        this.noticeWrapper = document.getElementById('notices-wrapper');
        this.duration = 4000;
        window.addEventListener('actions.notice', (event) => this.add(event.detail));
    }

    add(notice) {
        notice.id = Date.now();
        this.notices.push(notice);
        this.fire(notice.id);
    }

    fire(id) {
        const notice = this.notices.find(notice => notice.id === id);
        if (notice) {
            this.visible.push(notice);
            this.render();

            const timeShown = this.duration * this.visible.length;
            setTimeout(() => {
                this.remove(id);
            }, timeShown);
        }
    }

    remove(id) {
        const index = this.visible.findIndex(notice => notice.id === id);
        if (index > -1) {
            this.visible.splice(index, 1);
            this.render();
        }
    }

    render() {
        this.noticeWrapper.innerHTML = '';

        this.visible.forEach(notice => {
            const noticeDiv = document.createElement('div');
            noticeDiv.classList.add('notices-item');

            noticeDiv.textContent = notice.text;

            noticeDiv.classList.add(notice.type === 'error' ? 'notice-error' : 'notice-success');

            noticeDiv.setAttribute('role', 'alert');
            noticeDiv.setAttribute('aria-live', 'assertive');

            noticeDiv.addEventListener('click', () => this.remove(notice.id));

            this.noticeWrapper.appendChild(noticeDiv);

            // stack on top, better if notices are placed at the bottom
            // this.noticeWrapper.insertBefore(noticeDiv, this.noticeWrapper.firstChild);

        });
    }
}

const noticesHandler = new NoticesHandler();
{% endjs %}

{% css %}
.notices-wrapper {
    pointer-events: none;
    position: fixed;
    inset: 0;
    z-index: 9999;
    display: flex;
    height: 100vh;
    width: 100vw;
    flex-direction: column;
    align-items: center; /* self-start, self-end for left/right */
    justify-content: flex-start; /* flex-end for bottom */
}


.notices-item {
    pointer-events: auto;
    cursor: pointer;
    z-index: 9999;
    margin: 0.5rem;
    display: flex;
    width: 24rem;
    align-items: center;
    justify-content: center;
    border-radius: 0.5rem;
    padding: 0.5rem 2rem;
    font-size: 0.875rem;
    line-height: 1.25rem;
    box-shadow: 4px 4px 16px -6px rgba(0, 0, 0, 0.5);
}


.notice-success {
    background-color: #16a34a; /* green-600 */
    color: white;
}

.notice-error {
    background-color: #dc2626; /* red-600 */
    color: white;
}

{% endcss %}

{# For fetch logic see: https://stackoverflow.com/questions/40248231/how-to-handle-http-code-4xx-responses-in-fetch-api #}
{# For notice component see: https://codepen.io/KevinBatdorf/pen/JjGKbMa?css-preprocessor=none, converted to vanilla JavaScript #}

ACTIONS.md

How to Use the Craft CMS Actions Twig Component

This documentation explains how to use the @extras/_actions.twig component in Craft CMS to call web controller actions via JavaScript and display success or error notices.

---

Component Overview

The Actions component allows you to make asynchronous requests to Craft CMS web controller actions and handle responses within your JavaScript code. Additionally, the component can display success or error notifications to users based on the outcome of the requests.

Table of Contents

• Usage Overview
• JavaScript Methods
  • window.Actions.postAction()
• Callback Signature
• Example Usage
  • Basic Success Example
  • Handling Failures in the Callback
  • Using Additional Data
  • Rendering Twig Templates
• Notices System

---

Usage Overview

To include the Actions component in your Craft CMS templates, use the following Twig code:

{% include '<pathToTemplates>/_actions.twig' with {...} only %}

Ensure that you include this component only on pages where it is necessary to avoid unnecessary JS/CSS loading.

---

JavaScript Methods

window.Actions.postAction()

This method allows you to send a POST request to a Craft CMS web controller action.

Syntax:

window.Actions.postAction(action, data = {}, callback = null, options = {})

Parameters:

• action (String): The route to the controller action (e.g., mymodule/mycontroller/myaction).
• data (Object): Parameters to be passed to the server. Can be anything that can be converted to valid JSON data.
• callback (Function): Function to handle the response. If null, a success notice will be displayed. It can be in the form:
  • () => {...}
  • data => {...}
  • (data, status, ok) => {...}
• options (Object, Optional): Additional settings for the request:
  • handleFailuresInCallback (Boolean, default: false): Set to true if you want to handle 400 responses in the callback.
  • timeout (Number, default: 20000): The number of milliseconds after which the request is aborted. Set to 0 for no timeout.
  • logLevel (String, default: 'none'): Set to 'info' to log responses for debugging purposes.
  • indicatorSelector (?String, default: null): A unique CSS selector of the HTML element to provide user feedback while the request is in progress, e.g. a spinner.
  • indicatorClass (String, default: fetch-request): The class to apply to the indicator element while the request is in progress.

---

Callback Signature

The callback provided to postAction is invoked with the following parameters:

function callback(data, status, ok) {
    // Handle response
}

The content of the data parameter depends on the content type returned from the server:

application/json:

This is the content type expected from the server, if the controller uses return asSuccess()/asModelSuccess()/asFailure()/asModelFailure().

The data parameter will be an object with the following properties:

• data (Object): Decoded JSON response from the server.

  • data.message: Success or error message returned from the server.
  • data.<key>: Additional data returned from the server.
  • data.<modelName>: Model data returned from server via ->asModelSuccess(). ->asModelFailure().
  • data.errors: Validation errors for models (if any).
  • data.cart: Commerce only: The cart data returned from Commerce actions like commerce/cart/update-cart.

• status (Number): HTTP status code (e.g., 200, 400).

• ok (Boolean): Indicates whether the request was successful (true for success, false for errors).

If the controller uses return $this->asJson(...), the data parameter will be the raw response from the server. In this case, the default failure/notice handling will not work, and you will have to handle errors manually.

text/html:

This is the content type returned from the server if the controller uses return $this->renderTemplate().

The data parameter will be a string containing the HTML content of the response. data.message is not present in this case.

other:

No specific handling is provided for other content types. The data parameter will be what response.text() returns. Gook luck!

Handling Errors

By default, the callback will only be called if the server responds with a status code "200", so that you don't have to care about any errors in your client code.

Errors will be (optionally) logged to console and displayed via an error notice:

• Controller runtime errors
• Connection failure (server not running)
• Non-existing controller actions
• Uncaught exceptions thrown in controller action
• Failed 'require...' constraints (like $this->requireLogin())
• Timed out requests
• Non-JSON responses (that should never happen...)
• Responses with status code 400, like failed controller actions (return $this->asFailure(...)), if handleFailuresInCallback = false (default)

Note that errors may be different depending on Craft environment (dev, staging, production, devMode=on/off).

Handling Success

User feedback for successful actions is up to you, you may call Action.notice({type:'success', text: data.message) inside your callback, or use any other method in order to provide visual feedback.

---

Example Usage

Basic Success Example

This example demonstrates sending a POST request and handling a success response.

Controller Action:

return $this->asSuccess('Action completed successfully');

JavaScript:

window.Actions.postAction("mymodule/mycontroller/myaction",
    {'id': 1234},
    (data) => {
        window.Actions.success(data.message);
    }
);

Handling Failures in the Callback

If you want to handle failures (status 400) directly in your callback, set handleFailuresInCallback to true in the options.

Controller Action:

if (...someErrorCondition...) {
    return $this->asFailure('An error occurred');
}
return $this->asSuccess('Action completed successfully');

JavaScript:

window.Actions.postAction("mymodule/mycontroller/myaction",
    {'id': 1234},
    (data, status, ok) => {
        if (!ok) {
            // cleanup...
            window.Actions.error(data.message);
            return;
        }
        // Do something with the data
        window.Actions.success(data.message);
        
    },
    { handleFailuresInCallback: true }
);

Using Additional Data

If the controller returns additional data, you can access it in the callback.

Controller Action:

return $this->asSuccess('Success message', ['foo' => 'bar']);

JavaScript:

window.Actions.postAction("mymodule/mycontroller/myaction",
    {'id': 1234},
    (data) => {
        // Do somthing with the data
        alert(data.message + ': Foo=' + data.foo);
    }
);

Rendering twig templates

HTML (Alpine JS Example)

<div x-html="searchResultsHtml"></div>

JavaScript:

window.Actions.postAction("mymodule/mycontroller/myaction",
    {
        variables: {
            q: this.q,
            section: this.section
        }
    },
    (html) => {
        this.searchResultsHtml = html;
    }
);

Controller Action:

return $this->renderTemplate(
   'path/to/your-twig-template.twig',
   Craft::$app->getRequest()->getRequiredBodyParam('variables')
);

For security reasons, this script does not support calling twig templates directly without using a controller action.

In case you want to write a generic controller action that renders any template passed as a parameter, make sure:

• to pass the template path as a hashed value
• to validate the path using Craft::$app->security->validateData($templatePath)

You may want to look into Alpine's Morph plugin for more intelligent DOM updates.

---

Using Indicator

Display an indicator while the request is in progress.

Requires an HTML element that can be queried by the CSS selector specified in indicatorSelector, where the presence of the class specified in indicatorClass in some way toggles visibility.

document.querySelector() is used internally to find the element, so technically the selector can be anything that works with this method, however using an id is best practice.

JavaScript:

window.Actions.postAction("mymodule/mycontroller/myaction",
    {'id': 1234},
    (data) => {
        // Do somthing with the data
        Actions.notice({ type: 'success', text: data.message });
    },
    {indicatorSelector: '#my-indicator', indicatorClass: 'my-indicator-class'}
);

HTML (Example)

<div id="my-indicator" class="styling-the-indicator">Loading...</div>

CSS (Example)

#my-indicator  {
    display: none;
}

#my-indicator.my-indicator-class {
    display: block;
}

---

Notices System

The Actions component includes a built-in system for displaying notifications to the user.

Triggering Notices:

• Use Actions.notice({ type: 'success', text: 'Your message here' }) to display a notification.

Types of notices:

• success
• error

Shortcuts

Actions.success(data.message)
Actions.error(data.message)