Extending client-side behavior¶

A simple controller example¶

First, create your HTML so that appears somewhere within the Wagtail admin.

<!-- Will log 'My controller has connected: hi' to the console -->
<div data-controller="my-controller">Hi</div>
<!-- Will log 'My controller has connected: hello' to the console, with the span element-->
<div data-controller="my-controller">
    Hello <span data-my-controller-target="label"></span>
</div>

Second, create a JavaScript file that will contain your controller code. This controller logs a simple message on connect, which is once the controller has been created and connected to an HTML element with the matching data-controller attribute.

// myapp/static/js/example.js

class MyController extends window.StimulusModule.Controller {
    static targets = ['label'];
    connect() {
        console.log(
            'My controller has connected:',
            this.element.innerText,
            this.labelTargets,
        );
    }
}

window.wagtail.app.register('my-controller', MyController);

Finally, load the JavaScript file into Wagtail’s admin with a hook.

# myapp/wagtail_hooks.py
from django.templatetags.static import static
from django.utils.safestring import mark_safe

from wagtail import hooks

@hooks.register('insert_global_admin_js')
def global_admin_js():
    return mark_safe(
        f'<script src="{static("js/example.js")}"></script>',
    )

You should now be able to refresh your admin that was showing the HTML and see two logs in the console.

A more complex controller example¶

Now we will create a WordCountController that adds a small output element next to the controlled input element that shows a count of how many words have been entered.

// myapp/static/js/word-count-controller.js
class WordCountController extends window.StimulusModule.Controller {
    static values = { max: { default: 10, type: Number } };

    connect() {
        this.setupOutput();
        this.updateCount();
    }

    setupOutput() {
        if (this.output) return;
        const template = document.createElement('template');
        template.innerHTML = `<output name='word-count' for='${this.element.id}' class='output-label'></output>`;
        const output = template.content.firstChild;
        this.element.insertAdjacentElement('beforebegin', output);
        this.output = output;
    }

    updateCount(event) {
        const value = event ? event.target.value : this.element.value;
        const words = (value || '').split(' ');
        this.output.textContent = `${words.length} / ${this.maxValue} words`;
    }

    disconnect() {
        this.output && this.output.remove();
    }
}
window.wagtail.app.register('word-count', WordCountController);

This lets the data attribute data-word-count-max-value determine the ‘configuration’ of this controller and the data attribute actions to determine the ‘triggers’ for the updates to the output element.

# models.py
from django import forms

from wagtail.admin.panels import FieldPanel
from wagtail.models import Page


class BlogPage(Page):
    # ...
    content_panels = Page.content_panels + [
        FieldPanel('subtitle', classname="full"),
        FieldPanel(
            'introduction',
            classname="full",
            widget=forms.TextInput(
                attrs={
                    'data-controller': 'word-count',
                    # allow the max number to be determined with attributes
                    # note we can use Python values here, Django will handle the string conversion (including escaping if applicable)
                    'data-word-count-max-value': 5,
                    # decide when you want the count to update with data-action
                    # (e.g. 'blur->word-count#updateCount' will only update when field loses focus)
                    'data-action': 'word-count#updateCount paste->word-count#updateCount',
                }
            )
        ),
    #...

This next code snippet shows a more advanced version of the insert_editor_js hook usage which is set up to append additional scripts for future controllers.

# wagtail_hooks.py
from django.utils.html import format_html_join
from django.templatetags.static import static

from wagtail import hooks


@hooks.register('insert_editor_js')
def editor_js():
    # add more controller code as needed
    js_files = ['js/word-count-controller.js',]
    return format_html_join('\n', '<script src="{0}"></script>',
        ((static(filename),) for filename in js_files)
    )

You should be able to see that on your Blog Pages, the introduction field will now have a small output element showing the count and max words being used.

A more complex widget example¶

For more complex widgets we can now integrate additional libraries whenever the widget appears in the rendered HTML, either on initial load or dynamically without the need for any inline script elements.

In this example, we will build a color picker widget using the Coloris JavaScript library with support for custom widget options.

First, let’s start with the HTML, building on the Django widgets system that Wagtail supports for FieldPanel and FieldBlock. Using the build_attrs method, we build up the appropriate Stimulus data attributes to support common data structures being passed into the controller.

Observe that we are using json.dumps for complex values (a list of strings in this case), Django will automatically escape these values when rendered to avoid common causes of insecure client-side code.

# myapp/widgets.py
import json

from django.forms import Media, TextInput

from django.utils.translation import gettext as _

class ColorWidget(TextInput):
    """
    See https://coloris.js.org/
    """

    def __init__(self, attrs=None, swatches=[], theme='large'):
        self.swatches = swatches
        self.theme = theme
        super().__init__(attrs=attrs);

    def build_attrs(self, *args, **kwargs):
        attrs = super().build_attrs(*args, **kwargs)
        attrs['data-controller'] = 'color'
        attrs['data-color-theme-value'] = self.theme
        attrs['data-color-swatches-value'] = json.dumps(swatches)
        return attrs

    @property
    def media(self):
        return Media(
            js=[
                # load the UI library
                "https://cdn.jsdelivr.net/gh/mdbassit/Coloris@latest/dist/coloris.min.js",
                # load controller JS
                "js/color-controller.js",
            ],
            css={"all": ["https://cdn.jsdelivr.net/gh/mdbassit/Coloris@latest/dist/coloris.min.css"]},
        )

For the Stimulus controller, we pass the values through to the JavaScript library, including a reference to the controlled element via this.element.id.

// myapp/static/js/color-controller.js

class ColorController extends window.StimulusModule.Controller {
    static values = { swatches: Array, theme: String };

    connect() {
        // create
        Coloris({ el: `#${this.element.id}` });

        // set options after initial creation
        setTimeout(() => {
            Coloris({ swatches: this.swatchesValue, theme: this.themeValue });
        });
    }
}

window.wagtail.app.register('color', ColorController);

Now we can use this widget in any FieldPanel or any FieldBlock for StreamFields, it will automatically instantiate the JavaScript to the field’s element.

# blocks.py

# ... other imports
from django import forms
from wagtail.blocks import FieldBlock

from .widgets import ColorWidget


class ColorBlock(FieldBlock):
    def __init__(self, *args, **kwargs):
        swatches = kwargs.pop('swatches', [])
        theme = kwargs.pop('theme', 'large')
        self.field = forms.CharField(widget=ColorWidget(swatches=swatches, theme=theme))
        super().__init__(*args, **kwargs)

# models.py

# ... other imports
from django import forms
from wagtail.admin.panels import FieldPanel

from .blocks import ColorBlock
from .widgets import ColorWidget


BREAD_COLOR_PALETTE = ["#CFAC89", "#C68C5F", "#C47647", "#98644F", "#42332E"]

class BreadPage(Page):
    body = StreamField([
        # ...
        ('color', ColorBlock(swatches=BREAD_COLOR_PALETTE)),
        # ...
    ], use_json_field=True)
    color = models.CharField(blank=True, max_length=50)

    # ... other fields

    content_panels = Page.content_panels + [
        # ... other panels
        FieldPanel("body"),
        FieldPanel("color", widget=ColorWidget(swatches=BREAD_COLOR_PALETTE)),
    ]

Using a build system¶

You will need ensure your build output is ES6/ES2015 or higher. You can use the exposed global module at window.StimulusModule or provide your own using the npm module @hotwired/stimulus.

// myapp/static/js/word-count-controller.js
import { Controller } from '@hotwired/stimulus';

class WordCountController extends Controller {
    // ... the same as above
}

window.wagtail.app.register('word-count', WordCountController);

You may want to avoid bundling Stimulus with your JavaScript output and treat the global as an external/alias module, refer to your build system documentation for instructions on how to do this.