DEV Community: LB (Ben Johnston)

On mentoring for an an open-source internship

LB (Ben Johnston) — Wed, 12 Oct 2022 21:10:28 +0000

This year I was able to take part in an open-source internship run alongside Google Summer of Code but sponsored by Torchbox. This internship allowed one new to open-source developer to submit a project proposal and then work alongside myself and others to build something core into Wagtail. Wagtail is an open-source CMS built on Django.

It was a really big few months for me - while I was given paid time (4 hours) a week from my work, Virgin Australia, the time taken each week was much more. Especially when we had to consider multiple time zones across the team (UK, India, Australia). It was an incredibly rewarding experience though and taught me a lot about what it is like to help new developers get up to speed and when to push but also when to help with a bit of the solution.

It is easy to forget what it is like to write code or learn a framework for the first time, not just the first time in a new language but the first time completely.

While I have only been a full-time software developer for about five years, I have done programming in some form for many years before that.

At a previous job, not as a software developer, myself and a few others endeavoured to build a CRM for the church I worked at. We opted for web2py simply because it was the thing I had first learned after learning Python and had found incredible power in building something that people could use.

Learning this new framework meant learning so many things at once, and also intentionally or probably more so out of blissful ignorance, not learning some things. I never really picked up git until much later and was enamoured by the browser IDE that web2py shipped with, as it meant I did not have to think about that big unknown. To no one’s surprise, this caused many problems with writing directly to a production server without any version control history to fall back on.

These last few months I was able to get a somewhat fresh perspective on what it is like for all of us learn something new that is incredibly complex. You cannot possibly learn it all at once, nor can you really understand where to start learning and what bits matter now or matter later. It has reminded me of the importance of small goals and being ok with splitting those goals up even further until you can get some momentum.

I have had the pleasure over this time to be a mentor of Google Summer of Code (GSoC), technically Torchbox’s internship that ran alongside other GSoC projects for the Wagtail community. My employer, Virgin Australia, generously approved a set time each week for me to be a mentor and help a new developer get up to speed and contribute solidly to Wagtail (an open-source CMS built on Django).

During this project, I have been absolutely inspired by the tenacity and grit of Paarth who has gone from contributing small CSS / documentation fixes to building out full Django template components used across the entire CMS in a matter of weeks. Paarth was the student I got to mentor, he is in his third year of studies in one of the top tech universities in India. He worked incredibly hard even to get approved as a contributor, preparing a full project proposal from a reasonably ambiguous goal. That goal was to Unify the UX across large parts of Wagtail, originally we just called this ‘Apply page editor UX to other parts of Wagtail’ which did not do the enormity of the task justice. Paarth contributed close to 20 pull requests even before the project started, he advised me that he would keep his phone on loud notifications for only Github to keep on top of any new ‘good first issues’ that arose.

As we, Thibaud and Helen, got to know Paarth through the project I am glad to say that we created a bond and it was great for me to hear about his university life. I learned that Paarth had spent the first two years of his course remotely (due to the pandemic), and also how much harder he has had to work to get into uni and get into the course he wanted (well, almost, a course that is close to what he wanted). How far he lives from uni, an overnight train ride just to visit his family, along with many other things that have been hard for him but I had taken for granted as easy during my university days.

All of this alerted me to the fact that I have had it relatively easy here in Australia with my university life (a long time ago) and career. I have had to work hard but I have not had to fight or push in the same way Paarth has. In all of this I am thankful for the opportunities that have come my way but incredibly encouraged that there are legends out there like Paarth getting started while also wanting to be involved with open-source.

As for the project itself, it was an incredible success, with large parts of the Wagtail UI brought up to scratch with the new layouts, designs and cleaner HTML/CSS to manage. There were a lot of bug fixes, some existing and some introduced, along the way with a solid amount of unit tests added to support them. I was able to lean on the incredible advice of Helen and Thibaud from Torchbox in the UK, including when I sneaked off for a trip to Bali (yay) with my family. This helped me get different perspectives on how to approach problems and how to work in a large, long-lived codebase.

Core skills

Some of the things I was able to help guide.

Git - Despite my late learning of the power of git, this is something that came up again and again in our project. Botched rebases, switching branches, code conflicts, adding messages to commits and when a Git GUI is helpful.
Linting - Wagtail has multiple layers of code checks and linting, including Python/JavaScript, HTML linting, being able to understand these errors, setting up your editor, running the formatter are all critical to faster development.
Reading the issue - This is something we spent time on a lot, reading the issue raised (a bug or enhancement), learning to read it twice, asking questions and clarification, and the inevitable de-sope of things to future issues.
Reproducibility of the issue or problem - When solving bugs, it was important to make sure that he could reproduce the issue and truly understand it, before going in to solve it.
Unit tests - Writing, debugging, and refactoring unit tests is a whole universe of complexity but it is something that helps to ensure that improvements to the code can last longer and be more reliable for future development.
Reading a file & writing field notes - We spent a bit of time walking through existing code, just reading it line by line and writing notes. One thing that helped was to encourage the idea of ‘field notes’, just summarising the file in your own words and also breaking it up into bullet points to help understand it.
Make small changes and get early feedback - Instead of solving the whole thing at once, solve a small part of it and get feedback.

Bonus learnings

Some things I learned for me along the way, even if it means a bit more empathy for others getting started.

SCSS/CSS is hard - I often see Twitter threads about CSS being easy/hard or not a ‘real’ language. It is incredibly complex and requires a lot of patience and understanding to build things well that work across the myriad of breakpoints and browsers.
Long-lived code is a minefield of complexity - It is very easy to change things in one place and it breaks another place. This is something to not just know on the surface but really understand, it is especially complex for code that is used/extended by others like Wagtail.
open-source code needs to consider maintainers - While the above may not be too different to any other large project. The key difference with a large open-source project is that there are a wider range of contributors with a wider range of skills to consider and also conflicting PRs and work is almost guaranteed when doing anything large.
time zones add friction - I love remote work and even travelled for a year while working for companies back in Australia. However, when there are three time zones to consider (India, UK, AU) and working hours, uni classes and people with families it becomes very much a juggling act to line things up.
Zoom has incredibly good noise cancellation - I tried many others and Zoom is the best, I want Google Hangouts (or whatever it is called now) to be great but nothing matched Zoom. Maybe Google should stop building new chat / call apps.
Planning & Deadlines - Planning in sprints helped break up the work into blocks but in reality it did not follow that at all. Over the project, we found better things are 'themes' or 'blocks' of work in similar areas of code or similar goals with check-ins on those blocks every two weeks.
Accessibility first - Building things well with accessibility baked in solves for a lot of problems later, you have a better DOM structure and more thought-out code to work with.
Fast & slow - Some things are faster than you expect, some things are slower, often by orders of magnitude, your estimates will only be correct when the work is done.

What was achieved

I will not steal the thunder from Paarth, but just call out some of the most exciting features and some stats from the project.

Globally - Wagtail has an incredibly fresh UI, that feels much more consistent across parts of the code and is substantially more accessible and usable with other languages.
Two very old pull requests, from 2019 & 2020, were rebased with fixes and merged in.
Was able to close one of the oldest bugs in the project, from 2016.
Paarth moving from no contributions to the 21st most contributions - https://github.com/wagtail/wagtail/graphs/contributors.
Authentication pages, we thought they would be out of scope originally but Paarth was able to get them done and they look so much better.
Less yelling - the first pull request from Paarth, even before being accepted, was to remove all the uppercase styling on buttons/menus - thanks for reducing the yelling in Wagtail. https://github.com/wagtail/wagtail/issues/7624
You can read Paarth's blog post about his open-source internship experience.

Acknowledgements

It would be remiss of me to not call out those involved throughout this project.

Paarth - Congrats on putting yourself out there and working incredibly hard every step of the way, even while going to uni in person for the first time and being away from your family.
Thibaud - Thanks for joining so many of the calls, even when you were busy or about to go on leave. Thanks for always pushing back when needed on solutions that were a bit too overkill while also pushing the UI forward to be better for everyone.
Helen - It was great to get to know you and thanks for the great guidance on our calls on how to work with various generations of CSS and classes.
Virgin Australia - Thanks Ken & Annette, I was unsure what you would say to me asking for 4 hours a week for many months to do this and I really appreciate the trust you have for me to make this work.
Torchbox - Thanks for sponsoring Paarth, even though we did not get all the GSoC slots and thanks for all the resources you put into the Wagtail community generally.
Wagtail community - So many PRs had reviews from other core devs and along the way, there was even work in the UX Unification scope that got randomly contributed by others meaning we could do other things.
Bec & Leo - My wife and son, you made it possible for me to do the late night & early morning calls and have been so supportive of my desire to help with open-source over the last many years.

Round two?

In hindsight it would have been better to have a clearer goal, the project was a bit ambiguous which gave us room to move but felt like some things were not really solid enough to get good momentum on. I do feel that Paarth was an incredible contributor and took on the challenge well, pushing through, and was happy to give things a go a few different ways to see what worked the best.

This was an incredible opportunity to help make Wagtail better, help grow my skills and also get to know some great people, so yeah I would do it again!

More about this project

A list of all things completed and a bit of a round up - more technical focus - on the UX Unification project discussion
Wagtail - open-source internship: UX Unification

Creating an interactive event budgeting tool within Wagtail

LB (Ben Johnston) — Tue, 04 Oct 2022 00:49:49 +0000

Wagtail 4.0 has recently been released and it comes with a much nicer design for managing nested InlinePanel (models) or StreamField components.

I thought it might be a good chance to see how we could go about using this new UI to manage more complex data within Wagtail.

This tutorial will walk you through a basic set-up of building an interactive event budgeting tool within the Wagtail page editing interface. While this may not be something that should be done, a spreadsheet may be better, it is a good simple example of nested models along with some JavaScript sprinkles to give the user some instant feedback on their entry.

Goal

Build a basic event budgeting tool within the Wagtail page editor.
We should be able to enter fixed & variable (per person) prices, along with a sale price and see an estimate of how many tickets will need to be sold to break even.
We want the data to be stored in Django models so that we can work with this data server side easily.

Tutorial

0. Getting started

This tutorial assumes you have at least done the Wagtail getting started tutorial
First, we will create a new Wagtail/Django project and then create an events app within that Django project - python manage.py startapp events
Add "events" to INSTALLED_APPS

Versions

Python 3.10
Wagtail 4.0.2
Django 4.1.1
Stimulus JS 3.1.0 (Node js is not required for this tutorial)

1. Set up the data Model

We will create the initial model and Panels, Wagtail provides a nice abstraction around the Django models and fields with the concept of Panels to provide editing form containers.
Wagtail provides an InlinePanel solution that allows nested inline data relations to be edited easily.
We will have two core models, the EventPage which extends the Wagtail Page model and contains things like the Page title and the ticket price.
Our second model will be a ParentalKey (from modelcluster) relation to the EventPage and be called EventPageBudgetItem, each EventPage can also have an orderable set of these budget item rows. The budget item row will have three fields, the description, amount and whether the price is per person (variable) or fixed.
Modify the file events/models.py to add our model, as below.
Run python manage.py makemigrations and then python manage.py migrate.
Cross-check Confirm you can now go to the Wagtail admin interface, create a new page and then create an Event page with the budget items.

from django import forms
from django.db import models

from modelcluster.fields import ParentalKey

from wagtail.admin.panels import FieldPanel, FieldRowPanel, InlinePanel, MultiFieldPanel
from wagtail.models import Orderable, Page


class AbstractBudgetItem(models.Model):
    """
    The abstract model for the budget item, complete with panels.
    """

    class PriceType(models.TextChoices):
        PRICE_PER = "PP", "Price per"
        FIXED_PRICE = "FP", "Fixed price"

    description = models.CharField(
        "Description",
        max_length=255,
    )

    price_type = models.CharField(
        "Price type",
        max_length=2,
        choices=PriceType.choices,
        default=PriceType.FIXED_PRICE,
    )

    amount = models.DecimalField(
        "Amount",
        default=0,
        max_digits=6,
        decimal_places=2,
    )

    panels = [
        FieldRowPanel(
            [
                FieldPanel("description"),
                FieldPanel("price_type"),
                FieldPanel("amount"),
            ]
        )
    ]

    class Meta:
        abstract = True


class EventPageBudgetItem(Orderable, AbstractBudgetItem):
    """
    The real model which combines the abstract model, an
    Orderable helper class, and what amounts to a ForeignKey link
    to the model we want to add related links to (EventPage)
    """

    page = ParentalKey(
        "events.EventPage",
        on_delete=models.CASCADE,
        related_name="related_budget_items",
    )


class EventPage(Page):

    ticket_price = models.DecimalField(
        "Price",
        default=0,
        max_digits=6,
        decimal_places=2,
    )

    content_panels = Page.content_panels + [
        MultiFieldPanel(
            [
                InlinePanel("related_budget_items"),
                FieldPanel("ticket_price"),
            ],
            "Budget",
        ),
    ]

2. Set up the field widgets

We will now make the admin interface a bit easier to use and add some data attributes to our fields so we can track them in JavaScript.
We will also avoid the type="number" field and make the numbers a bit easier to work with.
A note about number fields, Django will use the type="number" by default when you use a Decimal field, to keep things simple we will use a text field with some different attributes. See the UK design system guidelines and a deep dive on why the number input is the worst input.
For each of the InlinePanel inner FieldPanels we will add a simple data attribute so that our JavaScript code can be implemented easily without having to know about the field name / id on the elements.
For the ticket price field we will use a more specific data attribute "data-budget-target": "ticketPrice", so that it is easier to read this value in our Stimulus js controller (more on that later).
Cross-check Once updated, you should be able to see that your number fields look more like text fields and when inspecting the DOM you should be able to see the data-* attributes on each field.

from django import forms
from django.db import models

from modelcluster.fields import ParentalKey

from wagtail.admin.panels import FieldPanel, FieldRowPanel, InlinePanel, MultiFieldPanel
from wagtail.models import Orderable, Page

# added
NUMBER_FIELD_ATTRS = {
    "inputmode": "numeric",
    "pattern": "[0-9.]*",
    "type": "text",
}


class AbstractBudgetItem(models.Model):
    """
    The abstract model for the budget item, complete with panels.
    """

    class PriceType(models.TextChoices):
        PRICE_PER = "PP", "Price per"
        FIXED_PRICE = "FP", "Fixed price"

    description = models.CharField(
        "Description",
        max_length=255,
    )

    price_type = models.CharField(
        "Price type",
        max_length=2,
        choices=PriceType.choices,
        default=PriceType.FIXED_PRICE,
    )

    amount = models.DecimalField(
        "Amount",
        default=0,
        max_digits=6,
        decimal_places=2,
    )

    panels = [
        FieldRowPanel(
            [
                FieldPanel(
                    "description",
                    # updated - using widget
                    widget=forms.TextInput(attrs={"data-description": ""}),
                ),
                FieldPanel(
                    "price_type",
                    # updated - using widget
                    widget=forms.Select(attrs={"data-type": ""}),
                ),
                FieldPanel(
                    "amount",
                    # updated - using widget
                    widget=forms.TextInput(
                        attrs={"data-amount": "", **NUMBER_FIELD_ATTRS}
                    ),
                ),
            ]
        )
    ]

    class Meta:
        abstract = True


class EventPageBudgetItem(Orderable, AbstractBudgetItem):
    """
    The real model which combines the abstract model, an
    Orderable helper class, and what amounts to a ForeignKey link
    to the model we want to add related links to (EventPage)
    """

    page = ParentalKey(
        "events.EventPage",
        on_delete=models.CASCADE,
        related_name="related_budget_items",
    )


class EventPage(Page):

    ticket_price = models.DecimalField(
        "Price",
        default=0,
        max_digits=6,
        decimal_places=2,
    )

    content_panels = Page.content_panels + [
        MultiFieldPanel(
            [
                InlinePanel("related_budget_items"),
                FieldPanel(
                    "ticket_price",
                    # updated - using widget
                    widget=forms.TextInput(
                        attrs={
                            "data-budget-target": "ticketPrice",
                            **NUMBER_FIELD_ATTRS,
                        }
                    ),
                ),
            ],
            "Budget",
        ),
    ]

3. Set up a custom wrapper Panel container

We will need a nice way to add some kind of summary of the totals for the user, there are a few ways to do this. One way could be via the HelpPanel which lets us add arbitrary Django templates to the panel set.
However, a nicer way for what we need is to extend the MultiFieldPanel with a custom template and some additional context passed to that template.
First, we will create a new BudgetGroupPanel that extends the MultiFieldPanel, in a new file events/panels.py.
This file lets us refer to a different template and also inject some extra data into the context.
We will use the field_ids so that we can provide a better experience for users with the output element.

# events/panels.py
from django.forms import MultiValueField
from wagtail.admin.panels import MultiFieldPanel


class BudgetGroupPanel(MultiFieldPanel):
    class BoundPanel(MultiFieldPanel.BoundPanel):
        template_name = "events/budget_group_panel.html"

        def get_context_data(self, parent_context=None):
            """
            Prepare a list of ids so that we can reference them in the
            output.
            """

            context = super().get_context_data(parent_context)

            context["field_ids"] = filter(
                None, [child.id_for_label() for child in self.visible_children]
            )

            return context

Next, we will need to prepare the template, create a file in your app's templates folder events/templates/events/budget_group_panel.html.
This HTML has some data attributes that tell our JavaScript what to attach to, along with when to update.
We are using include to include the original Wagtail multi_field_panel template inside our div wrapper.
We are using the output element and a suitable h3 title to present the sub-totals and budget estimate to the user.
Finally, these budget totals also have data attributes to advise our JavaScript code where to inject the values.

<div
    data-controller="budget"
    data-action="change->budget#updateTotals"
    data-budget-per-price-value="PP"
>
    {% include "wagtailadmin/panels/multi_field_panel.html" %}
    <output for="{{ field_ids|join:' ' }}">
        <h3>Budget summary</h3>
        <dl>
            <dt>Total price per</dt>
            <dd data-budget-target="totalPricePer">-</dd>
            <dt>Total fixed</dt>
            <dd data-budget-target="totalFixed">-</dd>
            <dt>Break even qty</dt>
            <dd data-budget-target="breakEven">-</dd>
        </dl>
    </output>
</div>

Finally, we need to use this custom panel in our EventPage model.
This will be a simple replacement of the MultiFieldPanel with our BudgetGroupPanel.
Cross-check Once updated, you should now be able to see the output content and also check the DOM for the relevant data attributes and for attribute.

# events/models.py
from django import forms
from django.db import models

from modelcluster.fields import ParentalKey

from wagtail.admin.panels import FieldPanel, FieldRowPanel, InlinePanel # updated, removing MultiFieldPanel
from wagtail.models import Orderable, Page

from .panels import BudgetGroupPanel # added

# ... other models

class EventPage(Page):

    ticket_price = models.DecimalField(
        "Price",
        default=0,
        max_digits=6,
        decimal_places=2,
    )

    content_panels = Page.content_panels + [
        BudgetGroupPanel(
            [
                InlinePanel("related_budget_items"),
                FieldPanel(
                    "ticket_price",
                    widget=forms.TextInput(
                        attrs={
                            "data-budget-target": "ticketPrice",
                            **NUMBER_FIELD_ATTRS,
                        }
                    ),
                ),
            ],
            "Budget",
        ),
    ]

4. Set up JavaScript sprinkles

There are a few good libraries out there that provide ways to add JavaScript 'sprinkles' existing HTML without the need to overhaul your entire system with something like React or Vue. What you use here is an architectural and tooling choice, but the underlying JavaScript that needs to be written is essentially the same.

We need a way to load JavaScript code.
We need to ensure we can attach the JavaScript listeners/behaviour to the right elements.
We need a way to do some JavaScript calculations based on the user's values that are entered, also consider when a user re-orders/removes an inline panel item.
We need a way to output the results of these calculations to the DOM at the desired elements.

All of this can be done in React, Vue, Angular, Alpine, jQuery and even JavaScript without any libraries at all. However, Stimulus gives us a nice API that moves the 'JavaScript attaching of behaviour' into the HTML and the 'doing logic stuff' into the JavaScript quite nicely.

You can read more about Stimulus Controllers in their documentation.

If you would like to see this tutorial written with other JavaScript libraries, let me know in the comments and we can explore for comparison.

Now, let's write some JavaScript.

Create a new file events/static/js/events.js that will house our Stimulus Controller.
We will use the import / from syntax that is available in modern browsers and import the Stimulus library directly from unpkg. For production projects, it would be better to serve this core module from your own project's static files.
The controller below will attach to any element that loads with the data-controller="budget" data attribute (we put this in our budget group panel).
We wll further refine the JS in the next step, for now let's focus on getting it loading.

import {
    Application,
    Controller,
} from "https://unpkg.com/@hotwired/[email protected]/dist/stimulus.js";

class BudgetController extends Controller {
    static targets = [
        "breakEven",
        "ticketPrice",
        "totalFixed",
        "totalPricePer",
    ];
    static values = { perPrice: String };

    connect() {
        this.updateTotals();
    }

    /**
     * Update the DOM targets with the calculated totals.
     */
    updateTotals() {
        console.log("updating totals with dummy values");
        const breakEven = 45;
        const totalFixed = 56;
        const totalPricePer = 78;
        this.totalPricePerTarget.innerText = `${totalPricePer || "-"}`;
        this.totalFixedTarget.innerText = `${totalFixed || "-"}`;
        this.breakEvenTarget.innerText = `${breakEven || "-"}`;
    }
}

const Stimulus = Application.start();

Stimulus.register("budget", BudgetController);

Wagtail provides a simple way to load JavaScript into the page editor using the insert_editor_js hook.
Create a new file events/wagtail_hooks.py and add the following code.
This will load a module script that pulls in our js file.
Cross-check Once updated, reload the dev server and then check the event page editing. You should see the dummy values load and the console should log out the message from our controller.

from django.templatetags.static import static
from django.utils.html import format_html

from wagtail import hooks


@hooks.register("insert_editor_js")
def editor_css():
    return format_html(
        '<script type="module" src="{}"></script>',
        static("js/events.js"),
    )

5. Add total calculation logic to JavaScript

Update events/static/js/events.js to the following code, we will walk through it after the code snippet.

import {
    Application,
    Controller,
} from "https://unpkg.com/@hotwired/[email protected]/dist/stimulus.js";

class BudgetController extends Controller {
    static targets = [
        "breakEven",
        "ticketPrice",
        "totalFixed",
        "totalPricePer",
    ];
    static values = { perPrice: String };

    connect() {
        this.updateTotals();
    }

    /**
     * Parse the inline panel children that are not hidden and read the inner field
     * values, parsing the values into usable JS results.
     */
    get items() {
        const inlinePanelChildren = this.element.querySelectorAll(
            "[data-inline-panel-child]:not(.deleted)"
        );

        return [...inlinePanelChildren].map((element) => ({
            amount: parseFloat(
                element.querySelector("[data-amount]").value || "0"
            ),
            description:
                element.querySelector("[data-description]").value || "",
            type: element.querySelector("[data-type]").value,
        }));
    }

    /**
     * parse ticket price and prepare the totals object to show a summary of
     * totals in the items and the break even quantity required.
     */
    get totals() {
        const perPriceValue = this.perPriceValue;
        const items = this.items;
        const ticketPrice = parseFloat(this.ticketPriceTarget.value || "0");

        const { totalPricePer, totalFixed } = items.reduce(
            (
                { totalPricePer: pp = 0, totalFixed: pf = 0 },
                { amount, type }
            ) => ({
                totalPricePer: type === perPriceValue ? pp + amount : pp,
                totalFixed: type === perPriceValue ? pf : pf + amount,
            }),
            {}
        );

        const totals = {
            breakEven: null,
            ticketPrice,
            totalFixed,
            totalPricePer,
        };

        // do not attempt to show a break even if there is no ticket price
        if (ticketPrice <= 0) return totals;

        const ticketMargin = ticketPrice - totalPricePer;

        // do not attempt to show a break even if ticket price does not cover price per
        if (ticketMargin <= 0) return totals;

        totals.breakEven = Math.ceil(totalFixed / ticketMargin);

        return totals;
    }

    /**
     * Update the DOM targets with the calculated totals.
     */
    updateTotals() {
        const { breakEven, totalFixed, totalPricePer } = this.totals;
        this.totalPricePerTarget.innerText = `${totalPricePer || "-"}`;
        this.totalFixedTarget.innerText = `${totalFixed || "-"}`;
        this.breakEvenTarget.innerText = `${breakEven || "-"}`;
    }
}

const Stimulus = Application.start();

Stimulus.register("budget", BudgetController);

static targets - Setting up Targets is a convenient way to provide access to specific elements in the DOM from our controller instance. Remember we put these attributes in the HTML template or our widget attrs, each target can now be accessed from the Controller via this.breakEvenTarget or similar.
connect method - This gets called when the Controller is instantiated with a DOM element, it is like constructor in that it runs early and only once.
items getter - This is a custom method that pulls in any non-hidden InlinePanel children and then reads the inner values via simple data attributes. Note that we are using this.element here, which will be the budget group panel with the data-controller set on it.
totals getter - This does all the bulk calculations, working out the break-even price, the sub-totals and returning an object to be used when updating the DOM. This JavaScript would be essentially the same irrespective of what library is used.
updateTotals method - This does the 'work' of updating the DOM, we have kept this method light for readability, it also adds some nicer default values if we get missing/undefined results.
Note: The updateTotals method gets triggered as an action because of this line in our HTML data-action="proxy.php?url=change->budget#updateTotals". This tells Stimulus that whenever any DOM element fires the change event within the group panel container, trigger the updateTotals method. We could enhance this further with data-action="proxy.php?url=change->budget#updateTotals focusout->budget#updateTotals" which will trigger whenever any focusout event also occurs.
Cross-check Now, when you refresh, you should be able to see that your totals are being calculated correctly.

Next steps

There are a few avenues for improvement, at some point though an external application may be more suitable.

We may want to provide other totals/calculations or even a profit margin value to the output.
We may want to trigger the updateTotals method more frequently based on the user interaction.
We could even add a hidden field that determines if the event will make a profit and block submitting if the price is not suitable.
Graphs!

For a simple planning tool and especially if the data is already being stored in Wagtail, this is a powerful way to make the editing interface a bit more reactive for users.

Any feedback below in the comments would be appreciated.

Ten tasty ingredients for a delicious pull request

LB (Ben Johnston) — Wed, 28 Sep 2022 20:46:24 +0000

Over the last few years, I have had the incredible opportunity to be a core team member of the Wagtail project. In that time, I have reviewed many new pull requests, and I’ve also had the chance to submit many of my own across Wagtail and many other projects.

lb-

I do enjoy the challenge of improving code, reading others’ code and learning how to write my own code better. I also love helping new developers get their first few pull requests over the line and become contributors. As we lead into Hacktoberfest I thought it would be a good chance to write down the things that I see time and time again when new contributors get involved and hopefully can help with some tips to give your contributions a better chance of being reviewed.

When you want to make something enticing for others, it not only needs to taste great but you need to think about presentation and also communication. You may have made the most amazing flat white (coffee), but if you leave out the epic latte art, it will not be as good. If your coffee is not what the customer ordered or is the wrong size, you have to start again. When you are able to tell a story or clearly articulate the decisions that went into the menu, it is always a more enjoyable experience.

Tasty ingredients

These ingredients apply to not just open source contributions but any code contributions at work or even in your own personal projects.

1. Read the [development] instructions

When you want to contribute, introduce yourself to the community, or even work out how to get started, take the time to read the project's development docs.

First, look at the project's readme for a Contributing or maybe a Development section. This may give you some basic instructions and hopefully point you in the direction of some documentation links.

Read the entire section, note all links, then read the content on each link. Sometimes, it is easy to skim through these because you want to get started quickly. But it's better to take 20 mins now to read the documentation instead of spending two hours later to start all over again.

About ‘fork the code’

Many contribution sections gloss over the mammoth task that can be a single line in the documentation similar to “fork the code and get it running locally”. This, on its own, can be a daunting task if you are just getting started, so let’s dive a bit deeper or if you know what this means skip to item two.

No single blog post like this can cover the nuance of this for every single project but it is good to call out some principles when it comes to getting started.

A. Basic understanding of git vs GitHub and/or GitLab git is the version control tool, it is something you install on your device and runs usually in the command line (terminal) or via some GUI application.
- GitHub & GitLab are two prominent websites that provide a web user interface for repositories using git. Mozilla has a great guide that helps to explain Git and GitHub
B. How to clone a remote repository and what that actually even means
- On GitHub or Gitlab, you will not be allowed to directly create branches or changes in a repository (project) that you do not have access to.
- However, you can make a copy (clone) of this repository using your own account, this clone will have all the branches and history that the original repository had.
- This is also called ‘fork’ in some cases, as your repository will be a branch of its own that forks the original repository.
- See the GitHub docs explain forking or how to fork a repository on GitLab.
C. How to go about getting the code running locally Once this is done, you still will not have any code locally on your device, you still need to create yet another fork on your own machine. Yes, it’s forks all the way down, there is no spoon.
- This is where the git command line comes into play and the term clone makes more sense. On your local machine you will git clone some-website.git which will create a new folder with a copy of the project inside.
- See Atlassian’s docs on git clone for more details.

Your goal at this point, before your first pull request, is to understand how to run the code on your local machine. Being able to make a change somewhere in the code and then re-run or reload whatever is needed to see that change in the development environment. For example, try to change something trivial, such as a template output or a JavaScript console log, and confirm you can actually get that change to show.

Bonus tip: Add a profile image to your Github profile and the community chat profile (Slack/Discord/Zulp). It does not need to be your image, but make it unique.

2. Read the issue and comments

Hopefully, at this point, you have a good sense of the purpose of the project and are still keen to contribute. Once you have the code forked and running locally, you will probably want to start looking for what to contribute.

Finding something to contribute is not always easy, especially if you are new to the project. Once you have a few candidate issues to investigate, be sure to read the entire issue description, all comments and all linked issues or pull requests. Often, you will find that someone else may have started or finished the issue, or sometimes there are clarifications in the comments about how to approach the problem or whether the problem is even something worth solving.

Bonus tip: If an issue has a pull request linked, but not merged, read that pull request and the discussion on it. Maybe the previous contributor got stuck or lost momentum, in which case you could pick up where they left off (assuming it's been enough time).

3. Create a fresh branch for your contributions

Before writing any code, take a moment to get your git hat on. When you clone the project locally, you will be checked out at the main branch (sometimes called master, or development depending on the project). This branch is not suitable for you to make your changes on. It is meant to be the branch that tracks the core development of the project.

Instead, take a moment to create a new branch. You can use the command line or install one of the many great git GUI tools. Don't listen to anyone that says you're not doing it right unless you use the command line. Reduce the things you need to learn today and focus on the git command line interface later. If you have a Mac, I recommend Fork, otherwise, the Github GUI is good enough.

This new branch name should have some context as to what you are fixing and if possible the issue number being fixed. For example git checkout -b 'feature/1234-add-unit-tests-for-inline-panel'. This branch name uses / to represent a folder and also has the issue number 1234, finally, it uses lower-kebab-case with a short description of the issue.

Bonus tip: You may find that your editor has some handy Git tooling and will often be able to tell you what branch you are on or whether you have any changes staged. https://code.visualstudio.com/docs/sourcecontrol/overview

4. Keep the changes focused

As a developer, it is easy to get distracted, maybe a typo here or white space that does not feel 'right' there. Sometimes, even our editor gets distracted and starts adding line breaks at the end of files as we save or it formats code without our consent due to configuration from a different project.

These added changes that are not the primary goal or not strictly required by the project's set-up are noise. This noise makes it harder to review the pull request and also can create confusion for future developers that see these commits and wonder how it relates to the bug that was fixed.

When you go to stage changes, only stage the parts you need or at least review the changes and 'undo' them before you save the commits.

If you do find a different problem, maybe a typo in the docs, this is what branches are for. Save your commits, create a new branch off master fix/fix-documentation-typo and then save that change to that branch., Now you have a small change, one that is easy to merge, which you can prepare a pull request for.

Keep your changes focused on the goal, do not add overhead to the reviewer or to yourself by changing things that do not need it (yet).

Bonus tip: It's OK to make changes in a 'messy' way locally, with lots of commits that maybe include things that are not needed. However, be sure to take some time to review your commits and clean up anything that is not required before you do your pull request.

5. Write unit tests

We are getting close to having a pull request, but the next critical step is unit tests. Anecdotally, I find that testing code you wrote will take 5-10x longer than the actual bug fix. Often, if the use case is right, it is better to write the tests first and get them running (but failing) before you fix the problem.

Finding how and where to write the unit tests can be hard in a new project, but hopefully, the project's development docs contain the clues you need to get started. Wagtai’s docs are hopefully a good example of this with a dedicated testing section.

If you fix a bug or introduce a new feature, you want to ensure that fix is long-lived and does not break again. You also want to help yourself by thinking through edge cases or potential problems. Testing helps with this. While regressions do happen, they are less likely to happen when code is tested.

Many projects will not even review a pull request without unit tests. Often, fixing a bug is not hard, ensuring the fix is the 'real' fix and that it does not break again is the hard part. Take the time to do the harder thing. It will help you grow as a developer and help your contributions make a longer lasting difference.

Bonus tip: A pull request that just adds unit tests to some core functionality that does not yet have tests is a great way to contribute, it helps you learn about the code and makes the project more reliable.

6. Give your pull request a name with context

A pull request that has the title 'fixes issue' is unhelpful at best, and spammy at worst. Take a few moments to think about how to give your change a title. Communicate, in a few words, the problem solved, feature added or bug fixed. Instead of 'Fixes 10423', use words and write a title 'Fixes documentation dark mode refresh issue'. No one in a project knows that issue 10423 is that one about the documentation dark mode refresh issue.

Also, add a proper name when you create the pull request. This will ensure that any notifications that go out to the team have the correct name from the start.

Bonus tip: Remember you can make a draft pull request in both GitHub and GitLab. This is a way to run the CI steps but in a way that indicates you are not ready for a review yet.

7. Reference the issue being fixed or resolved in the pull request

Referencing the issue being fixed within the pull request description is just as important as a good title. A pull request without a description is very difficult to review. Add some context and some steps to reproduce the issue or scenario.

It is often good to write yourself a checklist for any pull request and fill in the gaps.

Small description of the solution, one sentence.
Link to issue/s that should be resolved if this pull request gets merged.
Questions or assumptions, maybe you made an assumption we no longer support IE11 with your CSS change, if it's not in the docs - write the assumption down.
Details - additional details, context or links that help the reviewer understand the pull request.
Note: Some projects have a checklist or template for all new pull requests, it is best to use that if it is there.

Bonus tip: You can also include issues in the commit message. Adding something like fixes #1234 in your commit message will let GitHub know that the change is for that issue.

8. Review & fix the CI failures

Once you have created your pull request, there will often be a series of build/check/CI steps that run.

These steps are normally all required to pass before the pull request can be merged. CI is a broad term but usually, the testing and linting will run on the code you have proposed to change. Linting is a tricky one because sometimes the things that are flagged seem trivial, but they are important for code consistency. Re-read the development instructions and see how you can run the linting locally to avoid frustrating back & forth with small linting fixes.

Testing is a bit more complex. Maybe all the tests can be run locally or maybe the CI will run tests on multiple versions of a project or language. Do your best to run all the tests locally, but there may still be issues on the CI when you do. That is OK, and normally you can solve these issues one by one.

The most important thing is to not just ignore CI failures. Read through each error report and try to work out the problem and provide a fix. Ignoring these will likely lead to pull requests that do not get reviewed because they do not get the basics right.

Bonus tip: GitHub will not run the CI automatically for new contributors in some projects. This is an intentional security feature and a core contributor will need to approve your initial CI run.

9. Push to the same branch with fixes and do not open a new pull request

Finally, after you have fixed the failing linting and tests locally, you will want to push those changes to your remote branch. You do not need to open a new pull request. This creates more noise and confusion. Instead, push your changes up to your branch, and the CI will run automatically on those changes.

You can add a comment if you want to the pull request that you have updated, but often this is not really needed.

Avoid opening multiple pull requests for the same fix. Doing that means all the comments and discussion from the previous pull request will get lost and reviewers will have trouble finding them.

10. Eagerness balanced with patience

When you take time to contribute out of your own personal time, or even that from your paid employer, it can be very frustrating when a pull request does not get reviewed. It is best to temper your expectations with this process and remember that many people on the other side of this are also volunteers or have limited time to prioritise.

It is best to celebrate your accomplishment at this point even if your pull request never gets merged. However, it is good to balance that with an eagerness about getting your amazing fix in place to help people who use the project. Balancing this tension is hard, but the unhelpful thing to do is give up and never contribute or decide that you won’t respond to feedback because it came too late.

Also, remember that it is OK to move on and try something else. Try a different issue or project or area of the code. Don’t just sit waiting for a response on the one thing you did before looking at other challenges.

Update: John Franey on Twitter sent me a link to his post that is a great 'second course' to this post Preparing a Gourmet Pull Request.

Final thoughts

If there can be one summary of all of this, it is to take the time to read and remember that Slow is fast and fast is slow. If you rush through and do not take the time to read and truly understand the problem you are solving, you will end up being much slower in the long run.

Finally, remember that you can do all the right things and it may not be something that should be a core feature. The problem you are solving may not be a priority for a number of reasons or sometimes the solution ends up being a minefield of edge cases and complexity.

Be thankful that you are in a position to be able to write code, have a laptop that works and have a brain that can solve problems. There will always be more problems to solve later.

Also, remember that this is hard and that is OK. Anything new is hard and new things in programming often mean learning multiple new things in parallel. Get a notepad (virtual or otherwise) and write each problem down as you encounter it, this way you can work through each one individually without being overwhelmed.

Bonus: Learn how to rebase on `main`/`master`

One of the more complex things to grok is the git rebase. I found this very hard to understand when getting started but it is a critical part of developing for open source.

When you have your branch of code, it contains commits. The branch itself is essentially a 'pointer' to the last of those commits. Git is incredible software and works out where these commits 'branch' off the other commits that themselves have pointers.

Often on a project, you will make a change, and then a few days or weeks later see that these changes cannot be merged in easily as they conflict with the core code.

Merging main into your branch is unhelpful here, it will seem like it solves the current problem of conflicts but will create other headaches down the road. Merging main into your branch pulls ALL those commits, there could be hundreds` into your branch. Git now points your branch to the latest commit here, which is a mix of your original commits and all other ancestor changes back to before you started your changes.

Instead, think about this process as a thought exercise;

Create a new branch called my-temp-feature-2 off the latest main branch.
Go to each of your commits and re-apply them one by one on main.
Each time you get a conflict, resolve it one by one.
Now you have those commits sitting 'on top' of main without any code conflicts.
Delete the previous branch and rename your current temp branch with the same name as the previous branch.

This seems convoluted, but this is essentially the exact process of a rebase. It takes each commit, one by one, and writes it on top of another branch. As a conflict happens, you resolve the conflict for that specific commit and move on.

The final step is key though. You now have a local branch that is out of sync with the remote branch. You cannot just push because you will get an error. You must instead use the force and force push commands to overwrite the remote branch. Be careful before you do because these commands are absolute and will completely delete anything on the remote branch.

Some additional links on rebasing

Credits

The countless developers who have contributed small and meaningful changes to the free software & open source world.
Cover image - https://unsplash.com/photos/i9Hgm8Cf-20
Proofing - Meagen Voss from Torchbox
You, the reader, for learning to read the whole issue before moving on to fixing the problem
This has also been cross-posted on the Wagtail blog - https://wagtail.org/blog/ten-tasty-ingredients-for-a-delicious-pull-request/

Creating a schematic editor within Wagtail CMS with StimulusJS

LB (Ben Johnston) — Sun, 20 Feb 2022 06:55:18 +0000

Goal

Our goal is to create a way to present a product (or anything) visually alongside points over the image that aligns to a description.
Often content like this has to be rendered fully as an image, see the Instructables espresso machine article as an example.
However, we want to provide a way to have the image and its labels in separate content, this means the content is more accessible, links can be provided to sub-content and the labels can be translated if needed. See the website for the Aremde Nexus Prop coffee machine as an example. Not only is this coffee machine amazing, made in Brisbane, Australia but their website has some nice pulsating 'dots' that can be hovered to show features of the machine.

Our approach

A note on naming - Schematic - this can mean a few different things and maybe diagram would be more appropriate but we will go with schematic to mean the image along with some points with labels and point for the individual points that overlay the image.

Create a new Django app to contain the schematic model, we will design the model to contain the image and 'points' that align with the image.
Create a new Page that can add the Schematic and use Wagtail's built-in InlinePanel to allow for basic editing of these points.
Get the points and image showing in the page's template.
Refine the Wagtail CMS editing interface to firstly show the points visually over the image and then allow drag & drop positioning of the points all within the editor.

Versions

Python - 3.9
Django - 4.0
Wagtail - 2.16
Stimulus - 3.0.1

Assumptions

You have a working Wagtail project running locally, either your own project or something like the bakerydemo project.
You are using the images and snippets Wagtail apps (common in most installations).
You have installed the Wagtail API and have set up the URLs as per the basic configuration.
You have a basic knowledge of Wagtail, Django, Python and JavaScript.

Tutorial

Part 1 - Create a new `schematics` app plus `Schematic` & `SchematicPoint` models

python manage.py startapp schematics - create a new Django application to house the models and assets.
Add 'schematics' to your INSTALLED_APPS within your Django settings.
Create a Wagtail snippet which will hold our Schematic and SchematicPoint models, code and explanation below.
Run ./manage.py makemigrations, check the output matches expectations and then ./manage.py migrate to migrate your local DB.
Restart your dev server ./manage.py runserver 0.0.0.0:8000 and validate that the new model is now available within the Snippets section accessible from the sidebar menu.
Now create a single Schematic snippet so that there is some test data to work with and so you get a feel for the editing of this content.

Code - `models.py`

We will create two models, Schematic and SchematicPoint, the first will be a Wagtail snippet using the @register_snippet decorator via from wagtail.snippets.models import register_snippet.
The Schematic model has two fields title (a simple CharField) and image (a Wagtail image), the panels will also reference the related points model.
The SchematicPoint model has a ParentalKey (from modelcluster) which is included with Wagtail, for more information about this read the InlinePanel & modelclusters section of the Wagtail docs.
The SchematicPoint also has an x and y coordinate (percentages), the reasoning of using percentages is that it maps well to scenarios where the image may change or image may be shown at various sizes, if we go to px we have to solve a whole bunch of problems that present themselves. We also use the DecimalField to allow for up to 2 decimal places of precision within the value, e.g. 0.01 through to 99.99. (We are using max digits 5 because technically 100.00 is valid).
Note that we are using MaxValueValidator/MinValueValidator for the server-side validation of the values and NumberInput widget attrs for the client side (browser) validation. Django widget attrs is a powerful way to add HTML attributes to the form fields without needing to dig into templates, we will use this more later.

from django import forms
from django.core.validators import MaxValueValidator, MinValueValidator
from django.db import models

from modelcluster.fields import ParentalKey
from modelcluster.models import ClusterableModel

from wagtail.admin.edit_handlers import (
    FieldPanel,
    FieldRowPanel,
    InlinePanel,
)
from wagtail.core.models import Orderable
from wagtail.images.edit_handlers import ImageChooserPanel
from wagtail.search import index
from wagtail.snippets.models import register_snippet


@register_snippet
class Schematic(index.Indexed, ClusterableModel):
    title = models.CharField("Title", max_length=254)

    image = models.ForeignKey(
        "wagtailimages.Image",
        null=True,
        blank=True,
        on_delete=models.SET_NULL,
        related_name="+",
    )

    panels = [
        FieldPanel("title"),
        ImageChooserPanel("image"),
        InlinePanel("points", heading="Points", label="Point"),
    ]

    def __str__(self):
        title = getattr(self, "title", "Schematic")
        return f"Schematic - {title} ({self.pk})"

    class Meta:
        verbose_name_plural = "Schematics"
        verbose_name = "Schematic"


class SchematicPoint(Orderable, models.Model):
    schematic = ParentalKey(
        "schematics.Schematic",
        on_delete=models.CASCADE,
        related_name="points",
    )

    label = models.CharField("Label", max_length=254)

    x = models.DecimalField(
        verbose_name="X →",
        max_digits=5,
        decimal_places=2,
        default=0.0,
        validators=[MaxValueValidator(100.0), MinValueValidator(0.0)],
    )

    y = models.DecimalField(
        verbose_name="Y ↑",
        max_digits=5,
        decimal_places=2,
        default=0.0,
        validators=[MaxValueValidator(100.0), MinValueValidator(0)],
    )

    panels = [
        FieldPanel("label"),
        FieldRowPanel(
            [
                FieldPanel(
                    "x", widget=forms.NumberInput(attrs={"min": 0.0, "max": 100.0})
                ),
                FieldPanel(
                    "y", widget=forms.NumberInput(attrs={"min": 0.0, "max": 100.0})
                ),
            ]
        ),
    ]

    def __str__(self):
        schematic_title = getattr(self.schematic, "title", "Schematic")
        return f"{schematic_title} - {self.label}"

    class Meta:
        verbose_name_plural = "Points"
        verbose_name = "Point"

Part 2 - Create a new `ProductPage` model that will use the `schematic` model

You may want to integrate this into an existing page but for the sake of the tutorial, we will create a simple ProductPage that will have a ForeignKey to our Schematic snippet.
The snippet will be selectable via the SnippetChooserPanel which provides a chooser modal where the snippet can be selected. This also allows the same schematic to be available across multiple instances of the ProductPage or even available in other pages and shared as a discrete bit of content.
Remember to run ./manage.py makemigrations, check the output matches expectations and then ./manage.py migrate to migrate your local DB.
Finally, be sure to create a new ProductPage in the Wagtail admin and link its schematic to the one created in step 1 to test the snippet chooser is working.

Code - `models.py`

from django.db import models

from wagtail.core.models import Page
from wagtail.snippets.edit_handlers import SnippetChooserPanel


class ProductPage(Page):

    schematic = models.ForeignKey(
        "schematics.Schematic",
        null=True,
        on_delete=models.SET_NULL,
        related_name="product_page_schematic",
    )

    content_panels = Page.content_panels + [SnippetChooserPanel("schematic")]

Part 3 - Output the points over an image in the `Page`'s template

Now create a template to output the image along with the points, this is a basic template that gets the general idea across of using the point coordinates to position them over the image.
We will use the wagtailimages_tags to allow the rendering of an image at a specific size and the usage of the self.schematic within the template to get the points data.

Code - `myapp/templates/schematics/product_page.html`

The template below is built on the bakerydemo, so there is a base template that is extended.
Please note the CSS is not polished and will need to be adjusted to suit your own branding and desired hover behaviour.

{% extends "base.html" %}
{% load wagtailimages_tags %}

{% block head-extra %}
  <style>
    .schematic {
      position: relative;
    }

    .schematic .points {
      margin-bottom: 0;
    }

    .schematic .point {
      position: absolute;
    }

    .schematic .point::before {
      background-color: #fb7575;
      border-radius: 50%;
      box-shadow: 0 -2px 0 rgba(0, 0, 0, 0.1) inset;
      content: "";
      display: block;
      border: 0.5rem solid transparent;
      height: 2.75rem;
      background-clip: padding-box; /* ensures the 'hover' target is larger than the visible circle */
      position: absolute;
      transform: translate(-50%, -50%);
      width: 2.75rem;
      z-index: 1;
    }

    .point .label {
      opacity: 0; /* hide by default */
      position: absolute;

      /* vertically center */
      top: 50%;
      transform: translateY(-50%);

      /* move to right */
      left: 100%;
      margin-left: 1.25rem; /* and add a small left margin */

      /* basic styles */
      font-family: sans-serif;
      width: 12rem;
      padding: 5px;
      border-radius: 5px;
      background: #000;
      color: #fff;
      text-align: center;
      transition: opacity 300ms ease-in-out;
      z-index: 10;
    }

    .schematic .point:hover .label {
      opacity: 1;
    }
  </style>
{% endblock head-extra %}

{% block content %}
  {% include "base/include/header.html" %}
  <div class="container">
    <div class="row">
      {% image self.schematic.image width-1920 as schematic_image %}
      <div class="schematic col-md-12">
        <img src="proxy.php?url={{ schematic_image.url }}" alt="{{ schematic.title }}" />
        <ul class="points">
          {% for point in self.schematic.points.all %}
          <li class="point" style="left: {{ point.x }}%; bottom: {{ point.y }}%">
            <span class="label">{{ point.label }}</span>
          </li>
          {% endfor %}
        </ul>
      </div>
    </div>
  </div>
{% endblock content %}

Part 4 - Enhance the editor's experience to show a different image size

Before we can try to show the 'points' within the image in the editor we need to change the behaviour of the built-in ImageChooserPanel to load a larger image when editing. This panel has two modes, editing an existing 'saved' value (shows the image on load) or updating an image by choosing a new one either for the first time or editing, this image is provided from the server.
At this point we will start writing some JavaScript and use the Stimulus 'modest' framework, see the bottom of this article for a bit of a high-level overview of Stimulus if you have not yet heard about it. Essentially, Stimulus gives us a way to assign data- attributes to elements to link their behaviour to a Controller class in JavaScript and avoids a lot of the boilerplate usually needed when working with jQuery or vanilla (no framework) JS such as adding event listeners or targeting elements predictably.
On the server-side we will create a sub-class of ImageChooserPanel which allows us to modify the size of the image that is returned if already saved and add our template overrides so we can update the HTML.
We will break this part into a few sub-steps.

Part 4a - Adding Stimulus via `wagtail_hooks`

Wagtail provides a system of 'hooks' where you can add a file wagtail_hooks.py to your app and it will be run by Wagtail on load.
We will use the insert_editor_js hook to add our JavaScript module.
The JavaScript used from here on in assumes you are supporting browsers that have ES6 support and relies extensively on ES6 modules, arrow functions and classes.
We will be installing Stimulus as an ES6 module in a similar way to the Stimulus installation guide - without using a build system.

Create a new file `schematics/wagtail_hooks.py`

Once created, stop your Django dev server and restart it (hooks will not run the first time after the file is added unless you restart).
You can validate this step is working by checking the browser inspector - checking that the script module exists, remember this will only show on editing pages or editing models and not on the dashboard for example due to the Wagtail hook used.
Assuming you are running Django with DEBUG = True in your dev server settings you should also see some console info about the status of Stimulus.

from django.conf import settings
from django.utils.html import format_html

from wagtail.core import hooks


@hooks.register("insert_editor_js")
def insert_stimulus_js():
    return format_html(
        """
        <script type="module">
            import {{ Application, Controller }} from "https://unpkg.com/@hotwired/stimulus/dist/stimulus.js";
            const Stimulus = Application.start();
            {}
            window.dispatchEvent(new CustomEvent('stimulus:init', {{ detail: {{ Stimulus, Controller }} }}));
        </script>
        """,
        # set Stimulus to debug mode if running Django in DEBUG mode
        "Stimulus.debug = true;" if settings.DEBUG else "",
    )

Part 4b - Creating `schematics/edit_handlers.py` with a custom `ImageChooserPanel`

Create a new file schematics/edit_handlers.py.
In this file we will sub-class the built-in ImageChooserPanel and its usage of AdminImageChooser to customise the behaviour via a new class SchematicImageChooserPanel.
SchematicImageChooserPanel extends ImageChooserPanel and does two things; it updates the widget_overrides to use a second custom class AdminPreviewImageChooser and passes down a special data attribute to the input field. This attribute is a Stimulus target attribute and allows our JavaScript to easily access this field.
Within AdminPreviewImageChooser we override the get_value_data method to customise the image preview output, remember that this is only used when editing an existing model with a chosen image. We are using the get_rendition method built-in to Wagtail's Image model.
We also need to ensure we use the SchematicImageChooserPanel in our models.py.
Remember to validate before moving on, you can do this by checking the image that is loaded when editing a model that already has a chosen image, it should be a much higher resolution version.

# schematics/edit_handlers.py
from wagtail.images.edit_handlers import ImageChooserPanel
from wagtail.images.widgets import AdminImageChooser


class AdminPreviewImageChooser(AdminImageChooser):
    """
    Generates a larger version of the AdminImageChooser
    Currently limited to showing the large image on load only.
    """

    def get_value_data(self, value):
        value_data = super().get_value_data(value)

        if value_data:
            image = self.image_model.objects.get(pk=value_data["id"])
            # note: the image string here should match what is used in the template
            preview_image = image.get_rendition("width-1920")
            value_data["preview"] = {
                "width": preview_image.width,
                "height": preview_image.height,
                "url": preview_image.url,
            }

        return value_data


class SchematicImageChooserPanel(ImageChooserPanel):
    def widget_overrides(self):
        return {
            self.field_name: AdminPreviewImageChooser(
                attrs={
                    "data-schematic-edit-handler-target": "imageInput",
                }
            )
        }

# schematics/models.py

# ... existing imports

from .edit_handlers import SchematicImageChooserPanel


@register_snippet
class Schematic(index.Indexed, ClusterableModel):

    # ...fields

    panels = [
        FieldPanel("title"),
        SchematicImageChooserPanel("image"), # ImageChooserPanel("image") - removed
        InlinePanel("points", heading="Points", label="Point"),
    ]


# .. other model - SchematicPoint

Part 4c - Adding a custom `EditHandler`

In Wagtail, there is a core class EditHandler which contains much of the rendering of lists of containers/fields within a page and other editing interfaces (including snippets).
So that we can get more control over how our Schematic editor is presented, we will need to create a sub-class of this called SchematicEditHandler.
Our SchematicEditHandler will add some HTML around the built-in class and also provide the editor specific JS/CSS we need for this content. We could add the CSS/JS via more Wagtail Hooks but then it would load on every single editor page, even if the user is not editing the Schemas.

In the file `schematics/edit_handlers.py` create a custom `SchematicEditHandler`

This new file (schematics/edit_handlers.py) will contain our custom editor handler classes, we will start with SchematicEditHandler which extends ObjectList.
Using the get_form_class method we generate a new dynamic class with the type function that has a Media class within it.
Django will use the Media class on a Form to load any JS or CSS files declared but only once and only if the form is shown.

# schematics/edit_handlers.py
from django.utils.html import format_html # this import is added

from wagtail.admin.edit_handlers import ObjectList # this import is added
from wagtail.images.edit_handlers import ImageChooserPanel
from wagtail.images.widgets import AdminImageChooser

# ... other classes

class SchematicEditHandler(ObjectList):
    template = "schematics/edit_handlers/schematic_edit_handler.html"

    def get_form_class(self):
        form_class = super().get_form_class()
        return type(
            form_class.__name__,
            (form_class,),
            {"Media": self.Media},
        )

    class Media:
        css = {"all": ("css/schematic-edit-handler.css",)}
        js = ("js/schematic-edit-handler.js",)

Use the `SchematicEditHandler` on the `Schematic` model

We will need to ensure we use this SchematicEditHandler in our models.py
Once this is done, you can validate that it is working by reloading the Wagtail admin, editing an existing Schematic snippet and checking the network tools in the browser inspector. It should have tried to load the schematic-edit-handler.css & schematic-edit-handler.js files - which are not yet added - just check that the requests were made.

# schematics/models.py

# ... existing imports

from .edit_handlers import (
    SchematicEditHandler,
    SchematicImageChooserPanel,
)


@register_snippet
class Schematic(index.Indexed, ClusterableModel):

    # ...fields

    # panels = [ ... put the edit_handler after panels

    edit_handler = SchematicEditHandler(panels)

# .. other model - SchematicPoint

Part 4d - Adding initial JS & CSS for the schematic edit handler

Create `schematic-edit-handler.js` - Stimulus Controller

This file will be a Stimulus Controller that gets created once the event stimulus:init fires on the window (added earlier by our wagtail_hooks.py).
static targets = [... - this tells the controller to look at for a DOM element and 'watch' it to check if it exists or gets created while the controller is active. This will specifically look for the data attribute data-schematic-handler-target="imageInput" and make it available inside the Controller's instance.
connect is a class method similar to componentDidMount in React or x-init/init() in Alpine.js - it essentially means that there is a DOM element available.
Once connected, we call a method setupImageInputObserver which we have made in this class, it uses the MutationObserver browser API to listen to the image's input value. The reason we cannot just use the 'change' event is due to this value being updated programmatically, we also cannot easily listen to when the chooser modal closes as those are jQuery events that are not compatible with built-in browser events.
Finally, once we know the image input (id) has changed and has a value (e.g. was not just cleared), we can fire of an API call to the internal Wagtail API to get the image path, this happens in the updateImage method. Once resolved, we update the src on the img tag.
You can now validate this by refreshing and then changing an image to a new one via the image chooser, the newly loaded image should get updated to the full size variant of that image.

// static/js/schematic-edit-handler.js
window.addEventListener("stimulus:init", ({ detail }) => {
  const Stimulus = detail.Stimulus;
  const Controller = detail.Controller;

  class SchematicEditHandler extends Controller {
    static targets = ["imageInput"];

    connect() {
      this.setupImageInputObserver();
    }

    /**
     * Once connected, use DOMMutationObserver to 'listen' to the image chooser's input.
     * We are unable to use 'change' event as it is updated by JS programmatically
     * and we cannot easily listen to the Bootstrap modal close as it uses jQuery events.
     */
    setupImageInputObserver() {
      const imageInput = this.imageInputTarget;

      const observer = new MutationObserver((mutations) => {
        const { oldValue = "" } = mutations[0] || {};
        const newValue = imageInput.value;
        if (newValue && oldValue !== newValue)
          this.updateImage(newValue, oldValue);
      });

      observer.observe(imageInput, {
        attributeFilter: ["value"],
        attributeOldValue: true,
        attributes: true,
      });
    }

    /**
     * Once we know the image has changed to a new one (not just cleared)
     * we use the Wagtail API to find the original image URL so that a more
     * accurate preview image can be updated.
     *
     * @param {String} newValue
     */
    updateImage(newValue) {
      const image = this.imageInputTarget
        .closest(".field-content")
        .querySelector(".preview-image img");

      fetch(`/api/v2/images/${newValue}/`)
        .then((response) => {
          if (response.ok) return response.json();
          throw new Error(`HTTP error! Status: ${response.status}`);
        })
        .then(({ meta }) => {
          image.setAttribute("src", meta.download_url);
        })
        .catch((e) => {
          throw e;
        });
    }
  }

  // register the above controller
  Stimulus.register("schematic-edit-handler", SchematicEditHandler);
});

Create `static/css/schematic-edit-handler.css` styles

This is a base starting point to get the preview image and the action buttons to stack instead of show inline, plus allow the image to get larger based on the actual image used.

/* static/css/schematic-edit-handler.css */
/* preview image - container */

.schematic-edit-handler .image-chooser .chosen {
  padding-left: 0;
}

.schematic-edit-handler .image-chooser .preview-image {
  display: inline-block; /* ensure container matches image size */
  max-width: 100%;
  margin: 2rem 0;
  float: none;
  position: relative;
}

.schematic-edit-handler .image-chooser .preview-image img {
  max-height: 100%;
  max-width: 100%;
}

Part 5 - Enhance the editor's experience to show point positioning

In this next part, our goal is to have the points shown visually over the image.
The styling here is very similar to the styling used in our page template but we need to ensure that the points move when the inputs change.
We will continue to expand on our Stimulus controller to house the JS behaviour and leverage another data- attribute around the InlinePanel used.
Working with the InlinePanel (also called expanding formset) has some nuance, the main thing to remember is that these panels can be deleted but this deletion only happens visually as there are input fields under the hood that get updated. Also, the panels can be reordered and added at will.

5a - Add a `SchematicPointPanel` that will use a new template `schematics/edit_handlers/schematic_point_panel.html`

We will update schematics/edit_handlers.py with another custom panel, this time extending the MultiFieldPanel, which is essentially just a thin wrapper around a bunch of fields.
This custom class does one thing, point the panel to a new template.

# schematics/edit_handlers.py
from django.utils.html import format_html

from wagtail.admin.edit_handlers import MultiFieldPanel, ObjectList # update - added MultiFieldPanel
from wagtail.images.edit_handlers import ImageChooserPanel
from wagtail.images.widgets import AdminImageChooser

# ... other classes

class SchematicPointPanel(MultiFieldPanel):
    template = "schematics/edit_handlers/schematic_point_panel.html"

Create the new template schematics/edit_handlers/schematic_point_panel.html and all it does is wrap the existing multi_field_panel in a div that will add a class and add another Stimulus target.

<div class="schematic-point-panel" data-schematic-edit-handler-target="point">
  {% extends "wagtailadmin/edit_handlers/multi_field_panel.html" %}
</div>

5b - Use the `SchematicPointPanel` in `models.py` & update `attrs`

Now that we have created SchematicPointPanel we can use it inside our SchematicPoint model to wrap the fields.
We have also reworked the various FieldPanel items to leverage the widget attribute so we can add some more data-attributes.
Note that the data-action is a specific Stimulus attribute that says 'when this input changes fire a method on the Controller. It can be used to add specific event listeners as we will see later but the default behaviour on input elements is the 'change' event.
We also add some data-point- attributes, these are not Stimulus specific items but just a convenience attribute to find those elements in our Stimulus controller, we could use more target type attributes but that is not critical for the scope of this tutorial.
A reminder that Django will smartly handle some attributes and when Python True is passed, it will be converted to a string 'true' in HTML - thanks Django!

# schematics/models.py
# ... imports

from .edit_handlers import (
    SchematicEditHandler,
    SchematicImageChooserPanel,
    SchematicPointPanel, # added
)

# Schematic model

class SchematicPoint(Orderable, models.Model):
    # schematic/label fields

    x = models.DecimalField(
        verbose_name="X →",
        max_digits=5,
        decimal_places=2,
        default=0.0,
        validators=[MaxValueValidator(100.0), MinValueValidator(0.0)],
    )

    y = models.DecimalField(
        verbose_name="Y ↑",
        max_digits=5,
        decimal_places=2,
        default=0.0,
        validators=[MaxValueValidator(100.0), MinValueValidator(0)],
    )

    fields = [
        FieldPanel(
            "label",
            widget=forms.TextInput(
                attrs={
                    "data-action": "schematic-edit-handler#updatePoints",
                    "data-point-label": True,
                }
            ),
        ),
        FieldRowPanel(
            [
                FieldPanel(
                    "x",
                    widget=forms.NumberInput(
                        attrs={
                            "data-action": "schematic-edit-handler#updatePoints",
                            "data-point-x": True,
                            "min": 0.0,
                            "max": 100.0,
                        }
                    ),
                ),
                FieldPanel(
                    "y",
                    widget=forms.NumberInput(
                        attrs={
                            "data-action": "schematic-edit-handler#updatePoints",
                            "data-point-y": True,
                            "min": 0.0,
                            "max": 100.0,
                        }
                    ),
                ),
            ]
        ),
    ]

    panels = [SchematicPointPanel(fields)]

    # ... def/Meta

# other classes

5c - Add a `template` to `templates/schematics/edit_handlers/schematic_edit_handler.html`

We need a way to determine how to output a point in the editor UI, and while we can build this up as a string in the Stimulus controller, let's make our lives easier to and use a HTML template element.
This template will be pre-loaded with the relevant data attributes we need and a label slot to add the label the user has entered. The nice thing about this approach is that we can modify this rendering just by changing the HTML template later.

<!-- templates/schematics/edit_handlers/schematic_edit_handler.html -->
<div class="schematic-edit-handler" data-controller="schematic-edit-handler">
  <template data-schematic-edit-handler-target="imagePointTemplate">
    <li
      class="point"
      data-schematic-edit-handler-target="imagePoint"
    >
      <span class="label"></span>
    </li>
  </template>
  {% extends "wagtailadmin/edit_handlers/object_list.html" %}
</div>

5d - Update the `SchematicEditHandler` Stimulus controller to output points

In our Stimulus Controller we will add 4 new targets; imagePoint - shows the point visually over the preview images, imagePoints - container for the imagePoint elements, imagePointTemplate - the template to use, set in the above step, point - each related model added via the InlinePanel children.
Now we can add a pointTargetConnected method, this is a powerful built-in part of the Stimulus controller where each target gets its own connected/disconnected callbacks. These also fire when initially connected so we can have a consistent way to know what InlinePanel children exist on load AND any that are added by the user later without having to do too much of our own code here.
pointTargetConnected basically adds a 'delete' button listener so we know when to re-update our points.
updatePoints does the bulk of the heavy lifting here, best to read through the code line by line to understand it. Essentially it goes through each of the point targeted elements and builds up an array of elements based on the imagePointTemplate but only if that panel is not marked as deleted. It then puts those points into a ul element next to the preview image, which itself has a target of imagePoints to be deleted and re-written whenever we need to run another update.
You should be able to validate this by reloading the page and seeing that there are a bunch of new elements added just under the image.

// static/js/schematic-edit-handler.js

class SchematicEditHandler extends Controller {
    static targets = [
      "imageInput",
      "imagePoint",
      "imagePoints",
      "imagePointTemplate",
      "point",
    ];

    connect() {
      this.setupImageInputObserver();
      this.updatePoints(); // added
    }

    /**
     * Once a new point target (for each point within the inline panel) is connected
     * add an event listener to the delete button so we know when to re-update the points.
     *
     * @param {HTMLElement} element
     */
    pointTargetConnected(element) {
      const deletePointButton = element
        .closest("[data-inline-panel-child]")
        .querySelector('[id*="DELETE-button"]');

      deletePointButton.addEventListener("click", (event) => {
        this.updatePoints(event);
      });
    }

    // setupImageInputObserver() ...
    // updateImage() ...

    /**
     * Removes the existing points shown and builds up a new list,
     * ensuring we do not add a point visually for any inline panel
     * items that have been deleted.
     */
    updatePoints() {
      if (this.hasImagePointsTarget) this.imagePointsTarget.remove();

      const template = this.imagePointTemplateTarget.content.firstElementChild;

      const points = this.pointTargets
        .reduce((points, element) => {
          const inlinePanel = element.closest("[data-inline-panel-child]");
          const isDeleted = inlinePanel.matches(".deleted");

          if (isDeleted) return points;

          return points.concat({
            id: inlinePanel.querySelector("[id$='-id']").id,
            label: element.querySelector("[data-point-label]").value,
            x: Number(element.querySelector("[data-point-x]").value),
            y: Number(element.querySelector("[data-point-y]").value),
          });
        }, [])
        .map(({ id, x, y, label }) => {
          const point = template.cloneNode(true);
          point.dataset.id = id;
          point.querySelector(".label").innerText = label;
          point.style.bottom = `${y}%`;
          point.style.left = `${x}%`;
          return point;
        });

      const newPoints = document.createElement("ol");
      newPoints.classList.add("points");
      newPoints.dataset.schematicEditHandlerTarget = "imagePoints";

      points.forEach((point) => {
        newPoints.appendChild(point);
      });

      this.imageInputTarget
        .closest(".field-content")
        .querySelector(".preview-image")
        .appendChild(newPoints);
    }
//   rest of controller definition & registration

5e - Add styles for the points in `schematic-edit-handler.css`

There is a fair bit of CSS happening here but our goal is to ensure that the points show correctly over the image and can be positioned absolutely.
We also add a few nice visuals such as a label on hover, a number that shows in the circle and a number against each inline panel so that our users can mentally map these things easier.

/* static/css/schematic-edit-handler.css */

/* preview image - container ...(keep as is) */

/* inline panels - add visible numbers */

.schematic-edit-handler .multiple {
  counter-reset: css-counter 0;
}

.schematic-edit-handler [data-inline-panel-child]:not(.deleted) {
  counter-increment: css-counter 1;
}

.schematic-edit-handler
  [data-inline-panel-child]:not(.deleted)
  > fieldset::before {
  content: counter(css-counter) ". ";
}

/* preview image - points */
/* tooltip styles based on https://blog.logrocket.com/creating-beautiful-tooltips-with-only-css/ */

.schematic-edit-handler .image-chooser .preview-image .points {
  counter-reset: css-counter 0;
}

.schematic-edit-handler .image-chooser .preview-image .point {
  counter-increment: css-counter 1;
  position: absolute;
}

.schematic-edit-handler .image-chooser .preview-image .point::before {
  background-clip: padding-box; /* ensures the 'hover' target is larger than the visible circle */
  background-color: #7c4c4c;
  border-radius: 50%;
  border: 0.25rem solid transparent;
  color: rgb(236, 236, 236);
  box-shadow: 0 -2px 0 rgba(0, 0, 0, 0.1) inset;
  content: counter(css-counter);
  text-align: center;
  line-height: 1.75rem;
  font-weight: bolder;
  display: block;
  height: 1.75rem;
  position: absolute;
  transform: translate(-50%, -50%);
  width: 1.75rem;
  z-index: 1;
}

.schematic-edit-handler .image-chooser .preview-image .point .label {
  opacity: 0; /* hide by default */
  position: absolute;

  /* vertically center */
  top: 50%;
  transform: translateY(-50%);

  /* move to right */
  left: 100%;
  margin-left: 1.25rem; /* and add a small left margin */

  /* basic styles */
  width: 5rem;
  padding: 5px;
  border-radius: 5px;
  background: #000;
  color: #fff;
  text-align: center;
  transition: opacity 300ms ease-in-out;
  z-index: 10;
}

.schematic-edit-handler .image-chooser .preview-image .point:hover .label {
  opacity: 1;
}

5f - Validation & congrats

At this point, you should be able to load the Snippet with some existing points and once the JS runs see those points over the image.
These points should align visually with the same points shown in the public-facing page (frontend) when that Schematic is used.
Back in the Wagtail editor, we should be able to add/delete/reorder points with the InlinePanel UI and the points over the image should update each time.
We should also be able to adjust the label, the number fields bit by bit and see the points also updated.
Try to break it, see what does not work and what could be improved, but congratulate yourself for getting this far and learning something new!

Part 6 (Bonus) - Drag & Drop!

If you want to go down the rabbit hole further, grab yourself a fresh shot of espresso or pour an Aeropress and sit down to make this editing experience even more epic.
We will be using the HTML Drag & Drop API here and it is strongly recommended you read through the MDN overview before proceeding.
There are some caveats, we are working with a kind of lower-level API and there are browser support considerations to make.
Ideally, we would pull in another library to do this for us but it is probably better to build it with plain old Vanilla JS first and then enhance it later once you know this is a good thing to work on.

6a - Add more data attributes to the point template

At this point, you probably can tell that data attributes are our friend with Stimulus and Django so let's add some more.
In templates/schematics/edit_handlers/schematic_edit_handler.html we will update our template (which gets used to generate the li point element).
We have added data-action="proxy.php?url=dragstart->schematic-edit-handler#pointDragStart dragend->schematic-edit-handler#pointDragEnd" - this is the data-action from Stimulus showing off how powerful this abstraction is. Here we add two event listeners for specific events and no need to worry about addEventListener as it is done for us.
We also add draggable="true" which is part of the HTML Drag & Drop API requirements.

<div class="schematic-edit-handler" data-controller="schematic-edit-handler">
  <template data-schematic-edit-handler-target="imagePointTemplate">
    <li
      class="point"
      data-schematic-edit-handler-target="imagePoint"
      data-action="dragstart->schematic-edit-handler#pointDragStart dragend->schematic-edit-handler#pointDragEnd"
      draggable="true"
    >
      <span class="label"></span>
    </li>
  </template>
  {% extends "wagtailadmin/edit_handlers/object_list.html" %}
</div>

6b - Update the `SchematicEditHandler` Controller to handle drag / drop behaviour

Firstly, we need to handle the drag (picking up) an element, these events are triggered by the data-action set above.
pointDragStart - this will tell the browser that this element can 'move' and that we want to pass the dataset.id the eventual drop for tracking. We also make the element semi-transparent to show that it is being dragged, there are lots of other ways to visually show this but this is just a basic start.
pointDragEnd - resets the style opacity back to normal.
In the connect method we call a new method setupImageDropHandlers, this does the job of our data-action attributes but we cannot easily, without a larger set of Wagtail class overrides, add these attributes so we have to add the event handlers manually.
setupImageDropHandlers - finds the preview image container and adds a listener for 'dragover' to say 'this can drop here' and then the 'drop' to do the work of updating the inputs.
addEventListener("drop"... does a fair bit, essentially it pulls in the data from the drag behaviour, this helps us find what InlinePanel child we need to update. We then work out the x/y percentages of the dropped point relative to the image preview container and round that to 2 decimal places. The x/y values are then updated in the correct fields.
A reminder that when we update the fields programmatically, the 'change' event is NOT triggered, so we finally have to ensure we call updatePoints to re-create the points again over the image container.
You can now validate this by actually doing drag & drop and checking things get updated correctly in the UI, save the values and check the front-facing page.

class SchematicEditHandler extends Controller {
    // ... targets

    connect() {
      this.setupImageInputObserver();
      this.setupImageDropHandlers();
      this.updatePoints();
    }

    /**
     * Once a new point target (for each point within the inline panel) is connected
     * add an event listener to the delete button so we know when to re-update the points.
     *
     * @param {HTMLElement} element
     */
    pointTargetConnected(element) {
      const deletePointButton = element
        .closest("[data-inline-panel-child]")
        .querySelector('[id*="DELETE-button"]');

      deletePointButton.addEventListener("click", (event) => {
        this.updatePoints(event);
      });
    }

    /**
     * Allow the point to be dragged using the 'move' effect and set its data.
     *
     * @param {DragEvent} event
     */
    pointDragStart(event) {
      event.dataTransfer.dropEffect = "move";
      event.dataTransfer.setData("text/plain", event.target.dataset.id);
      event.target.style.opacity = "0.5";
    }

    /**
     * When dragging finishes on a point, reset its opacity.
     *
     * @param {DragEvent} event
     */
    pointDragEnd({ target }) {
      target.style.opacity = "1";
    }

    // setupImageInputObserver() { ...


    /**
     * Once connected, set up the dragover and drop events on the preview image container.
     * We are unable to easily do this with `data-action` attributes in the template.
     */
    setupImageDropHandlers() {
      const previewImageContainer = this.imageInputTarget
        .closest(".field-content")
        .querySelector(".preview-image");

      previewImageContainer.addEventListener("dragover", (event) => {
        event.preventDefault();
        event.dataTransfer.dropEffect = "move";
      });

      previewImageContainer.addEventListener("drop", (event) => {
        event.preventDefault();

        const inputId = event.dataTransfer.getData("text/plain");
        const { height, width } = previewImageContainer.getBoundingClientRect();

        const xNumber = event.offsetX / width + Number.EPSILON;
        const x = Math.round(xNumber * 10000) / 100;
        const yNumber = 1 - event.offsetY / height + Number.EPSILON;
        const y = Math.round(yNumber * 10000) / 100;

        const inlinePanel = document
          .getElementById(inputId)
          .closest("[data-inline-panel-child]");

        inlinePanel.querySelector("[data-point-x]").value = x;
        inlinePanel.querySelector("[data-point-y]").value = y;

        this.updatePoints(event);
      });
    }

    // updateImage(newValue) { ... etc & rest of controller

Finishing Up & Next Steps

You should now have a functional user interface where we can build a schematic snippet with points visually shown over the image in the editor and in the front-facing page that uses it.
We should be able to update the points via their fields and if you did step 6, via drag and drop on the actual points within the editor.
I would love to hear your feedback on this post, let me know what issues you encountered or where you could see improvements.
If you liked this, please add a comment or reaction to the post or even shout me a coffee.
You can see the full working code, broken up into discrete commits, on my schematic-builder tutorial branch.

Further Improvements

Here are some ideas for improvements you can give a go at yourself.

Add colours for points to align with the colours in the inline panels so that the point/field mapping can be easier to work with.
Add better keyboard control, focusable elements and up/down/left/right 'nudging', a lot of this can be done via adding more data-action attributes on the point template and working from there.
Add better handling of drag/drop on mobile devices, the HTML5 Drag & Drop API does not support mobile devices great, maybe an external library would be good to explore.

Why Stimulus and not ... other things

I originally built this in late 2021 when doing some consulting, at the time I called the model Diagram but Schematic sounded better.

The original implementation was done in jQuery and adding all the event listeners to the InlinePanel ended up being quite a mess, I could not get a bunch of the functionality to work well that is in this final tutorial and the parts of the JS/HTML were all over the place so it would have been hard to maintain.

Since then, I have been investigating some options for a lightweight JS framework in the Wagtail core codebase. Stimulus kept popping up in discussions but I initially wrote it off and was expecting Alpine.js to be a solid candidate. However, Alpine.js has a much larger API and also has a large CSP compliance risk that pretty much writes it off (yes, the docs say they have a CSP version but as of writing that is not actually released or working, also it pretty much negates all the benefits of Alpine).

After doing some small things with Stimulus, I thought this code I had written would be a good example of a semi-larger thing that needs to interact with existing DOM and dynamic DOM elements without having to dig into the other JS used by the InlinePanel code.

I do not know where the Wagtail decision will head, you can read more of the UI Technical Debt discussion if you want. However, for lightweight JS interaction where you do not have, or need to have, full control over the entire DOM. Stimulus appears to be a really solid choice without getting in the way. While letting you work in 'vanilla' JS for all the real work and helps you with the common things like targeting elements/initialising JS behaviour and managing event listeners.

Updates

Since posting, I have been made aware of an existing Wagtail package that does something similar https://github.com/neon-jungle/wagtail-annotations - I have not tried it but it is good to be aware of

Adding Tasks with a Checklist to Wagtail Workflows

LB (Ben Johnston) — Wed, 22 Sep 2021 07:54:45 +0000

Goal: Create a simple way for Wagtail's CMS admin users to manage custom Workflow Tasks with checklists.

Why: Wagtail's Workflow feature is incredibly powerful and can be leveraged to help guide our users through their Page publishing process easier.

Journey

Note: Feel free to skip if you just want to see the code.

One of my favourite books is The Checklist Manifesto: How to Get Things Right and another I am reading right now is Everything in Its Place: The Power of Mise-En-Place to Organise Your Life, Work, and Mind. The core message that is in common with these is the simple practice of writing a checklist or a plan before you start and where possible, manage those checklists for future work of the same kind.

Now, checklists can become a burden to those who are forced to mindlessly tick 700 boxes they never read for the thousandth time this week, so as in all things there is a balance.

However, I do honestly believe that simple checklists for recurring processes can help both new people to a process and those who are veterans, remember the critical aspects of what they do day to day.

One visceral memory I have of checklists is when my son, Leo, was born. My wife had to go into an emergency C-section and while I won't go into any more details, I do vividly remember up on the wall were two huge checklists (just like described in the Checklist Manifesto) with four or five key steps regarding the surgery process.

This memory is obviously key to me for more than just checklists, I got to see my amazing son for the first time. I often think back to that moment and wonder how many times a day, or that week those in the room would have done the same operation but how many lives a simple checklist on the wall would have saved.

It also puts into perspective the code I write and the processes we design for our team. Most likely what we do is not something that could risk the lives of others but nonetheless, we all have a part to play in helping our teams be excellent and remember the little but non-trivial things they do in their job.

So that leads us to Wagtail's Workflow system, which was introduced in Wagtail 2.10. This system replaced the previous moderation workflow and was a sponsored feature (a special thanks to those who contribute to Open Source / Free Software) and may have flown under the radar for many of those who use Wagtail.

However, this Workflow feature has been built from the ground up to be very extensible and even borrows a lot of the approaches from Wagtail's core Page model itself where a mix of custom code and CMS Admin editing can be combined to make something incredibly flexible and powerful.

What We Are Building

In this tutorial, you may have guessed, we will be putting together a way for Workflow Tasks to be created with a checklist and then that checklist is presented to those when they approve that specific step in the workflow.

This means that Wagtail Admin users could create a Workflow Checklist Task that is specifically for approval of types of pages or a generic one for all pages.

Tutorial

Step 0 - Getting Started

It is assumed at this point you have Wagtail running locally and have a basic understanding of the Workflow system from a user's perspective.
If not, it would be best to start with the Wagtail Getting Started guide.
It is also assumed you have a basic understanding of Django's Model and Form systems, although if not maybe this Tutorial will be a good way to get some deeper understanding.
Versions:
- Django 3.2
- Wagtail 2.14

Step 1 - Create the `ChecklistApprovalTask` Model

Firstly, we need to think about what this Task model is and what we want to let the user fill out.
The Wagtail Workflow area has a few key models, the main being a Workflow and a Task.
When creating a Task in the Wagtail admin, the user is presented with what kind of Task to use (similar to when creating a new Page), this UI only shows if there are more than one kind of Task models available (Wagtail will search through your models and find all those that are subclasses of the core Task model).
So, the Task model we are creating contains the fields that the user enters for multiple Tasks of that 'kind', which are then mapped to one or more user created Workflows.
For our base Task model in that case, we do not actually need to define sets of checklists but rather a way for users to enter a set of checklist items and the simplest way to do this would be with a multi-line TextField where each line becomes a checklist item.
Along with that, we will also add a field to determine whether this Task will require ALL checklist items to be ticked when submitting, this way the checklists can be a 'suggestion' or a 'requirement' on a per Task instance basis.
It is important to remember that the Task instance can be changed at any time, so the checklist the user views today could be different tomorrow and as such we will keep this implementation simpler by not tracking that the checklist was submitted and which items were ticked but that could be implemented as an enhancement down the road.
The following code is loosely based on the Wagtail docs How to add new Task Types section, however, to save a bunch of reimplementation, instead of building all the user logic on our own we will just extend the existing (built-in) GroupApprovalTask.
The reason for extending GroupApprovalTask is that our ChecklistApprovalTask is very similar, we want to assign a user group that can approve/reject as a Task but we just want to allow the approve step to show extra content in the approval screen.
Once you implement the code below you should be able to create a new Workflow and add one of the new ChecklistApprovalTask instances. For the rest of this tutorial it would be good to have one ready to go to test with as we build out the features.

Code `models.py`

Create a new model ChecklistApprovalTask that extends GroupApprovalTask.
This new model will contain two fields; checklist a TextField which will be used to generate the checklist items (per line), and a is_checklist_required BooleanField which will be ticked to force each checklist item to be ticked.
Similar to Page panels, we can use the admin_form_fields class attribute to define a List of fields that will be shown when a user creates/edits this Task.
The last part of our model is to leverage the get_description class method and the meta verbose names to provide a user-facing description & name of this Task type, plus we want to override the one that comes with the GroupApprovalTask class.
Once you have built your model, run django-admin makemigrations and then django-admin migrate to apply your new model.


from django.db import models

from wagtail.core.models import GroupApprovalTask


class ChecklistApprovalTask(GroupApprovalTask):
    """
    Custom task type where all the features of the GroupApprovalTask will exist but
    with the ability to define a custom checklist that may be required to be checked for
    Approval of this step. Checklist field will be a multi-line field, each line being
    one checklist item.
    """

    # Reminder: Already has 'groups' field as we are extending `GroupApprovalTask`

    checklist = models.TextField(
        "Checklist",
        help_text="Each line will become a checklist item shown on the Approve step.",
    )

    is_checklist_required = models.BooleanField(
        "Required",
        help_text="If required, all items in the checklist must be ticked to approve.",
        blank=True,
    )

    admin_form_fields = GroupApprovalTask.admin_form_fields + [
        "checklist",
        "is_checklist_required",
    ]

    @classmethod
    def get_description(cls):
        return (
            "Members of the chosen User Groups can approve this task with a checklist."
        )

    class Meta:
        verbose_name = "Checklist approval task"
        verbose_name_plural = "Checklist approval tasks"

Before you continue: Check that when you create a new Task you can now see that there are two options available; 'Group approval task' and 'Checklist approval task'.

Step 2 - Revise the Actions to Always Show the Form Modal

The built-in GroupApprovalTask, when in a Workflow, will give the user two options; 'Approve and Publish' and 'Approve with Comment and Publish', the difference is that the one with the comment will open a form modal when clicked where the user can fill out a comment.
What we want to do for our custom Task is to ensure that the approval step can only be completed with a form modal variant, and in this form we will show the checklist.
Each Task has a method get_actions which will return a list of (action_name, action_verbose_name, action_requires_additional_data_from_modal) tuples.
We will now revise this method to leverage the existing check if the user is in the right group but only return one option with the form modal being required, we will also ensure there is a reject action allowed.

Code `models.py`

Within the CrosscheckApprovalTask built above, create a new method get_actions, this should copy the user check from the GroupApprovalTask implementation but only return two actions.

class CrosscheckApprovalTask(GroupApprovalTask):
    # ... checklist etc, from above step

    def get_actions(self, page, user):
        """
        Customise the actions returned to have a reject and only one approve.
        The approve will have a third value as True which indicates a form is
        required.
        """

        if self.groups.filter(id__in=user.groups.all()).exists() or user.is_superuser:
            REJECT = ("reject", "Request changes", True)
            APPROVE = ("approve", "Approve", True)
            return [REJECT, APPROVE]

        return []

    # ... @classmethod etc

Before you continue: Check that when you put an existing Page into the workflow that contains this new task type, when approving the change it will show only one option 'Approve and Publish' and this should open a form modal. No need to approve just yet though.

Step 3 - Build a Basic Checklist Form

We now need to create a custom form that leverages the existing form that GroupApprovalTask makes, this form needs to have a MultipleChoiceField where each of the choices is a line in our Task model's checklist field.
We also want to make the form field dynamic based on the Task model's is_checklist_required saved value.
To override the Task form we can add a get_form_for_action method and when the action is 'approve' we can provide a custom Form.
The things we need to answer is what form to extend (we want to ensure we get the comment field still), how do we ensure that the checklist values do not try to be 'saved' to the TaskState (the model that reflects each state for a Task as it is processed).
If we take a look at the implementation of get_form_for_action on the GroupApprovalTask we can see that it returns a TaskStateCommentForm which extends a Django Form with one field, comments.

Code `models.py`

To build a dynamic Class in Python, we can declare a new class in a function or we can also use the type built-in function, passing in three args. A name, base classes tuple and a dict where each key will be used to generate dynamic attributes (fields) and methods (e.g. the clean method).
In this dynamic class we will extend whatever the super's get_form_for_action returns, this way we do not need to think about what this is in the code, but know that it is the TaskStateCommentForm above.
We will also need to add a clean method that will remove any checklist values that are submitted (as we do not want to save these).
We will need to add a field, checklist, which we will pull out to a new class method get_checklist_field which can return a forms.MultipleChoiceField that has dynamic values for required and the choices based on the Task instance. Note: The default widget used for this field is SelectMultiple which is a bit cluncky, but we will enhance that in the next step.
We will also want to ensure that our checklist field shows before the comment field, for that we can dynamically add a field_order attribute.

from django import forms
from django.db import models
from django.utils.translation import gettext_lazy as _

# ... other imports

class ChecklistApprovalTask(GroupApprovalTask):

    # ... checklist etc, from above step


    def get_checklist_field(self):
        """
        Prepare a form field that is a list of checklist boxes for each line in the
        checklist on this Task instance.
        """

        required = self.is_checklist_required

        field = dict(label=_("Checklist"), required=required)

        field["choices"] = [
            (index, label) for index, label in enumerate(self.checklist.splitlines())
        ]

        return forms.MultipleChoiceField(**field)

    def get_form_for_action(self, action):
        """
        If the action is 'approve', return a new class (using type) that has access
        to the checklist items as a field based on this Task's instance.
        """

        form_class = super().get_form_for_action(action)

        if action == "approve":

            def clean(form):
                """
                When this form's clean method is processed (on a POST), ensure we do not pass
                the 'checklist' data any further as no handling of this data is built.
                """
                cleaned_data = super(form_class, form).clean()
                if "checklist" in cleaned_data:
                    del cleaned_data["checklist"]
                return cleaned_data

            return type(
                str("ChecklistApprovalTaskForm"),
                (form_class,),
                dict(
                    checklist=self.get_checklist_field(),
                    clean=clean,
                    field_order=["checklist", "comment"],
                ),
            )

        return form_class

    # ... @classmethod etc

Before you continue: Check that when you click the Approve step on a Page with this Task, you now see a list of checklist items and it is required (or not, based on the data saved on the original Task type).

Step 4 - Enhance the Checklist Form

Now, we will modify the help_text, validators and the widget of our field generated in the method get_checklist_field.
The goals here are to ensure that, when the checklist is required, we show and actually validate against all items being ticked.
I find all of this pretty amazing, how powerful it is to build up blocks of built-in functions and logic into what we want without really writing much code ourselves, just calling the right methods/functions/classes.

Code `models.py`

help_text needs to be a dynamic value based on the required value we set up in the previous step.
If the checklist is required, we will leverage the built-in MinLengthValidator, while this is usually used to validate string length it can be used just the same for validating the length of the list of values provided to the field (in our case it will be a list of indices). We will also pass in a custom message kwarg to this validator so it makes sense to the user.
For the widget we will use the built-in CheckboxSelectMultiple, but note in the docs that even if we set required on the field the checkbox will not actually put required on the inputs HTML attributes so we need to pass in an extra attrs to the widget to handle this.
Note: the only parts added below are the min_length_validator, help_text, validators and widget lines.

from django import forms
from django.core.validators import MinLengthValidator
from django.db import models
from django.utils.translation import gettext_lazy as _, ngettext_lazy

# ... other imports

class ChecklistApprovalTask(GroupApprovalTask):

    # ... checklist etc, from above step

    def get_checklist_field(self):
        """
        Prepare a form field that is a list of checklist boxes for each line in the
        checklist on this Task instance.
        """

        required = self.is_checklist_required

        field = dict(label=_("Checklist"), required=required)

        field["choices"] = [
            (index, label) for index, label in enumerate(self.checklist.splitlines())
        ]

        min_length_validator = MinLengthValidator(
            len(field["choices"]),
            message=ngettext_lazy(
                "Only %(show_value)d item has been checked (all %(limit_value)d are required).",
                "Only %(show_value)d items have been checked (all %(limit_value)d are required).",
                "show_value",
            ),
        )

        field["help_text"] = (
            _("Please check all items.") if required else _("Please review all items.")
        )

        field["validators"] = [min_length_validator] if required else []

        field["widget"] = forms.CheckboxSelectMultiple(
            # required attr needed as not rendered by default (even if field required)
            # https://docs.djangoproject.com/en/3.2/ref/forms/widgets/#django.forms.CheckboxSelectMultiple
            attrs={"required": "required"} if required else {}
        )

        return forms.MultipleChoiceField(**field)

Before you continue: Check that the Approve modal form now contains actual checkboxes for each checklist item and that validation works as expected.

Final Implementation

You should now have a fully functional new Task type where your CMS admin users can create for specific workflows that leverage existing user group approval logic along with custom checklists on a per Task instance.
You can view the steps on the tutorial/workflow-checklist branch or the final code in the models.py file.
I think it is really important to now require all the checklist items by default, but some will insist that this is required no doubt, but checklists work better as reminders and not rigid rules in this context.
Please comment in response if you think something is missing here or have some other useful content relating to Wagtail Workflows that might be helpful.
Thanks to my brother Sam for proofing and to Danielle MacInnes for the cover photo.

Future Improvements Ideas

Adding a description field to the Task so that users can put content above the checklist that explains part of a process.
Storing the checklist values (or maybe how many were checked), if that is useful for reporting, remember that the Page history will contain which users Approved the step and that may be enough as it is.
Other Form content that applies to an Approval (or some other step like Rejection) and needs to be dynamic, maybe even requiring a comment when the workflow is Rejected.
If you end up building one of these, even as a Github Gist, be sure to put a link to it in the comments.

How to create a Zen (Focused) mode for the Wagtail CMS admin

LB (Ben Johnston) — Sun, 05 Sep 2021 10:30:14 +0000

Hi, I am LB, a full stack developer on the core team for the Watail CMS and here is a tutorial that will hopefully teach you a bit about Wagtail but also make life better for content editors.

Goal: Implement a simple way for users within the Wagtail CMS admin interface to focus on a sub-set of fields, hiding menus/headers and other fields.
Why: Being able to switch 'hats' from content management to content writing is often difficult, providing a different editing mode may allow for focusing.
How: Using the browser's built-in Fullscreen API to provide a native and accessible experience on most new devices and browsers.

Overview

The inspiration for this is the VSCode editor's Zen mode that allows you to switch to a fullscreen version of your current editor that hides menus/footers and other UI elements.
Create a custom Edit Handler (Panel) that works the same as MultiFieldPanel which can be used to wrap some fields on a per-model basis (e.g. the main content fields).
Use the Wagtail editor interface hooks system to inject custom JS & CSS files that will do the admin frontend work.

Tutorial

Step 0 - Getting Started

This tutorial was written using Wagtail version 2.14, however, you should be able to use this on older versions.
It is assumed you have a working Wagtail project running, otherwise, you will need to go through the Wagtail getting started docs.
Read through the MDN Fullscreen API docs.
It is worth taking a quick look at the Wagtail source code for the MultiFieldPanel implementation (code below), note that it has a custom template and classes and that is pretty much it.

class MultiFieldPanel(BaseCompositeEditHandler):
    template = "wagtailadmin/edit_handlers/multi_field_panel.html"

    def classes(self):
        classes = super().classes()
        classes.append("multi-field")
        return classes

Step 1 - Build the custom Panel

Create a new file within your app called edit_handers.py and then a custom class that extends MultiFieldPanel.
We will create a new class ZenModeMultiFieldPanel and override one attribite template and one method classes.
For the template, we will need to create a new file templates/edit_handlers/zen_mode_multi_field_panel.html that will include the existing "wagtailadmin/edit_handlers/multi_field_panel.html" template.
In this new template we will add two buttons, an activate and an exit button, by default the exit button will have a class 'hidden'.
In the classes method, we will append one class 'zen-mode-panel' to make it easier to target the styles to these Panels.
The full code for this step is below.
Once done, find an existing Page model and wrap one or more fields within this ZenModeMultiFieldPanel, for example:

        ZenModeMultiFieldPanel(
            [FieldPanel("introduction", classname="full"), StreamFieldPanel("body")],
            heading="Content",
        ),

edit_handlers.py

from wagtail.admin.edit_handlers import MultiFieldPanel


class ZenModeMultiFieldPanel(MultiFieldPanel):

    template = "myapp/edit_handlers/zen_mode_multi_field_panel.html"

    def classes(self):
        classes = super().classes()
        classes.append("zen-mode-panel")
        return classes

templates/edit_handlers/zen_mode_multi_field_panel.html

{% load wagtailadmin_tags %}

<button
  class="zen-mode activate button button-small button-secondary button--icon"
>
  Zen {% icon name="collapse-up" wrapped=1 %}
</button>
<button
  class="zen-mode exit button button-small button-secondary button--icon hidden"
>
  Exit {% icon name="collapse-down" wrapped=1 %}
</button>

{% include "wagtailadmin/edit_handlers/multi_field_panel.html" %}

Before you continue

Once complete, you should be able to see this new Panel in the browser and see the button + classes on the panel container.
Note that the button may not be visible as it is 'behind' the header, that is fine for now, just check it is in the DOM.

Step 2 - Add initial CSS & JS injection via Hooks

Firstly, ensure that your static files are set up in Django, if this is not already in place you will need to read the docs about Managing static files.
Create a wagtail_hooks.py file if you do not already have one within your main app.
Create a CSS file in your static folder static/css/zen-mode-multi-field-panel.css and put a basic CSS selector to position the buttons and to test the CSS is being imported.
In your wagtail_hooks.py file, use the insert_global_admin_css hook to load the static CSS file.
Create a JS file in your static folder static/js/zen-mode-multi-field-panel.js and put a basic JS initiation file with a selector logging out each Zen MultiFieldPanel based on the classes set in the .zen-mode-panel class.
In your wagtail_hooks.py file, use the insert_global_admin_js hook to load the static JS file.
Note: You can use the page editor scoped hooks insert_editor_css & insert_editor_js, however this means that this custom Panel will not work as desired when using it in other places (such as Snippet or ModelAdmin editing) throughout the admin.
Reminder: When adding static files, you will need to restart your server for these files to be loaded.

static/css/zen-mode-multi-field-panel.css

.object.multi-field.zen-mode-panel .button.zen-mode {
  position: absolute;
  right: 4rem;
  z-index: 100;
  top: 0.5rem;
}

.object.multi-field.zen-mode-panel .button.zen-mode.hidden {
  display: none;
}

static/js/zen-mode-multi-field-panel.js

window.addEventListener("DOMContentLoaded", () => {
  document.querySelectorAll(".zen-mode-panel").forEach((panel) => {
    console.log("found panel!", { panel });
  });
});

myapp/wagtail_hooks.py

from django.utils.html import format_html
from django.templatetags.static import static
from wagtail.core import hooks


@hooks.register("insert_global_admin_css")
def global_admin_zen_mode_multi_field_panel_css():
    return format_html(
        '<link rel="stylesheet" href="{}">',
        static("css/zen-mode-multi-field-panel.css"),
    )


@hooks.register("insert_global_admin_js")
def global_adminzen_mode_multi_field_panel__js():
    return format_html(
        '<script src="{}"></script>',
        static("js/zen-mode-multi-field-panel.js"),
    )

Before you continue

Once complete, you should be able to reload your development server and load up the Page editor and see the following;
1. The Zen button should be visible and the Exit button should not.
2. You should see an output in your browser console with logging of the panel.

Step 3 - Get JS fully functional

Now we will work through the JS interaction, our goal is to use the fullscreen API to make the 'Zen' button trigger the fullscreen mode on the panel's container div and then provide TWO ways to exit, the built-in 'esc' press handling and the pressing of the button 'exit'.
There will still be further CSS refinements to do, but the goal for this step is to get the button functionality working.
Firstly we use document.querySelectorAll(".zen-mode-panel").forEach(... to find ALL of the zen-mode-panel (this means we can support multiple of these throughout the editor if needed).
For each panel we will find that panel's activate and exit buttons and set them to a variable activateButton and exitButton.
Then we check the browser can actually support fullscreen mode by checking that a function requestFullscreen exists on the panel element, if it does not we add the class 'hidden' to the activateButton and return so that the button is hidden and no fulscreen activation actions can take place.
After this, we create a listener on the activateButton's onClick event that will requestFullscreen on the panel, it also needs to call event.preventDefault() so that the form does not submit.
Create a listener on the exitButton's onClick event that will exitFullscreen on the document (important, not the panel). It also needs to call event.preventDefault() so that the form does not submit.
The last part of the JS is to handle when the fullscreen mode triggers (and exits) to update some classes on our elements, we want to add fullscreen-active to the panel container and also switch the visibility of the activate/exit button.
Note: The reason we are adding an event handler onfullscreenchange on the panel is that it simplifies the overall logic, avoids content from getting out of sync and means the built-in browser handling of esc press will work without issues.

static/js/zen-mode-multi-field-panel.js

window.addEventListener("DOMContentLoaded", () => {
  const FULLSCREEN_ACTIVE = "fullscreen-active";
  const HIDDEN = "hidden";

  document.querySelectorAll(".zen-mode-panel").forEach((panel) => {
    const activateButton = panel.querySelector(".zen-mode.activate");
    const exitButton = panel.querySelector(".zen-mode.exit");

    // ---- Hide button & return early if fullscreen is not supported ---- //

    if (!panel.requestFullscreen) {
      return activateButton.classList.toggle(HIDDEN);
    }

    // ---- Add button event listeners ---- //

    activateButton.onclick = (event) => {
      event.preventDefault(); // ensure the button does not submit the form
      panel.requestFullscreen();
    };

    exitButton.onclick = (event) => {
      event.preventDefault(); // ensure the button does not submit the form
      document.exitFullscreen();
    };

    // ---- Add fullscreen event listener ---- //

    panel.onfullscreenchange = (event) => {
      panel.classList.toggle(FULLSCREEN_ACTIVE);
      activateButton.classList.toggle(HIDDEN);
      exitButton.classList.toggle(HIDDEN);
    };
  });
});

Before you continue

Once complete, you should be able to reload your development server and load up the Page editor and see the following;
1. The Zen button should be visible and when pressed, the browser should show the panel content only in fullscreen.
2. You should be able to press the 'exit' button (which becomes visible) and not see the 'zen' button when in fullscreen.
3. When 'exit' is pressed (or 'esc' on the keyboard) the buttons should switch back and the fullscreen mode should cancel.

Step 4 - Refine CSS for various scenarios

Finally, our goal is to refine our CSS, this is not a perfect step but will be enough to get the UI working.
You will have noticed that the fullscreen mode has a black background, we can fix this with the dynamic class that will get added to the container when in fullscreen fullscreen-active and a background-color.
The last part is some tweaks to how the fields show and how scrolling is handled for longer field content (e.g. long StreamFields). We set a max-width none so content goes to full width, a max-height and overflow-scroll so that content scrolls and then some padding.

static/css/zen-mode-multi-field-panel.css

.object.multi-field.zen-mode-panel .button.zen-mode {
  position: absolute;
  right: 4rem;
  z-index: 100;
  top: 0.5rem;
}

.object.multi-field.zen-mode-panel .button.zen-mode.hidden {
  display: none;
}

.object.multi-field.zen-mode-panel.fullscreen-active {
  background-color: white;
}

.object.multi-field.zen-mode-panel.fullscreen-active fieldset {
  /* ensure that scrolling within content still works */
  max-width: none;
  max-height: calc(100vh - 6rem);
  overflow: scroll;
  padding-right: 1rem;
  padding-bottom: 2rem;
}

Final Implementation

Once complete, you should be able to reload your development server and when in fullscreen mode see a white background and be able to scroll nicely when field content is too long for the screen.
You can view the final code on my lb-/bakerydemo tutorial branch.

Future Improvements & Links

It would be great to have a global keyboard shortcut, similar to the VSCode Zen mode, however, we would need to consider the scenarios where more than one ZenModeMultiFieldPanel is available.
Browser Compatibility could be lacking, this will definitely not support IE11 and there could still be some issues on mobile browsers.
Dark mode, while I do think it is not something useful everywhere, in this Zen mode it might be something helpful.
fscreen provides an API that will work better across multiple browsers, it would be good to use that in the future.

How to build an interactive guide for users in the Wagtail CMS admin

LB (Ben Johnston) — Thu, 19 Aug 2021 11:55:12 +0000

Goal: Create a simple way for contextual guides to be shown to users while using Wagtail.

Why: Wagtail's UI is quite intuitive, however, when using anything for the first time it is great to have a bit of help.

How: We want to provide a way for these guides to be maintained by the admin users (avoiding hard-coded content), they should be simple to create and be shown on specific pages when available.

Implementation Overview

Each guide will be able to be mapped to a page within the admin.
Each guide will be able to have one or more steps with basic text content and the option to align a step with a UI element.
If a guide is available for the current page it will be highlighted in the menu. If no guide is available for the current page the menu will simply load a listing of all guides.
Shepherd.js will be used to present the UI steps in an interactive way, this is a great JS library that allows a series of 'steps' to be declared that takes the user through a tour as a series of popovers, some steps can be aligned to an element in the UI and that element will be highlighted.
Wagtail modelAdmin and hooks will be used to add the customisation.
We can leverage content from the Editor's guide to Wagtail for some of the initial guides.

Versions

Django 3.2
Wagtail 2.14
Shepherd.js 8.3.1

Tutorial

0. Before you start

It is assumed that you will have a Wagtail application running, if not you can use the Wagtail Bakery Demo as your starting point.
It is assumed you will have a basic knowledge of Django and Wagtail and are comfortable with creating Django Models and Python Classes.
It is assumed you have a basic knowledge of Javascript and CSS, you can copy & paste the code but it is good to understand what is happening.

1. Create the guide app

Use the Django startapp command to create a new app 'guide' which will contain all the new models and code for this feature.
Run django-admin startapp guide
Update the settings INSTALLED_APPS with the new guide app created
Run the initial migration ./manage.py makemigrations guide

INSTALLED_APPS = [
  # ...
  'guide',
  # ... wagtail & django items
]

Cross-check (before you continue)

You should have a new app folder guide with models, views, etc.
You should be able to run the app without errors.

2. Create the model

We will create two new models; Guide and GuideStep.
Where Guide contains a title (for searching), a URL path (to determine what admin UI page it should be shown on) and links to one or more steps. We want to provide the user with a way to order the steps, even re-order them later.
In the Guide we are using the edit_handler to build up a tabbed UI so that some fields will be separate.
Where GuideStep contains a title, text and an optional element selector. The data needed is based on the options that can be passed to the Shepherd.js steps.
This code is based on the Inline Panels and Model Clusters instructions in the Wagtail docs.
You may need to add 'modelcluster' to your INSTALLED_APPS if you are having troubles using this when defining your model.
After creating the models, remember to run migrations & migrate /manage.py makemigrations & /manage.py migrate.

# guide/models.py
from django.db import models

from modelcluster.fields import ParentalKey
from modelcluster.models import ClusterableModel

from wagtail.admin.edit_handlers import (
    FieldPanel,
    InlinePanel,
    ObjectList,
    TabbedInterface,
)
from wagtail.core.models import Orderable


class GuideStep(models.Model):
    """
    Each step is a model to represent the step used by
    https://shepherdjs.dev/docs/Step.html
    This is an abstract model as `GuideRelatedStep` will be used for the actual model with a relation
    """

    title = models.CharField(max_length=255)
    text = models.CharField(max_length=255)
    element = models.CharField(max_length=255, blank=True)

    panels = [
        FieldPanel("title"),
        FieldPanel("text"),
        FieldPanel("element"),
    ]

    class Meta:
        abstract = True


class GuideRelatedStep(Orderable, GuideStep):
    """
    Creates an orderable (user can re-order in the admin) and related 'step'
    Will be a many to one relation against `Guide`
    """

    guide = ParentalKey("guide.Guide", on_delete=models.CASCADE, related_name="steps")


class Guide(ClusterableModel):
    """
    `ClusterableModel` used to ensure that this model can have orderable relations
    using the modelcluster library (similar to ForeignKey).
    edit_handler
    """

    title = models.CharField(max_length=255)
    # steps - see GuideRelatedStep
    url_path = models.CharField(max_length=255, blank=True)

    content_panels = [
        FieldPanel("title"),
        InlinePanel("steps", label="Steps", min_num=1),
    ]

    settings_panels = [
        FieldPanel("url_path"),
    ]

    edit_handler = TabbedInterface(
        [
            ObjectList(content_panels, heading="Content"),
            ObjectList(settings_panels, heading="Settings"),
        ]
    )

Cross-check (before you continue)

You should have a new file guide/migrations/001_initial.py with your migration.
You should be able to run the app without errors.

3. Add the hooks for the `modelAdmin`

Using the modelAdmin system we will create a basic admin module for our Guide model, this code is based on the modelAdmin example in the docs.
Remember to add 'wagtail.contrib.modeladmin' to your INSTALLED_APPS.
Using modelAdmin will set up a new menu item in the sidebar by adding the code below to a new file wagtail_hooks.py.
Note that we have turned ON inspect_view_enabled, this is so that a read-only view of each guide is available and it also ensures that non-editors of this model can be given access to this data, these permissions are checked for showing the menu item also.
Remember to give all users permission to 'inspect' Guides (otherwise the menu will not show).
It would be good to now add at least one Guide with the following values.

- Title: Dashboard
- URL Path: /admin/ **(on the settings tab*)*
- Step 1:
  - Title: Dashboard
  - Text: Clicking the logo returns you to your Dashboard
  - Element: a.logo
- Step 2:
  - Title: Search
  - Text: Search through to find any Pages, Documents, or Images
  - Element: .nav-search > div
- Step 3:
  - Title: Explorer Menu (Pages)
  - Text: Click the Pages button in the sidebar to open the explorer. This allows you to navigate through the sections of the site.
  - Element: .menu-item[data-explorer-menu-item]
- Step 4:
  - Title: Done
  - Text: That's it for now, keep an eye out for the Help menu item on other pages.
  - Element: (leave blank)

# guide/wagtail_hooks.py
from wagtail.contrib.modeladmin.options import ModelAdmin, modeladmin_register

from .models import Guide


class GuideAdmin(ModelAdmin):
    menu_label = "Guide"
    model = Guide
    menu_icon = "help"
    menu_order = 8000
    list_display = ("title", "url_path")
    search_fields = ("title", "url_path")
    inspect_view_enabled = True


modeladmin_register(GuideAdmin)

Cross-check (before you continue)

You should now see a menu item 'Guide' in the left sidebar within Wagtail admin.
You should be able to log in as a non-admin user and still see this sidebar menu item.

4. Customise the `Guide` menu item

Our goal now is to create a custom MenuItem, this is a Wagtail class that is used to generate the content for each sidebar menu item.
Instead of extending the class from wagtail.admin.menu import MenuItem we will be using the class from wagtail.contrib.modeladmin.menus import ModelAdminMenuItem. This is because the ModelAdminMenuItem contains some specific ModelAdmin logic we want to keep.
Each MenuItem has a method get_context which provides the template context to the menu_item.html template.
This template accepts attr_string and classnames which can be leveraged to inject content.

4a. Add a method to the `Guide` model

This method get_data_for_request will allow us to find the first Guide instance where the URL path of the request aligns with the url_path in the guide.
For example - if a Guide is created with the URL path '/admin/images/' then we want to return data about that when we are on that page in the admin. If a Guide is created with the path '/admin/images/#/' then we want the guide to be found whenever is editing any image (note the use of the hash).
path_to_match = re.sub('[\d]+', '#', request.path) will take the current request path (e.g. /admin/images/53/) and convert it to one where any numbers are replaced with a hash (e.g. /admin/images/#/), this is a simple way to allow fuzzy URL matching.
The data structure returned is intentionally creating a JSON string so it is easier to pass into our model as a data-attribute.

# guide/models.py

class Guide(ClusterableModel):
    #...

    @classmethod
    def get_data_for_request(cls, request):
        """
        Returns a dict with data to be sent to the client (for the shepherd.js library)
        """

        path_to_match = re.sub("[\d]+", "#", request.path)

        guide = cls.objects.filter(url_path=path_to_match).first()

        if guide:
            steps = [
                {
                    "title": step.title,
                    "text": step.text,
                    "element": step.element,
                }
                for step in guide.steps.all()
            ]

            data = {"steps": steps, "title": guide.title}

            value_json = json.dumps(
                data,
                separators=(",", ":"),
            )

            data["value_json"] = value_json

            return data

        return None

4b. Create a `menu.py` file

This will contain our new menu class, we could put this code in the wagtail_hooks.py file but it is nice to isolate this logic if possible.
Here we override the get_context method for the MenuItem and first call the super's get_context method and then add two items.
Firstly, we add attr_string and build a data-help attribute which will contain the JSON output of our guide (if found). Note: There are many ways to pass data to the client, this is the simplest but it is not perfect.
Secondly, we extend the classnames item with a help-available class if we know we have found a matching Guide for the current admin page.
Remember to return context, otherwise you will just get a blank menu item.

# guide/menu.py

from django.utils.html import format_html

from wagtail.contrib.modeladmin.menus import ModelAdminMenuItem

from .models import Guide


class GuideAdminMenuItem(ModelAdminMenuItem):
    def get_context(self, request):
        context = super().get_context(request)

        data = Guide.get_data_for_request(request)

        if data:

            context["attr_string"] = format_html('data-help="{}"', data["value_json"])
            context["classnames"] = context["classnames"] + " help-available"

        return context

4c. Update the Guide admin to use the custom menu item

By overriding the get_menu_item we can leverage our custom GuideAdminMenuItem instead of the default one.

# guide/wagtail_hooks.py
from wagtail.contrib.modeladmin.options import ModelAdmin, modeladmin_register

from .menu import GuideAdminMenuItem # added
from .models import Guide

class GuideAdmin(ModelAdmin):
    # ...
    def get_menu_item(self, order=None):
        """
        Utilised by Wagtail's 'register_menu_item' hook to create a menu item
        to access the listing view, or can be called by ModelAdminGroup
        to create a SubMenu
        """
        return GuideAdminMenuItem(self, order or self.get_menu_order())

Cross-check (before you continue)

When you load the Dashboard page in the Wagtail admin, you should be able to inspect (browser developer tools) the 'Guide' menu item and see the classes & custom data-help attribute.

5. Adding JS & CSS

There is a fair bit to unpack in this step, but the goal is to provide the right options to the Shepherd.js library and when the user clicks the menu item button, instead of going to the Guide listing it should trigger the tour.

5a. Importing the `shepherd.js` library

In our wagtail_hooks.py file we will leverage the insert_global_admin_js hook to add two files, the first of which is a CDN version of the npm package.
Using a hosted CDN version of the NPM package via https://www.jsdelivr.com/package/npm/shepherd.js saves time but it may not be suitable for your project.
In the code snippet below we will also use Wagtail's static system to add a js file, however, the code for that file is in step 5c.
Cross-check (before you continue) Remember to restart your dev server, once done you should be able to open up the browser console and type Shepherd to see a value. This means the CDN has worked, you can also look at the network tab to check it gets loaded.

#guide/wagtail_hooks.py

from django.templatetags.static import static # added
from django.utils.html import format_html # added

from wagtail.contrib.modeladmin.options import ModelAdmin, modeladmin_register
from wagtail.core import hooks # added

# .. other imports & GuideAdmin

@hooks.register("insert_global_admin_js")
def global_admin_js():
    """
    Sourced from https://www.jsdelivr.com/package/npm/shepherd.js
    """
    return format_html(
        '<script src="{}"></script><script src="{}"></script>',
        "https://cdn.jsdelivr.net/npm/shepherd.js@8/dist/js/shepherd.min.js",
        static("js/shepherd.js"),
    )

5b. Adding the custom static CSS file

The CSS code below contains all the base styles supplied with the Shepherd.js library with some tweaks to look a bit more like 'Wagtail', you can just use the CDN version via https://cdn.jsdelivr.net/npm/shepherd.js@8/dist/css/shepherd.css to save time.
It is important to note the styling .menu-item .help-available::after - this is to add a small visual indicator of a * (star) when a known help item is available.
Remember to add 'django.contrib.staticfiles' to your INSTALLED_APPS so that static files can be used.
Cross-check (before you continue) Remember to restart your dev server when changing static files, once done you should be able to see that this CSS file was loaded in the network tab.

#guide/wagtail_hooks.py

# .. other imports & GuideAdmin + insert_global_admin_js

@hooks.register("insert_global_admin_css")
def global_admin_css():
    """
    Pulled from https://github.com/shipshapecode/shepherd/releases (assets)
    .button styles removed (so we can use Wagtail styles instead)
    """
    return format_html('<link rel="stylesheet" href="{}">', static("css/shepherd.css"))

/* guide/static/css/shepherd.css */
.shepherd-footer {
  border-bottom-left-radius: 5px;
  border-bottom-right-radius: 5px;
  display: flex;
  justify-content: flex-end;
  padding: 0 0.75rem 0.75rem;
}

.shepherd-footer .shepherd-button:last-child {
  margin-right: 0;
}

.shepherd-cancel-icon {
  background: transparent;
  border-radius: 0.25rem;
  border: none;
  color: inherit;
  font-size: 2em;
  cursor: pointer;
  font-weight: 400;
  margin: 0;
  padding: 0;
  transition: background-color 0.5s ease;
  width: 2.2rem;
  height: 2.2rem;
}

.shepherd-cancel-icon:hover {
  background-color: var(--color-primary-darker);
}

.shepherd-title {
  display: flex;
  font-size: 1.5rem;
  font-weight: 400;
  flex: 1 0 auto;
  margin: 0;
  padding: 0;
}

.shepherd-header {
  align-items: center;
  border-top-left-radius: 5px;
  border-top-right-radius: 5px;
  display: flex;
  justify-content: flex-end;
  line-height: 2em;
  padding: 0.75rem 0.75rem 0;
  margin-bottom: 0.25rem;
}

.shepherd-has-title .shepherd-content .shepherd-header {
  padding: 1em;
}

.shepherd-text {
  color: rgba(0, 0, 0, 0.75);
  font-size: 1rem;
  line-height: 1.3em;
  min-height: 4em;
  padding: 0.75em 1em;
}

.shepherd-text p {
  margin-top: 0;
}

.shepherd-text p:last-child {
  margin-bottom: 0;
}

.shepherd-content {
  border-radius: 5px;
  outline: none;
  padding: 0;
}

.shepherd-element {
  background: #fff;
  border-radius: 5px;
  box-shadow: 0 1px 4px rgba(0, 0, 0, 0.2);
  max-width: 50em;
  opacity: 0;
  outline: none;
  transition: opacity 0.3s, visibility 0.3s;
  visibility: hidden;
  width: 100%;
  z-index: 9999;
}

.shepherd-enabled.shepherd-element {
  opacity: 1;
  visibility: visible;
}

.shepherd-element[data-popper-reference-hidden]:not(.shepherd-centered) {
  opacity: 0;
  pointer-events: none;
  visibility: hidden;
}

.shepherd-element,
.shepherd-element *,
.shepherd-element :after,
.shepherd-element :before {
  box-sizing: border-box;
}

.shepherd-arrow,
.shepherd-arrow:before {
  position: absolute;
  width: 16px;
  height: 16px;
  z-index: -1;
}

.shepherd-arrow:before {
  content: "";
  transform: rotate(45deg);
  background: #fff;
}

.shepherd-element[data-popper-placement^="top"] > .shepherd-arrow {
  bottom: -8px;
}

.shepherd-element[data-popper-placement^="bottom"] > .shepherd-arrow {
  top: -8px;
}

.shepherd-element[data-popper-placement^="left"] > .shepherd-arrow {
  right: -8px;
}

.shepherd-element[data-popper-placement^="right"] > .shepherd-arrow {
  left: -8px;
}

.shepherd-element.shepherd-centered > .shepherd-arrow {
  opacity: 0;
}

.shepherd-element.shepherd-has-title[data-popper-placement^="bottom"]
  > .shepherd-arrow:before {
  background-color: #e6e6e6;
}

.shepherd-target-click-disabled.shepherd-enabled.shepherd-target,
.shepherd-target-click-disabled.shepherd-enabled.shepherd-target * {
  pointer-events: none;
}

.shepherd-target {
  outline: 4px dotted var(--color-input-focus);
  outline-offset: -2px;
}

.shepherd-modal-overlay-container {
  height: 0;
  left: 0;
  opacity: 0;
  overflow: hidden;
  pointer-events: none;
  position: fixed;
  top: 0;
  transition: all 0.3s ease-out, height 0ms 0.3s, opacity 0.3s 0ms;
  width: 100vw;
  z-index: 9997;
}

.shepherd-modal-overlay-container.shepherd-modal-is-visible {
  height: 100vh;
  opacity: 0.75;
  transition: all 0.3s ease-out, height 0s 0s, opacity 0.3s 0s;
}

.shepherd-modal-overlay-container.shepherd-modal-is-visible path {
  pointer-events: all;
}

.menu-item .help-available::after {
  content: "*";
}

5c. Adding the custom static JS file

The full JS is below, the goal of this JS is to set up a Shepherd.js tour for every element found with the data-help attribute.
This data attribute will be parsed as JSON and if steps are found, the tour will be set up and the element will have a click listener attached to it to trigger the tour.
We have also set up some logic to ensure that the right buttons show for each possible state of a step (for example, the first step should only have a 'next' button).
The Shepherd.js documentation contains information about each of the options passed in and these can be customised based on requirements.
Cross-check (before you continue) Remember to restart your dev server when adding static files, once done you should be able to see that this JS file was loaded in the network tab.

// guide/static/js/shepherd.js
(() => {
  /* 1. set up buttons for each possible state (first, last, only) of a step */

  const nextButton = {
    action() {
      return this.next();
    },
    classes: "button",
    text: "Next",
  };

  const backButton = {
    action() {
      return this.back();
    },
    classes: "button button-secondary",
    secondary: true,
    text: "Back",
  };

  const doneButton = {
    action() {
      return this.next();
    },
    classes: "button",
    text: "Done",
  };

  /* 2. create a function that will maybe return an object with the buttons */

  const getButtons = ({ index, length }) => {
    if (length <= 1) return { buttons: [doneButton] }; // only a single step, no back needed
    if (index === 0) return { buttons: [nextButton] }; // first
    if (index === length - 1) return { buttons: [backButton, doneButton] }; // last
    return {};
  };

  /* 3. prepare the default step options */

  const defaultButtons = [backButton, nextButton];

  const defaultStepOptions = {
    arrow: false,
    buttons: defaultButtons,
    cancelIcon: { enabled: true },
    canClickTarget: false,
    scrollTo: { behavior: "smooth", block: "center" },
  };

  /* 4. once the DOM is loaded, find all the elements with the data-help attribute
     - for each of these elements attempt to parse the JSON into steps and title
     - if we find steps then initiate a `Shepherd` tour with those steps
     - finally, attach a click listener to the link so that the link will trigger the tour
   */

  window.addEventListener("DOMContentLoaded", () => {
    const links = document.querySelectorAll(".help-available[data-help]");

    // if no links found with data-help - return
    if (!links || links.length === 0) return;

    links.forEach((link) => {
      const data = link.dataset.help;

      // if data on data-help attribute is empty or missing, do not attempt to parse
      if (!data) return;

      const { steps = [], title } = JSON.parse(data);

      const tour = new Shepherd.Tour({
        defaultStepOptions,
        steps: steps.map(({ element, ...step }, index) => ({
          ...step,
          ...(element ? { attachTo: { element } } : {}),
          ...getButtons({ index, length: steps.length }),
        })),
        tourName: title,
        useModalOverlay: true,
      });

      link &&
        link.addEventListener("click", (event) => {
          event.preventDefault();
          tour.start();
        });
    });
  });
})();

Final Implementation

There should now be a fully functional Tour trigger that is available on the Admin home (dashboard) page, the 'Guide' menu item should have a '*' to indicate help is available.
When clicking this, it should trigger the tour based on the data added in step 3 above.
You can see all the final code on github https://github.com/lb-/bakerydemo/tree/tutorial/guide-app/guide

Updated: 20/08/2021 - added reminders about INSTALLED_APPS.

Future Enhancement Ideas

Having the same Menu Item trigger the guide AND show the guide listing is not ideal, as this could be confusing for users, plus it might be confusing to admins when they actually want to edit and cannot easily get to the guide listing (if there are lots of guides added).
Make a dashboard panel available to new users if there is a matching guide available for that page, this has been implemented as a bonus step 6 below.
Make the inspect view for Guide items show the full steps in a nice UI, as this will be a helpful resource, even without the interactive tour aspect.
Have a way to track what users click on what guides, especially helpful for new users, maybe even provide feedback.

6. Add a Dashboard panel with a Guide trigger Bonus

This is a rough implementation but it leverages the same logic in the custom MenuItem to potentially render a homepage panel.
This code is based on the construct_homepage_panels Wagtail docs.
Using Guide.get_data_for_request(self.request) we can pull in a potential data object and if found, pass it to the generated HTML.
Note: We need to override the __init__ method to ensure this Panel class can be initialised with the request.

# wagtail_hooks.py

# imports and other hooks...

class GuidePanel:
    order = 500

    def __init__(self, request):
        self.request = request

    def render(self):
        data = Guide.get_data_for_request(self.request)

        if data:
            return format_html(
                """
            <section class="panel summary nice-padding">
                <h2>Guide</h2>
                <div>
                    <button class="button button-secondary help-available" data-help="{}">Show {} Guide</button>
                </div>
            </section>
            """,
                data["value_json"],
                data["title"],
            )

        return ""


@hooks.register("construct_homepage_panels")
def add_guide_panel(request, panels):
    panels.append(GuidePanel(request))

How to create a Kanban (Trello style) view of your ModelAdmin data in Wagtail

LB (Ben Johnston) — Fri, 06 Aug 2021 11:49:32 +0000

Goal: Create a ModelAdmin mixin that will make it easy to show an index view as a Kanban board.

Why: Visual presentation is very helpful for planning and also a high-level understanding of information. Kanban boards provide a recognisable way to show sets of items in columns that represent their 'status' or grouping.

How: We want this to be as simple as possible, leveraging existing ModelAdmin conventions where possible and keeping as much of the logic being on the server. Drag & drop would be great but happy to sacrifice real-time / async Javascript behaviour to gain simplicity.

Inspiration: Kanban, notion.so, Trello, Github & Gitlab Kanban interface.

Getting Started

Versions

Wagtail 2.14
Python 3.6
Django 3.2
jkanban 1.3 (Javascript/npm library)

Key Parts to Understand

Terminology
ModelAdmin (Wagtail's not Django's)
Class Mixin

Tutorial

1. Prepare a ModelAdmin model

For this tutorial we will be using ArsTechnica's Rocket Report as inspiration. As of writing the latest report was Rocket Report: Super Heavy lights up.

This regular post contains a title, byline, preamble, a reports section which breaks up the news snippets into class of launch (small, medium and large). At the end of the report there, is a small timeline of upcoming launches. The part we want to focus on for this tutorial is the reports section, and Wagtail's snippets are a perfect way to store this kind of related content in a centralised way.

Create app

We assume you already have a Wagtail application up and running, so our first step will be to find a place to store all our custom logic and models. We will start a new app called rocket_report.

Run django-admin startapp rocket_report
Update your settings.py

INSTALLED_APPS = [
  # ...
  'rocket_report',
  # ... wagtail & django items
  # ensure that snippets and modeladmin apps are added
  'wagtail.snippets',
  'wagtail.contrib.modeladmin',
]

There will now be an app folder rocket_report with models, views, etc.

Create page Model

Our next step will be to define our RocketReportPage page model.

Add a page model to your models.py file, code example below.
Run ./manage.py makemigrations & ./manage.py migrate
Restart the dev server to validate that we can now add a Rocket Report Page in Wagtail's admin
Add one page for use throughout the rest of the tutorial

from django.db import models

from modelcluster.fields import ParentalKey

from wagtail.core.models import Page, Orderable
from wagtail.core.fields import RichTextField
from wagtail.admin.edit_handlers import FieldPanel, InlinePanel
from wagtail.images.edit_handlers import ImageChooserPanel


class RocketReportPage(Page):

    # Database fields
    byline = models.CharField(blank=True, max_length=120)
    preamble = RichTextField(blank=True)
    main_image = models.ForeignKey(
        "wagtailimages.Image",
        null=True,
        blank=True,
        on_delete=models.SET_NULL,
        related_name="+",
    )

    # Editor panels configuration
    content_panels = Page.content_panels + [
        FieldPanel("byline"),
        FieldPanel("preamble", classname="full"),
        ImageChooserPanel("main_image"),
        # TBC - reports
        InlinePanel("related_launches", label="Timeline"),
    ]


class Launch(Orderable):
    page = ParentalKey(
        RocketReportPage, on_delete=models.CASCADE, related_name="related_launches"
    )
    date = models.DateField("Launch date")
    details = models.CharField(max_length=255)

    panels = [
        FieldPanel("date"),
        FieldPanel("details"),
    ]

Create snippet Model

Our rocket report items will be Wagtail Snippets, this gives a simple way to edit, manage and select these items for our pages.

Add the snippet model to your same models.py file, code example below.
Run ./manage.py makemigrations & ./manage.py migrate.
Restart the dev server to validate that we can now add the snippet in Wagtail's admin.
Add some snippet entries for use throughout the rest of the tutorial.
Note - a reminder to ensure INSTALLED_APPS contains 'wagtail.snippets'

from django.db import models
# ... include existing imports from model.py
from wagtail.snippets.models import register_snippet
from wagtail.snippets.edit_handlers import SnippetChooserPanel
from wagtail.admin.edit_handlers import FieldPanel


class RocketReportPage(Page):
    # ...
    content_panels = Page.content_panels + [
        # ... other field panels
        ImageChooserPanel("main_image"),
        # ... other field panels
    ]


@register_snippet
class RocketReport(models.Model):

    STATUS_CHOICES = [
        ("SUBMITTED", "Submitted"),
        ("REVIEWED", "Reviewed"),
        ("PROPOSED", "Proposed"),
        ("HOLD", "Hold"),
        ("CURRENT", "Current"),
    ]

    CATEGORY_CHOICES = [
        ("BLANK", "Uncategorised"),
        ("SMALL", "Small"),
        ("MEDIUM", "Medium"),
        ("LARGE", "Large"),
    ]

    submitted_url = models.URLField(null=True, blank=True)
    submitted_by = models.CharField(max_length=255, blank=True)
    status = models.CharField(max_length=255, blank=True, choices=STATUS_CHOICES)
    title = models.CharField(max_length=255)
    content = RichTextField(blank=True)
    category = models.CharField(
        max_length=255, choices=CATEGORY_CHOICES, default="BLANK"
    )

    panels = [
        FieldPanel("title"),
        FieldPanel("status"),
        FieldPanel("category"),
        FieldPanel("content"),
        FieldPanel("submitted_url"),
        FieldPanel("submitted_by"),
    ]

    def __str__(self):
        return self.title


class RocketReportPageReportPlacement(Orderable, models.Model):
    page = ParentalKey(
        RocketReportPage, on_delete=models.CASCADE, related_name="rocket_reports"
    )
    rocket_report = models.ForeignKey(
        RocketReport, on_delete=models.CASCADE, related_name="+"
    )

    panels = [
        SnippetChooserPanel("rocket_report"),
    ]

    def __str__(self):
        return self.page.title + " -> " + self.rocket_report.title

Register with ModelAdmin

Now we can register the report model using ModelAdmin. Note that this is Wagtail's ModelAdmin not Django's.

Add wagtail.contrib.modeladmin to your INSTALLED_APPS in your settings.py
Add a new ModelAdmin class in admin.py, code example below.
Register this class in a new file wagtail_hooks.py, code example below.
Validate that we now have an admin sidebar item for 'Rocket Reports' which will show the default ModelAdmin item list.

# admin.py
from wagtail.contrib.modeladmin.options import ModelAdmin

from .models import RocketReport


class RocketReportAdmin(ModelAdmin):
    model = RocketReport
    menu_icon = "fa-rocket"
    list_display = ("title", "status", "category", "submitted_by")
    list_filter = ("status", "category")
    search_fields = ("title", "status", "category", "submitted_by")

# wagtail_hooks.py
from wagtail.contrib.modeladmin.options import modeladmin_register

from .admin import RocketReportAdmin

modeladmin_register(RocketReportAdmin)

2. Create a template, view & mixin

We are going to now set up a custom KanbanMixin that will house the customisations to our ModelAdmin. We could put all of these customisations directly on our RocketReportAdmin but we want to set up something reusable. It would be good to have a basic understanding of how to customise the index view (listing) before reading on.

Create Kanban index template

We will be using a Javascript library to do the client-side rendering and handling of interaction for our basic Kanban board. There are a lot of Kanban JS libraries on Github and a few Kanban packages on NPM.

The package we will use is Jkanban, it has a simple API and does not rely on third-party dependencies. For simplicity, we will use the jsdelivr service to provide our script and CSS, find the package and use the dist directory to get your script and style tags.

Create a template file /templates/modeladmin/kanban_index.html
To inherit the existing modeladmin index listing layout (header, search bar, title etc) add {% extends "modeladmin/index.html" %} at the top
The content blocks we will use, provided by the above template are extra_css, extra_js and content_main.
Remember to add {{ block.super }} to the js & css blocks so that existing scripts and styles will be used.
content_main block - add a div that will contain the Kanban with class kanban-wrapper listing and an inner div with an id kanban-mount which is used by JKanban to add the rendered kanban board
extra_css block - Add the link tag from jsdelivr and some basic styles within a <style> tag, in the code below we are starting with some margins and handling of longer boards
extra_js block - our goal is to simply load up some dummy data based on the options docs for jKanban

document.addEventListener("DOMContentLoaded", function () {
  var options = {
    boards: [
      {
        id: "column-0",
        title: "Column A",
        item: [
          { id: "item-1", title: "Item 1" },
          { id: "item-2", title: "Item 2" },
          { id: "item-1", title: "Item 3" },
        ],
      },
      {
        id: "column-1",
        title: "Column B",
        item: [
          { id: "item-4", title: "Item 4" },
          { id: "item-5", title: "Item 4" },
          { id: "item-5", title: "Item 6" },
        ],
      },
    ],
  };

  // build the kanban board with supplied options
  var kanban = new jKanban(
    Object.assign({}, options, { element: "#kanban-mount" })
  );
});

Full template code

{% extends "modeladmin/index.html" %}
{% comment %} templates/modeladmin/kanban_index.html {% endcomment %}

{% block extra_css %}
    {{ block.super }}
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/jkanban@1/dist/jkanban.min.css">
    <style>
      .kanban-wrapper {
        width: 100%;
        overflow-x: auto; /* add horizontal scrolling for wide boards */
        margin-top: 1rem;
        margin-bottom: 1rem;
      }

      .kanban-item {
        min-height: 4rem;
      }
    </style>
{% endblock %}

{% block extra_js %}
  {{ block.super }}
  <script src="https://cdn.jsdelivr.net/npm/jkanban@1/dist/jkanban.js"></script>
  <script>
    document.addEventListener('DOMContentLoaded', function() {
      var options = {
        boards: [
          {
            id: 'column-0',
            title: 'Column A',
            item: [{ id: 'item-1', title: 'Item 1'}, { id: 'item-2', title: 'Item 2'}, { id: 'item-1', title: 'Item 3'}]}
          ,
          {
            id: 'column-1',
            title: 'Column B',
            item: [{ id: 'item-4', title: 'Item 4'}, { id: 'item-5', title: 'Item 4'}, { id: 'item-5', title: 'Item 6'}]
          }
        ]
      };

      // build the kanban board with supplied options
      // see: https://github.com/riktar/jkanban#var-kanban--new-jkanbanoptions
      var kanban = new jKanban(Object.assign({}, options, {element: '#kanban-mount'}));
    });
  </script>
{% endblock %}

{% block content_main %}
  <div class="kanban-wrapper listing">
    <div id="kanban-mount"></div>
  </div>
{% endblock %}

Create Mixin with template override

A template is only good if we can get our ModelAdmin to use it when rendering the index listing view instead of the default. We can leverage a mixin approach to override the ModelAdmin methods while still honouring the existing config on a per app or model basis.

We will store our mixin in the admin.py file.
ModelAdmin uses a method get_index_template to get the index listing template, simply override this to call the defined index_template_name or get_templates("kanban_index").
This will ensure that the template made above will be found at templates/modeladmin/kanban_index.html
Be sure to add the mixin to your RocketReportAdmin class, before the ModelAdmin usage.

# rocket_report/admin.py

class KanbanMixin:
    def get_index_template(self):
        # leverage the get_template to allow individual override on a per model basis
        return self.index_template_name or self.get_templates("kanban_index")


class RocketReportAdmin(KanbanMixin, ModelAdmin):
    model = RocketReport
    # ...

Create View to supply mock data to the kanban board

Our goal is to keep as much logic on the server, so we need a way to provide the board data from our Django view to our client. Doing this comes with some issues of encoding/decoding and ensuring that server generated content cannot inject Javascript.

Thankfully, Django helps us out with its builtin tag json_script which provides a way for sever generated content to be provided to JS in a view in a safe way.

Add a new view to the app's views.py called KanbanView
This view will inherit the modeladmin wagtail.contrib.modeladmin.views.IndexView
Override get_context_data, calling super and then adding kanban_options with similar dummy data that we used in the template
Use this KanbanView within the KanbanMixin
Update the kanban_index.html to inject the JSON data via json-script

# views.py
from wagtail.contrib.modeladmin.views import IndexView


class KanbanView(IndexView):
    def get_kanban_data(self, context):
        return [
            {
                "id": "column-id-%s" % index,
                "item": [
                    {"id": "item-id-%s" % obj["pk"], "title": obj["title"],}
                    for index, obj in enumerate(
                        [
                            {"pk": index + 1, "title": "%s Item 1" % column},
                            {"pk": index + 2, "title": "%s Item 2" % column},
                            {"pk": index + 3, "title": "%s Item 3" % column},
                        ]
                    )
                ],
                "title": column,
            }
            for index, column in enumerate(["column a", "column b", "column c"])
        ]

    def get_context_data(self, **kwargs):
        context = super().get_context_data(**kwargs)

        # replace object_list in context as we do not want it to be paginated
        context["object_list"] = self.queryset

        # see: https://github.com/riktar/jkanban#var-kanban--new-jkanbanoptions
        context["kanban_options"] = {
            "addItemButton": False,
            "boards": self.get_kanban_data(context),
            "dragBoards": False,
            "dragItems": False,
        }

        return context

# rocket_report/admin.py
from wagtail.contrib.modeladmin.options import ModelAdmin

from .views import KanbanView
from .models import RocketReport


class KanbanMixin:

    index_view_class = KanbanView

    def get_index_template(self):
        #...


class RocketReportAdmin(KanbanMixin, ModelAdmin):
    model = RocketReport
    # ...

{% comment %} templates/modeladmin/kanban_index.html (just the JS block shown) {% endcomment %}
{% block extra_js %}
  {{ block.super }}
  <script src="https://cdn.jsdelivr.net/npm/jkanban@1/dist/jkanban.js"></script>
  {{ kanban_options|json_script:"kanban-options" }}
  <script>
    document.addEventListener('DOMContentLoaded', function() {
      // load the options from server
      var options = JSON.parse(document.getElementById('kanban-options').textContent);
      console.log('loaded', { options })

      // build the kanban board with supplied options
      // see: https://github.com/riktar/jkanban#var-kanban--new-jkanbanoptions
      var kanban = new jKanban(Object.assign({}, options, {element: '#kanban-mount'}));
    });
  </script>
{% endblock %}

3. Render items columns from actual data

Our goal here is to finish this basic implementation by generating columns and items from the correct Model. To achieve this we will revise the KanbanMixin to have some methods for smaller templates (used for the title/content) and methods to determine what field will be used for the columns. After that, we can revise the View to prepare all the data.

Revise the KanbanMixin and add small templates

Add a method get_kanban_item_template to look for a template with the name kanban_item but also allow the Mixin usage to declare an attribute kanban_item_template_name. This way we can have simple defaults but allow each KanbanMixin to declare custom templates for the items on a per model basis.
Add a method get_kanban_column_title_template that is similar to the above but for the column title.
Add a method get_kanban_column_field which will return the first field name from the list_filter attribute on the Mixin usage, this means we can leverage the existing ModelAdmin attributes approach.
Finally, add a method get_kanban_column_name_default for a default column name, this will be used when there is no value for the Kanban column field (e.g. a drop-down where a None/blank value is selected).

# rocket_report/admin.py

class KanbanMixin:
    index_view_class = KanbanView

    def get_index_template(self):
        # leverage the get_template to allow individual override on a per model basis
        return self.index_template_name or self.get_templates("kanban_index")


    def get_kanban_item_template(self):
        # leverage the get_template to allow individual override on a per model basis
        return getattr(
            self, "kanban_item_template_name", self.get_templates("kanban_item")
        )

    def get_kanban_column_title_template(self):
        # leverage the get_template to allow individual override on a per model basis
        return getattr(
            self,
            "kanban_column_title_template_name",
            self.get_templates("kanban_column_title"),
        )

    def get_kanban_column_field(self):
        # return a field to use to determine which column the item will be shown in
        # pull in the first value from list_filter if no specific column set
        list_filter = getattr(self, "list_filter", [])
        field = list_filter[0] if list_filter else None
        return field

    def get_kanban_column_name_default(self):
        # used for the column title name for None or no column scenarios
        return getattr(self, "kanban_column_name_default", "Other")
# ...

Revise the KanbanMixin and add small templates

There is a lot changed in this final step, the main methods added to the KanbanView are to generate all the various parts (columns/items) and use the template in each of those parts set up in the KanbanMixin.

Add a method render_kanban_item_html which will pull in the action buttons (part of ModelAdmin), the template and then pass all the data to the template from the get_kanban_item_template method. This will return a string (HTML) which will, in turn, be passed to the JSON data for the Kanban board.
Add a method render_kanban_column_title_html which will pass the context to the configured title template.
Add a method get_kanban_columns that uses a query which will gather ALL the Model instances and prepare the data which has groupings of those Models by their column, along with the columns (with their names) also.
Replace the method get_kanban_data with a series of List parsing that goes through the column data and prepares the items to be placed within each column in a format that, when converted to JSON, is suitable for jKanban.

from django.contrib.admin.templatetags.admin_list import result_headers

from django.template.loader import render_to_string
from django.db.models import CharField, Count, F, Value

from wagtail.contrib.modeladmin.templatetags.modeladmin_tags import result_list
from wagtail.contrib.modeladmin.views import IndexView


class KanbanView(IndexView):

    def render_kanban_item_html(self, context, obj, **kwargs):
        """
        Allow for template based rendering of the content that goes inside each item
        Prepare action buttons that will be the same as the classic modeladmin index
        """

        kwargs["obj"] = obj
        kwargs["action_buttons"] = self.get_buttons_for_obj(obj)

        context.update(**kwargs)

        template = self.model_admin.get_kanban_item_template()

        return render_to_string(template, context, request=self.request,)

    def render_kanban_column_title_html(self, context, **kwargs):
        """
        Allow for template based rendering of the content that goes at the top of a column
        """

        context.update(**kwargs)

        template = self.model_admin.get_kanban_column_title_template()

        return render_to_string(template, context, request=self.request,)

    def get_kanban_columns(self):
        """
        Gather all column related data
        columns: name & count queryset
        default: label of a column that either has None value or does not exist on the field
        field: field name that is used to get the value from the instance
        key: internal use key to refer to the annotated column name label value
        queryset original queryset annotated with the column name label
        """
        object_list = self.queryset

        column_field = self.model_admin.get_kanban_column_field()
        column_name_default = self.model_admin.get_kanban_column_name_default()

        column_key = "__column_name"

        queryset = object_list.annotate(
            __column_name=F(column_field)
            if column_field
            else Value(column_name_default, output_field=CharField())
        )

        order = F(column_key).asc(nulls_first=True) if column_field else column_key

        columns = (
            queryset.values(column_key).order_by(order).annotate(count=Count("pk"))
        )

        return {
            "columns": columns,
            "default": column_name_default,
            "field": column_field,
            "key": column_key,
            "queryset": queryset,
        }

    def get_kanban_data(self, context):
        """
        Prepares the data that is used by the Kanban js library
        An array of columns, each with an id, title (html) and item
        Item value in each column contains an array of items which has a column, id & title (html)
        """
        columns = self.get_kanban_columns()

        # use existing model_admin utility to build headers/values
        result_data = result_list(context)

        # set up items (for ALL columns)
        items = [
            {
                "column": getattr(obj, columns["key"]),
                "id": "item-id-%s" % obj.pk,
                "title": self.render_kanban_item_html(
                    context,
                    obj,
                    fields=[
                        {"label": label, "value": result_data["results"][index][idx]}
                        for idx, label in enumerate(result_data["result_headers"])
                    ],
                ),
            }
            for index, obj in enumerate(columns["queryset"])
        ]

        # set up columns (aka boards) with sets of filtered items inside
        return [
            {
                "id": "column-id-%s" % index,
                "item": [
                    item for item in items if item["column"] == column[columns["key"]]
                ],
                "title": self.render_kanban_column_title_html(
                    context,
                    count=column["count"],
                    name=column.get(columns["key"], columns["default"])
                    or columns["default"],
                ),
            }
            for index, column in enumerate(columns["columns"])
        ]

    def get_context_data(self, **kwargs):
        # ... (same as before)

Final Solution

Code can be found Github / lb-

Future Improvements & Feedback

It took a while to get this published, so hopefully it all came together well but I would love any feedback and hope this is helpful to someone.
Better handling of pre-setting 'values' for each item's field/value, currently renders inside <td> tags due to existing ModelAdmin assumptions.
Handling drag & drop (even real-time) with column number updates and toast style messages, you can view a rough version of this in the repo above (see commit ORIGINAL ROUGH IMPLEMENTATION).

Notes

Updated 20/08/2021 - added notes about updating INSTALLED_APPS

Image Uploads in Wagtail Forms

LB (Ben Johnston) — Thu, 24 Sep 2020 22:10:08 +0000

For developers using the Wagtail CMS who want to add image upload fields.

Heads up - This is an update of my earlier post Image Uploads in Wagtail Forms which was written for Wagtail v1.12, this new post is written for v2.10/v2.11.

The Problem --- Your team are loving the custom form builder in Wagtail CMS and want to let people upload an image along with the form.

The Solution --- Define a new form field type that is selectable when editing fields in the CMS Admin, this field type will be called 'Upload Image'. This field should show up in the view as a normal upload field with restrictions on file type and size, just like the Wagtail Images system.

Goal: When you add an 'Upload Image' field, it will show up on the form view for you.

Wagtail, Images and Forms

Skip ahead if you know the basics here.

Wagtail is a Content Management System (CMS) that is built on top of the Django Web Framework. What I love about Wagtail is that it embraces the Django ecosystem and way of doing things. It also has a really nice admin interface that makes it easy for users to interact with the content.

Wagtail has a built in interface and framework for uploading, storing and serving images. This is aptly named Wagtail Images, you can review the docs about Using Images in Templates or Advanced Image Usage for more information.

Wagtail comes with a great Form Builder module, it lets users build their own forms in the admin interface. These forms can have a series of fields such as Text, Multi-line Text, Email, URL, Checkbox, and others that build up a form page that can be viewed on the front end of the website. Users can customise the default value, whether the field is required and also some help text that relates to the field.

Before We Start

Before we start changing (breaking) things, it is important that you have the following items completed.

Wagtail v2.10.x or v2.11.x up and running as per the main documentation.
Wagtailforms module is installed, running and you have forms working. Remember to add 'wagtail.contrib.forms' to your INSTALLED_APPS.

Adding Image Upload Fields to Forms in Wagtail

Planning our Changes

We want to enable the following user interaction:

The admin interface should provide the ability to edit an existing form and create a new form as normal.
When editing a form page, there should be a new dropdown option on the 'Field Type' field called 'Upload Image'.
The form page view should have one file upload field for every 'Upload Image' field that was defined in the admin.
The form page view should accept images with the same restrictions as Wagtail Images (< 10mb, only PNG/JPG/GIF*).
The form page view should require the image if the field is defined as 'required' in admin.
When an image is valid, it should save this image into the Wagtail Images area.
A link to the image should be saved to the form submission (aka form response), this will ensure it appears on emails or reports.

* Default GIF support is quite basic in Wagtail, if you want to support animated GIFs you should read these docs regarding Animated GIFs.

1. Extend the `AbstractFormField` Class

In your models file that contains your FormPage class definition, you should also have a definition for a FormField class. In the original definition, the AbstractFormField class uses a fixed tuple of FORM_FIELD_CHOICES. We need to override the field_type with an appended set of choices.

# models.py

from wagtail.contrib.forms.models import AbstractForm, AbstractFormField, FORM_FIELD_CHOICES

class FormField(AbstractFormField):

    field_type = models.CharField(
        verbose_name='field type',
        max_length=16,
        choices=list(FORM_FIELD_CHOICES) + [('image', 'Upload Image')]
    )

    page = ParentalKey('FormPage', related_name='form_fields', on_delete=models.CASCADE)

In the above code you can see that we imported the original FORM_FIELD_CHOICES from wagtail.contrib.forms.models. We then converted it to a list, added our new field type and then this is used in the choices argument of the field_type field.

When you do this, you will need to make a migration, and run that migration. Test it out, the form in admin will now let you select this type, but it will not do much else yet.

2. Extend the `FormBuilder` Class

In your models file you will now need to create an extended form builder class. In the original definition the FormBuilder class builds a form based on the field_type list that is stored in each FormPage instance. We can follow the example in the docs about Adding a custom field type.

We will need to create a method that follows the convention based on the field name ('image' in our case) to a method name create_image_field which is then called and should return an instance of a Django form widget. Rather than building our own custom Image field that works with Wagtail, we can use their own WagtailImageField.

# models.py

from wagtail.contrib.forms.forms import FormBuilder

from wagtail.images.fields import WagtailImageField


class CustomFormBuilder(FormBuilder):

    def create_image_field(self, field, options):
        return WagtailImageField(**options)

In the above code, we have imported FormBuilder from wagtail.contrib.forms.forms and WagtailImageField from wagtail.images.fields, then created our own custom FormBuilder with a new class. We have added a method create_image_field that returns a created WagtailImageField, passing in any options provided.

3. Set the FormPage class to use `CustomFormBuilder`

This step is pretty straight forward, we want to override the form_builder definition in our FormPage model. This is a very nifty way that Wagtail enables you to override the form_builder you use.

# models.py

from wagtail.contrib.forms.models import AbstractForm

class FormPage(AbstractForm):

    form_builder = CustomFormBuilder

    #... rest of the FormPage definition

4. Update form page template to accept File Data

The form page view should have a <form /> tag in it, the implementation suggested by Wagtail does not allow files data to be submitted in the form.

<!-- templates/form_page.html -->

{% extends "base.html" %}

{% load wagtailcore_tags %}

{% block content %}

    {{ self.intro }}

    <form action="{% pageurl self %}" method="POST" enctype="multipart/form-data">
        {% csrf_token %}
        {{ form.as_p }}
        <input type="submit" />
    </form>

{% endblock %}

The only difference to the basic form is that we have added enctype="multipart/form-data" to our form attributes. If you do not do this you will never get any files sent through the request and no errors to advise you why.

For more information about why we need to do this, you can view the Django Docs File Uploads page and have a deep dive into the enctype form attribute on MDN.

5. Add ability to select a collection for uploaded images

When uploading images via the admin interface, there is an option to add each image to a collection, this defaults to 'Root' and these act like folders for your images.

Rather than just dumping all uploaded images from form submissions into 'Root' we want to give the user the option to determine which Collection the images for each page form will be added to.

# models.py

from wagtail.admin.edit_handlers import FieldPanel
from wagtail.core.models import Collection


class FormPage(AbstractForm):

    form_builder = CustomFormBuilder

    # other fields...

    uploaded_image_collection = models.ForeignKey(
        'wagtailcore.Collection',
        null=True,
        blank=True,
        on_delete=models.SET_NULL,
    )

    # content_panels...

    settings_panels = AbstractForm.settings_panels + [
        FieldPanel('uploaded_image_collection')
    ]


    def get_uploaded_image_collection(self):
        """
        Returns a Wagtail Collection, using this form's saved value if present,
        otherwise returns the 'Root' Collection.
        """
        collection = self.uploaded_image_collection
        return collection or Collection.get_first_root_node()

In the code above we import the Collections model, added a new field to our FormPage model called uploaded_image_collection which is a ForeignKey relation to the 'wagtailCore.Collection' model.

We also added a class method to retrieve this from the Page and fall back to the root collection via the get_first_root_node method (as Wagtail Collections use Treebeard to define a tree like structure).

Once this code step is completed, you will need to make a migration, and run that migration.

6. Process the Image (file) Data after Validation

We will now override the process_form_submission on our FormPage class. The original definition of the process_form_submission method has no notion of processing anything other than the request.POST data. It will simply convert the cleaned data to JSON for storing on the form submission instance. We will iterate through each field and find any instances of WagtailImageField then get the data, create a new Wagtail Image with that file data, finally we will store a link to the image in the response.

# models.py

import json
from os.path import splitext

from django.core.serializers.json import DjangoJSONEncoder

from wagtail.images import get_image_model


class FormPage(AbstractForm):

    form_builder = CustomFormBuilder

    # fields & panels definitions...

    @staticmethod
    def get_image_title(filename):
        """
        Generates a usable title from the filename of an image upload.
        Note: The filename will be provided as a 'path/to/file.jpg'
        """

        if filename:
            result = splitext(filename)[0]
            result = result.replace('-', ' ').replace('_', ' ')
            return result.title()
        return ''

    def process_form_submission(self, form):
        """
        Processes the form submission, if an Image upload is found, pull out the
        files data, create an actual Wgtail Image and reference its ID only in the
        stored form response.
        """

        cleaned_data = form.cleaned_data

        for name, field in form.fields.items():
            if isinstance(field, WagtailImageField):
                image_file_data = cleaned_data[name]
                if image_file_data:
                    ImageModel = get_image_model()

                    kwargs = {
                        'file': cleaned_data[name],
                        'title': self.get_image_title(cleaned_data[name].name),
                        'collection': self.get_uploaded_image_collection(),
                    }

                    if form.user and not form.user.is_anonymous:
                        kwargs['uploaded_by_user'] = form.user

                    image = ImageModel(**kwargs)
                    image.save()
                    # saving the image id
                    # alternatively we can store a path to the image via image.get_rendition
                    cleaned_data.update({name: image.pk})
                else:
                    # remove the value from the data
                    del cleaned_data[name]

        submission = self.get_submission_class().objects.create(
            form_data=json.dumps(form.cleaned_data, cls=DjangoJSONEncoder), # note: Wagtail 3.0 & beyond will no longer need to wrap this in json.dumps as it uses Django's JSONField under the hood now - https://docs.wagtail.org/en/stable/releases/3.0.html#replaced-form-data-textfield-with-jsonfield-in-abstractformsubmission
            page=self,
        )

        # important: if extending AbstractEmailForm, email logic must be re-added here
        # if self.to_address:
        #    self.send_mail(form)

        return submission

Once this is applied, you should be able to submit a form response with an uploaded image.

A few items of note here:

Using get_image_model is the best practice way to get the Image Model that Wagtail is using.
cleaned_data contains the File Data (for any files), the Django form module does this for us. File Data cannot be parsed by the JSON parser, hence us having to process into a URL or Image ID for these cases.
The staticmethod get_image_title can look like whatever you want, I stripped out dashes and made the file title case. You do not have to do this but you do have to ensure there is some title when inserting a WagtailImage.
If our FormPage is actually extending AbstractEmailForm (ie. the form submits AND sends an email) we must ensure that the send_mail code is added.
You must use cleaned_data.update to save a JSON seralizable reference to your image, hence the file data will not work.

7. Viewing the image via the form submissions listing

The final step is to provide a way for this image to be easily viewed in the submission listing view, we can do this by customising how this list generates.

We have stored an id of the image but we want to use image.get_rendition, which is a very useful function detailed in the Wagtail Documentation. This function mimics the template helper but can be used in Python. By default the URL will be relative (it will not contain the http/https, or the domain), this will mean links sent to email will not work. It is up to you to work out how to best solve this if it is an issue.

# models.py

from django.utils.html import format_html
from django.urls import reverse

from wagtail.contrib.forms.views import SubmissionsListView


class CustomSubmissionsListView(SubmissionsListView):

    def get_context_data(self, **kwargs):
        context = super().get_context_data(**kwargs)

        if not self.is_export:
            # generate a list of field types, the first being the injected 'submission date'
            field_types = ['submission_date'] + [field.field_type for field in self.form_page.get_form_fields()]
            data_rows = context['data_rows']

            ImageModel = get_image_model()

            for data_row in data_rows:

                fields = data_row['fields']

                for idx, (value, field_type) in enumerate(zip(fields, field_types)):
                    if field_type == 'image' and value:
                        image = ImageModel.objects.get(pk=value)
                        rendition = image.get_rendition('fill-100x75|jpegquality-40')
                        preview_url = rendition.url
                        url = reverse('wagtailimages:edit', args=(image.id,))
                        # build up a link to the image, using the image title & id
                        fields[idx] = format_html(
                            "<a href='{}'><img alt='Uploaded image - {}' src='{}' />{} ({})</a>",
                            url,
                            image.title,
                            preview_url,
                            image.title,
                            value
                        )

        return context

class FormPage(AbstractForm):

    form_builder = CustomFormBuilder
    submissions_list_view_class = CustomSubmissionsListView # added

In the code above we have added a new CustomSubmissionsListView that extends the Wagtail SubmissionsListView which will have a custom get_context_data method. In this method we call the original get_context_data to get the generated context data.

Then we check if we are showing the submissions to the user (instead of exporting them) and map through each submission row, checking with values are images and updating the shown value with some HTML. This HTML will contain a preview of the image (using rendition) with some description based on the title and id within a link to the admin page for that image.

Finishing Up

Your Form models.py file will now look something like the following.

Full code snippet

# models.py

import json
from os.path import splitext

from django.core.serializers.json import DjangoJSONEncoder
from django.db import models
from django.utils.html import format_html
from django.urls import reverse

from modelcluster.fields import ParentalKey

from wagtail.admin.edit_handlers import (
    FieldPanel,
    FieldRowPanel,
    InlinePanel,
    MultiFieldPanel,
    PageChooserPanel,
    StreamFieldPanel,
)
from wagtail.core.models import Collection
from wagtail.contrib.forms.forms import FormBuilder
from wagtail.contrib.forms.models import AbstractForm, AbstractFormField, FORM_FIELD_CHOICES
from wagtail.contrib.forms.views import SubmissionsListView
from wagtail.images import get_image_model
from wagtail.images.fields import WagtailImageField


class CustomFormBuilder(FormBuilder):

    def create_image_field(self, field, options):
        return WagtailImageField(**options)


class CustomSubmissionsListView(SubmissionsListView):

    def get_context_data(self, **kwargs):
        context = super().get_context_data(**kwargs)

        if not self.is_export:

            # generate a list of field types, the first being the injected 'submission date'
            field_types = ['submission_date'] + [field.field_type for field in self.form_page.get_form_fields()]
            data_rows = context['data_rows']
            ImageModel = get_image_model()

            for data_row in data_rows:

                fields = data_row['fields']

                for idx, (value, field_type) in enumerate(zip(fields, field_types)):
                    if field_type == 'image' and value:
                        image = ImageModel.objects.get(pk=value)
                        rendition = image.get_rendition('fill-100x75|jpegquality-40')
                        preview_url = rendition.url
                        url = reverse('wagtailimages:edit', args=(image.id,))
                        # build up a link to the image, using the image title & id
                        fields[idx] = format_html(
                            "<a href='{}'><img alt='Uploaded image - {}' src='{}' />{} ({})</a>",
                            url,
                            image.title,
                            preview_url,
                            image.title,
                            value
                        )

        return context


class FormField(AbstractFormField):

    field_type = models.CharField(
        verbose_name='field type',
        max_length=16,
        choices=list(FORM_FIELD_CHOICES) + [('image', 'Upload Image')]
    )

    page = ParentalKey('FormPage', related_name='form_fields', on_delete=models.CASCADE)


class FormPage(AbstractForm):

    form_builder = CustomFormBuilder
    submissions_list_view_class = CustomSubmissionsListView

    # ... fields

    uploaded_image_collection = models.ForeignKey(
        'wagtailcore.Collection',
        null=True,
        blank=True,
        on_delete=models.SET_NULL,
    )

    content_panels = AbstractForm.content_panels + [
        # ... panels
    ]

    settings_panels = AbstractForm.settings_panels + [
        FieldPanel('uploaded_image_collection')
    ]

    def get_uploaded_image_collection(self):
        """
        Returns a Wagtail Collection, using this form's saved value if present,
        otherwise returns the 'Root' Collection.
        """
        collection = self.uploaded_image_collection

        return collection or Collection.get_first_root_node()

    @staticmethod
    def get_image_title(filename):
        """
        Generates a usable title from the filename of an image upload.
        Note: The filename will be provided as a 'path/to/file.jpg'
        """

        if filename:
            result = splitext(filename)[0]
            result = result.replace('-', ' ').replace('_', ' ')
            return result.title()
        return ''

    def process_form_submission(self, form):
        """
        Processes the form submission, if an Image upload is found, pull out the
        files data, create an actual Wgtail Image and reference its ID only in the
        stored form response.
        """

        cleaned_data = form.cleaned_data

        for name, field in form.fields.items():
            if isinstance(field, WagtailImageField):
                image_file_data = cleaned_data[name]
                if image_file_data:
                    ImageModel = get_image_model()

                    kwargs = {
                        'file': cleaned_data[name],
                        'title': self.get_image_title(cleaned_data[name].name),
                        'collection': self.get_uploaded_image_collection(),
                    }

                    if form.user and not form.user.is_anonymous:
                        kwargs['uploaded_by_user'] = form.user

                    image = ImageModel(**kwargs)
                    image.save()
                    # saving the image id
                    # alternatively we can store a path to the image via image.get_rendition
                    cleaned_data.update({name: image.pk})
                else:
                    # remove the value from the data
                    del cleaned_data[name]

        submission = self.get_submission_class().objects.create(
            form_data=json.dumps(form.cleaned_data, cls=DjangoJSONEncoder),
            page=self,
        )

        # important: if extending AbstractEmailForm, email logic must be re-added here
        # if self.to_address:
        #    self.send_mail(form)

        return submission

Forms can now have one or more Image Upload fields that are defined by the CMS editors. These images will be available in Admin in the Images section and can be used throughout the rest of Wagtail. You also get all the benefits that come with Wagtail Images like search indexing, usage in templates and URLS for images of various compressed sizes.

The Admin view of form responses will now show whatever you store from the clean_data.

Let me know if you run into issues or find some typos/bugs in this article. Thank you to the amazing team at Torchbox and all the developers of Wagtail for making this amazing tool. Show your support of Wagtail by starring the Wagtail repo on Github.

You can see all the original code changes in Github via the image-uploads branch.

One suggestion from the comments: It's a good idea to add a post_delete signal on the form submission model. So that when you delete an entry from the submission list, it will also delete the uploaded image.

Thanks to my friend Adam for helping me proof this.

Adding a React component in Wagtail Admin

LB (Ben Johnston) — Thu, 12 Dec 2019 21:28:39 +0000

I’m a full-stack developer and a member of the core team for Wagtail, the open-source CMS built on top of Django. I also work full time for Virgin Australia as a front end developer.

Wagtail uses React in parts of its admin, so it should be pretty straightforward to add a custom React component right?

A few months ago I was doing some investigating for a project at work and found this awesome React timeline component, React Calendar Timeline. React Calendar Tiemline is a fully interactive timeline component that lets you do anything, from simply viewing a timeline through to complete interaction, such as dragging & dropping to move items around the timeline. This timeline component is really well put together and appears to be actively maintained and improved by the team at Namespace.

I thought it would be great to be able to visualise and eventually control key Wagtail Page events such as updates and publishing dates.

The article below is 80% tutorial and 20% journey of the frustrations and fun in working with React in a slightly non-standard way. Some of this will apply to Django development as Wagtail is essentially just Django.

Step 1 - Define The Goal & Constraints

We want to incorporate a single React component into Wagtail's Admin.
We want to leverage the existing React library that comes with Wagtail Admin along with the existing sidebar, page title, search and messaging structure that Wagtail uses, so it feels like Wagtail.
We want our development environment to be easy to use so we can leverage the npm ecosystem.
We want a build output that is simple to integrate with an existing Django/Wagtail project.

Goal: Add a single page within the Wagtail Admin that looks like a normal page but uses the React Calendar Timeline component to render a timeline of published pages.

Step 2 - Set up a new Django App & Wagtail Admin Page

Important If you do not have an existing Wagtail project running locally, please follow the Wagtail Getting Started guide.

Note: We will leverage the Wagtail Bakery Demo for this tutorial.
Create a Django App named timeline - this can be done quickly via the django-admin command ./manage.py startapp timeline
Update your settings to include this app by adding to the INSTALLED_APPS list.
Reminder: When updating settings, you will need to restart Django for the changes to take effect.
Create a simple 'timeline' view and template that simply render a header and content. We will use some of the existing admin template includes, these are not all documented but looking at the Wagtail code can help us discover what's available.
Create a wagtail_hooks.py file to register the timeline view as an admin URL (via the hook register_admin_urls) and also to add a link to the admin settings menu via the hook register_admin_menu_item.
Code snippets below.

{% comment %} timeline/templates/timeline.html {% endcomment %}
{% extends "wagtailadmin/base.html" %}
{% load static %}

{% block titletag %}{{ title }}{% endblock %}
{% block bodyclass %}timeline{% endblock %}

{% block content %}
  {% include "wagtailadmin/shared/header.html" with title=title %}
  <div class="container">
    <div id="timeline">
      {{ title }}
    </div>
  </div>
{% endblock %}

# timeline/views.py

from django.shortcuts import render


def timeline_view(request):

    return render(request, "timeline.html", {
        'title': 'Timeline',
    })

# timeline/wagtail_hooks.py

from django.conf.urls import url
from django.urls import reverse

from wagtail.admin.menu import MenuItem
from wagtail.core import hooks

from .views import timeline_view


@hooks.register('register_admin_urls')
def urlconf_time():
    return [
        url(r'^timeline/$', timeline_view, name='timeline'),
    ]


@hooks.register('register_admin_menu_item')
def register_timeline_menu_item():
    return MenuItem(
        'Timeline',
        reverse('timeline'),
        classnames='icon icon-time',
        order=10000 # very last
    )

Step 3 - Add an in-line basic React Component

Here we want to simply confirm we can get something rendering with React, using the global React object provided by Wagtail Admin.

Add a small Javascript script tag that will render a simple React Component. This will use the ReactDOM.render and React.createElement functions.
Remember: As this code is not transpiled, we're unable to use the more-familiar JSX syntax, and need to consider what features the target browsers support, for example, we can't use arrow functions here as they aren't supported by IE11.
Save the changes to the template, refresh the view and you should see the text TIMELINE CONTENT HERE visible.


{% block extra_js %}
  {{ block.super }}
  <script>
    // templates/timeline/timeline.html
    document.addEventListener('DOMContentLoaded', function() {
      ReactDOM.render(
        React.createElement(
          'div',
          {
            children: 'TIMELINE CONTENT HERE',
            className: 'timeline-content'
          }
        ), document.getElementById('timeline'));
    });
  </script>
{% endblock %}

Step 4 - Use a React toolkit to build a React Component

Story Time

Initially, I tried to use create-react-app as this has worked great for me in the past. However, it did not take long for me to realise that this was not really the right tool for what we were doing. Firstly - this is not a single page app, this is an existing Django application that we want to integrate a stand-alone React component within a subset of the view.
I did not want to eject and start to dig into Webpack configuration if I could avoid it so I went exploring.
I found that what I was looking for is called a 'React Toolkit' (knowing the right term helps with the Googles) and found lots of lists, even some on the create-react-app documentation.
After trying a bunch quickly, I landed two great solutions, nwb and neutrinojs.
As seems to be the case when wanting to use something open source in the Javascript ecosystem, both of these libraries were in varying states of being "production ready".
nwb was easy to get started with but the lack of updates over the past few months made it feel like it might not receive regular maintenance.
neutrinojs was the opposite, being by a team at Mozilla, it has had a massive number of updates but of course all of these were for the version 9 release candidate but the docs were for version 8.
I ended up doing almost all of this tutorial in both nwb and neutrinojs and found that neutrinojs ended up being my pick. The documentation is more complete and overall it appears to be more flexible and requires only slightly more "config" to get working compared to nwb.
I will put links at the end of this post for the roughly working code branch where nwb was used.

Code Time

Set up a client app within the Django timeline app, this approach means we will have a client folder within the timeline folder. There are many ways to organise your JS/CSS within a Django app so do whatever works for you.
Important: We will be using the version 9 release candidate, there are a few reasons for this decision. But essentially it's better and will hopefully make the shelf life of this post a bit longer. As of the time of writing, the docs for version 9 can be found here - https://master.neutrinojs.org/.
In the timeline folder run the command npx @neutrinojs/create-project@next client. This creates a new folder, named client, with the scaffolded project.
The scaffold CLI is really hhelpful, here are the answers to the questions:
- First up, what would you like to create? Components
- Next, what kind of components would you like to create? React Components
- Would you like to add a test runner to your project? Jest
- Would you like to add linting to your project? Airbnb style rules
Test out the local dev server run npm start from the client folder and you should see the demo component load in your browser at http://localhost:5000/
Add styles - add a style.css file to the example component folder - client/src/components/Example/style.css and import it in the component client/src/components/Example/index.jsx. Plain CSS works out of the box and can be imported using import './style.css';. Adding a trivial rule to the CSS such as button { background: lightblue; } allows us to test that the styles have been imported correctly.
Save the changes and confirm that the styles have been imported and used in the client demo server by opening http://localhost:5000/.

Step 5 - Render the Example component in the Django view.

Story Time

This step took the most amount of time to work out, literally days of trying things, coming back to it, switching back to nwb and then encountering similar but still frustrating issues and switching back.
I ended up having to dig into the internals of Neutrino, nwb, Webpack and a tricksy little library called webpack-node-externals.
The major disconnect here is that we are building this in a bit of a blurry world, in terms of what common requirements are expected.
Toolkits, plugins, Webpack, etc make a lot of assumptions and those are that you will be building something that is either a library (ie. publish to npm and it is imported/required into your project) or a SPA (you want to build EVERYTHING you need to get this app running with nothing but a bare index.html file).
On top of that, my knowledge about any ends of this spectrum was limited.
webpack-node-externals is used by default in a lot of build tools and makes the hard assumption that ANY import is external. Which makes sense when you want to build a small NPM utility that depends on lodash and leftpad. You really do not want to bundle these with your library.
This makes sense in terms of a common use case of Neutrino js - to output a small bundle of a 'component' without needing React and the whole universe alongside.
The other issue is that we actually do not want to bundle everything, only some things. We do not want to bundle React with this build output either as we know it is available in Django as a global that is already imported.
Thankfully Webpack is pretty amazing and lets you configure all the things including this exact scenario - which things are bundled and which things are not (along with a plethora of config about how those things are available to the build file). You can read more here https://webpack.js.org/configuration/externals/#externals.
So with that rant out of the way, let's get to the one line of code that took so long.

Code Time

Configure neutrinojs to use the global React instead of importing/requiring it. We add one more function after jest() that will determine if the build is for production and then revise part of the config accordingly.

// timeline/client/.neutrinorc.js
const airbnb = require('@neutrinojs/airbnb');
const reactComponents = require('@neutrinojs/react-components');
const jest = require('@neutrinojs/jest');

module.exports = {
  options: {
    root: __dirname,
  },
  use: [
    airbnb(),
    reactComponents(),
    jest(),
    /**
     * Ensure that react is read from global - and webpack-node-externals is NOT used.
     *
     * By default the react-components plugin uses webpack-node-externals to build
     * the externals object. This will simply get all dependencies and assume they are
     * external AND assume that requirejs is used.
     *
     * However, for a web usage, we want only some external dependencies set up and
     * want them to read from global (aka root), hence we map the 'react' import to 'React' global.
     * See:
     * 
     * https://www.npmjs.com/package/webpack-node-externals
     * https://webpack.js.org/configuration/externals/#externals
     */
    neutrino => {
      neutrino.config.when(process.env.NODE_ENV === 'production', config => {
        config.externals({ react: 'React' });
      });
    },
  ],
};

Update the Django settings to have access to this folder as a static assets folder. (Note: We can configure neutrinojs to build to any folder, but this is the simplest way forward for now).

STATICFILES_DIRS = [
    os.path.join(PROJECT_DIR, 'static'),
    os.path.join(PROJECT_DIR, 'timeline/client/build'),  # add the default neutrino.js 'build' folder
]

Now run the build output via npm run build and note that there is now a client/build folder with four files (Example.js, Example.css and a .map file for each).
Finally, update our Django template to import the Example.js and Example.css for the example component rendering. We will add the extra_css section to import the static file Example.css and add the script tag to import Example.js and update the createElement function to use Example.default

{% extends "wagtailadmin/base.html" %}
{% comment %} timeline/templates/timeline.html {% endcomment %}
{% load static %}

{% block titletag %}{{ title }}{% endblock %}
{% block bodyclass %}timeline{% endblock %}

{% block extra_css %}
    {{ block.super }}
    <link rel="stylesheet" type="text/css" href="{% static 'Example.css' %}">
{% endblock %}

{% block extra_js %}
  {{ block.super }}
  <script src="{% static 'Example.js' %}"></script>
  <script>
    document.addEventListener('DOMContentLoaded', function() {
      ReactDOM.render(
        React.createElement(
          Example.default, // note - using .default here as this is how the global is set up
          {
            children: 'TIMELINE CONTENT HERE',
            className: 'timeline-content'
          }
        ), document.getElementById('timeline'));
    });
  </script>
{% endblock %}

{% block content %}
  {% include "wagtailadmin/shared/header.html" with title=title %}
  <div class="container">
    <div id="timeline">
      {{ title }}
    </div>
  </div>
{% endblock %}

Save changes, refresh your Django dev server and check the Example component is rendered.

Step 6 - Development Workflow

Just a recap, we now have two dev servers.

client

Run by Neutrino, using npm start and avaialable at http://localhost:5000/.
This server has no awareness of Django and is purely a way to quickly work with your React client code.
Hot reloading works here, save a JS file and the dev server will update instantly.
You can modify the file timeline/client/src/index.jsx to be anything you want to make it easier for this, this file will NOT be built and is only for development.

server

Run by Django, this is your Wagtail application where you can view admin along with any of your CMS output.
This will only have access to your static assets, hence the 'production' code from your client.
Hot reloading will not work here, changing your JS file will have no effect until you run npm run build AND refresh your Django site.
Depending on your browser settings, you may need to disable caching (see your browser's dev tools). Django does a nice job of caching your styles, but this is not needed when making frequent changes.

making changes

Try to break up your work into client/server, switching between the two less frequently. This helps you batch changes into the two areas of the code and lets you build the compiled output less frequently saving you time.
Try to make your dev demo file reflect data and parts of the Django admin you want to be thinking about (eg. you may want to add a simple sidebar). timeline/client/src/index.jsx.
Biggest thing - remember that after saving the JS and CSS files that you need to run the Neutrino build again to make the changes available to Django.

Step 7 - Make a Timeline.jsx component

We will need to install a few npm libraries:
- react-calendar-timeline which also has a peer dependency interactjs
- classnames - a great helper util used to generate clean classNames for React components
- moment - needed for date management and also is a peer dependency of react-calendar-timeline
These can be imported by running npm install react-calendar-timeline classnames moment interactjs
Let's leave Example.js as is for now and create a new component by following the example in the react-calendar-timeline README.

// timeline/client/src/components/Timeline/index.js
export { default } from './Timeline';

/* timeline/client/src/components/Timeline/timeline.css */
.timeline {
  background: lightblue;
}

// timeline/client/src/components/Timeline/Timeline.jsx

import React from 'react';
import PropTypes from 'prop-types';

import classNames from 'classnames';
import moment from 'moment';
import CalendarTimeline from 'react-calendar-timeline';

// styles
import 'react-calendar-timeline/lib/Timeline.css'; // must include to ensure the timeline itself is styled
import './timeline.css';

const Timeline = ({ className }) => {
  const groups = [
    { id: 1, title: 'group 1' },
    { id: 2, title: 'group 2' },
  ];

  const items = [
    {
      id: 1,
      group: 1,
      title: 'item 1',
      start_time: moment(),
      end_time: moment().add(1, 'hour'),
    },
    {
      id: 2,
      group: 2,
      title: 'item 2',
      start_time: moment().add(-0.5, 'hour'),
      end_time: moment().add(0.5, 'hour'),
    },
    {
      id: 3,
      group: 1,
      title: 'item 3',
      start_time: moment().add(2, 'hour'),
      end_time: moment().add(3, 'hour'),
    },
  ];

  return (
    <div className={classNames('timeline', className)}>
      <CalendarTimeline
        groups={groups}
        items={items}
        defaultTimeStart={moment().add(-12, 'hour')}
        defaultTimeEnd={moment().add(12, 'hour')}
      />
    </div>
  );
};

Timeline.propTypes = {
  className: PropTypes.string,
};

Timeline.defaultProps = {
  className: '',
};

export default Timeline;

Important: We need to update our demo page (Remember: Used only while developing the client code) to use the Timeline component not Example.

// timeline/client/src/index.jsx

import React from 'react';
import { render } from 'react-dom';
import Timeline from './components/Timeline';

render(
  <main className="main">
    <header role="banner">
      <div className="row nice-padding">
        <div className="left">
          <div className="col header-title">
            <h1 className="icon icon-">Timeline</h1>
          </div>
        </div>
        <div className="right" />
      </div>
    </header>
    <Timeline className="additional-class" />
  </main>,
  document.getElementById('root'),
);

Test this all works on your client dev server, confirm the CSS is used and you have a basic timeline rendering.
Run npm run build to build your static assets.
Update timeline.html (the Django view) to use the new component.

{% block extra_css %}
    {{ block.super }}
    <link rel="stylesheet" type="text/css" href="{% static 'Timeline.css' %}">
{% endblock %}

{% block extra_js %}
  {{ block.super }}
  <script src="{% static 'Timeline.js' %}"></script>
  <script>
    document.addEventListener('DOMContentLoaded', function() {
      ReactDOM.render(
        React.createElement(
          Timeline.default, // note - using .default here as this is how the global is set up
          {
            className: 'timeline-content'
          }
        ), document.getElementById('timeline'));
    });
  </script>
{% endblock %}

Refresh your Django dev server and confirm you have a basic timeline rendering.

Step 8 - Connect to Wagtail's API

Our goal out of this step is to be able to read a response from Wagtail's API in our React component.

It is important to note that while developing with the API, we need to have two things running. Firstly we need to have our client running via npm start and also our Django app running which will handle the API requests.

Update API max response WAGTAILAPI_LIMIT_MAX = 100 in our Django settings, the default is 20 and we want to allow for returning more Pages in our use case.
Run the client app and the Django app. Client - npm start, server - ./manage.py runserver.
Set up the proxy, this is a development feature in neutrinojs which will let us redirect our JavaScript client dev server requests to the Wagtail API.

// client/.neutrinorc.js
// replace `reactComponents()` with the same call but with an objects object passed in.
    reactComponents({
      /** Change options related to starting a webpack-dev-server
       * https://webpack.js.org/configuration/dev-server/#devserverproxy
       * Proxy requests to /api to Wagtail local Django server
       */
      devServer: { proxy: { '/api': 'http://localhost:8000' } },
    }),

Now we can build a React component that fetches the API's data and transforms it into data we want for our rendering. This step may be a big jump if you are new to React, but we will explain more after the code snippets.

New File - Messages.jsx

This will render our loading message and potentially any error message using class names that already exist in the Wagtail Admin CSS.

// client/src/Timeline/Messages.jsx
import React from 'react';
import PropTypes from 'prop-types';

/**
 * A verbose example of a Functional component. Messages renders the loading or
 * error message states.
 * @param {Object} props
 */
const Messages = ({ error, isLoading }) => (
  <div className="messages">
    <ul>
      {isLoading && <li className="success">Loading...</li>}
      {error && (
        <li className="error">
          <span>Error: </span>
          {error.message}
        </li>
      )}
    </ul>
  </div>
);

Messages.defaultProps = {
  isLoading: false,
  error: {},
};

Messages.propTypes = {
  isLoading: PropTypes.bool,
  error: PropTypes.shape({
    message: PropTypes.string,
  }),
};

export default Messages;

New File - get-transformed-response.js

This is a pure function, takes the response from the API and prepares the data we need for our Timeline component.

// client/src/components/Timeline/get-transformed-response.js
/* eslint-disable camelcase */
import moment from 'moment';

const getTransformedItems = ({ items = [] } = {}) =>
  items.map(({ meta: { first_published_at, type, ...meta }, ...item }) => ({
    ...item,
    ...meta,
    group: type,
    start_time: moment(first_published_at),
    end_time: moment().add(1, 'year'), // indicates they are live
  }));

const getGroups = items =>
  items
    .map(({ group }) => group)
    .reduce((groups, group, index, arr) => {
      if (arr.indexOf(group) >= index) {
        return groups.concat({
          id: group,
          /* convert 'base.IndexPage' to 'Index Page' */
          title: group.replace(/([a-z](?=[A-Z]))/g, '$1 ').split('.')[1],
        });
      }
      return groups;
    }, []);

const getDefaultTimes = items =>
  items.reduce(({ start = null, end = null }, { start_time, end_time }) => {
    if (!start && !end) return { start: start_time, end: end_time };
    return {
      start: start_time.isBefore(start) ? start_time : start,
      end: end_time.isAfter(end) ? end_time : end,
    };
  }, {});

const getTransformedResponse = response => {
  const items = getTransformedItems(response);
  return {
    defaultTimes: getDefaultTimes(items),
    groups: getGroups(items),
    items,
  };
};

export default getTransformedResponse;

Revised File - Timeline.jsx

// timeline/client/src/components/Timeline/Timeline.jsx

import React, { PureComponent } from 'react';
import PropTypes from 'prop-types';

import classNames from 'classnames';
import CalendarTimeline from 'react-calendar-timeline';

import Messages from './Messages';
import getTransformedResponse from './get-transformed-response';

// styles
import 'react-calendar-timeline/lib/Timeline.css'; // must include to ensure the timeline itself is styled
import './timeline.css';

class Timeline extends PureComponent {
  state = {
    defaultTimes: {},
    error: null,
    groups: [],
    isLoading: true,
    items: [],
  };

  componentDidMount() {
    this.fetchData();
  }

  /** set state to loading and then call the API for the items data */
  fetchData() {
    const { apiUrl } = this.props;
    this.setState({ isLoading: true });
    fetch(apiUrl)
      .then(response => response.json())
      .then(({ message, ...data }) => {
        if (message) throw new Error(message);
        return data;
      })
      .then(getTransformedResponse)
      .then(({ items, defaultTimes, groups }) =>
        this.setState({
          defaultTimes,
          error: null,
          groups,
          isLoading: false,
          items,
        }),
      )
      .catch(error => this.setState({ error, isLoading: false }));
  }

  render() {
    const { className } = this.props;
    const {
      defaultTimes: { start, end },
      error,
      groups,
      isLoading,
      items,
    } = this.state;

    return (
      <div className={classNames('timeline', className)}>
        {isLoading || error ? (
          <Messages error={error} isLoading={isLoading} />
        ) : (
          <CalendarTimeline
            defaultTimeEnd={end}
            defaultTimeStart={start}
            groups={groups}
            items={items}
            sidebarWidth={250}
            stackItems
          />
        )}
      </div>
    );
  }
}

Timeline.defaultProps = {
  apiUrl: '/api/v2/pages/?limit=100',
  className: '',
};

Timeline.propTypes = {
  apiUrl: PropTypes.string,
  className: PropTypes.string,
};

export default Timeline;

Explanation

Our Timeline React Component has been changed to a class component.
The component has its own state and on componentDidMount it will call its own fetchData function.
fetchData sets the component's isLoading state to true, reads the api url from props (which defaults to Wagtail's pages endpoint) and does some basic error handling, JSON parsing and finally sends the response data through our transformer, setting the state to our transformed results.
The render method on our component will output the data from state into our timline, but may render the Messages component while the data is still loading or if any errors occured.
Our transformer file does the heavy lifting of working out what dates to show on the calendar based on the dates from the pages response, also prepares the groups based on the page type. We also do a bit of formatting on the native page type to make it read nicer.
The transformer also prepares the default start/end dates based on the overall dates of the response's pages.
We should be able to see the data from the API now in the component.
Run npm run build and then you can see the changes within your Wagtail application.

Step 9 - Integrate with the Wagtail Admin search box

Now we want to show an example of Wagtail's Django templates and views working with our React component.
First, update the view to include handling and passing of the search query in the URL params. The existing wagtailadmin/shared/header.html include in the timeline.html template will read the search_form from context.

# timeline/views.py

from django.shortcuts import render

from wagtail.admin.forms.search import SearchForm


def timeline_view(request):
    # Search Handling
    query_string = None
    if 'q' in request.GET:
        search_form = SearchForm(request.GET, placeholder='Search timeline')
        if search_form.is_valid():
            query_string = search_form.cleaned_data['q']
    else:
        search_form = SearchForm(placeholder='Search timeline')

    return render(request, "timeline.html", {
        'icon': 'time', # pass in an icon to show in the header
        'query_string': query_string or '',
        'search_form': search_form,
        'search_url': 'timeline',  # url name set by wagtail_hooks
        'title': 'Timeline',
    })

Then we need to pass in the search form's id and current query to our React component. This will mean we can update the timeline live as the user types into the search form, and handle the cases where a URL is copied or the user presses enter to submit the search form.
Here we only need to change the block extra_js, essentially adding two props, the initialSearchValue and the searchFormId. Note: id_q is just the existing convention that Wagtail has, it is set up automatically by Wagtail.

{% block extra_js %}
  {{ block.super }}
  <script src="{% static 'Timeline.js' %}"></script>
  <script>
    document.addEventListener('DOMContentLoaded', function() {
      const props = { className: 'inner timeline-content', initialSearchValue: '{{ query_string }}', searchFormId: 'id_q' };

      ReactDOM.render(
        React.createElement(
          Timeline.default, // note - using .default here as this is how the global is set up
          props
        ), document.getElementById('timeline'));
    });
  </script>
{% endblock %}

Now we can set up an event listener on our form, along with basic text search filtering.
Below we have added three new methods;
- onSearch - handles the input as the user types in the search box.
- setUpSearchForm - called on mount and sets up the listener and initial state.
- getFilteredItems - returns a filtered array of items based on the search string.
We have also revised the props & default props to include initialSearchValue and searchFormId.
Finally, we have customised the actual timeline rendering to show the searched string in the header, plus returning only the filtered items to the calendar timeline.

// timeline/client/src/components/Timeline/Timeline.jsx

import React, { PureComponent } from 'react';
import PropTypes from 'prop-types';

import classNames from 'classnames';

import CalendarTimeline, {
  DateHeader,
  SidebarHeader,
  TimelineHeaders,
} from 'react-calendar-timeline';

import Messages from './Messages';
import getTransformedResponse from './get-transformed-response';

// styles
import 'react-calendar-timeline/lib/Timeline.css'; // must include to ensure the timeline itself is styled
import './timeline.css';

class Timeline extends PureComponent {
  state = {
    defaultTimes: {},
    error: null,
    groups: [],
    isLoading: true,
    items: [],
    searchValue: null,
  };

  componentDidMount() {
    this.fetchData();
    this.setUpSearchForm();
  }

  /** handler for search form changing */
  onSearch({ target: { value } = {} } = {}) {
    const { searchValue } = this.state;

    if (value !== searchValue) {
      this.setState({ searchValue: value });
    }
  }

  /** set up a listener on a search field that is outside this component
   * (rendered by Django/Wagtail) */
  setUpSearchForm() {
    const { initialSearchValue, searchFormId } = this.props;
    this.setState({ searchValue: initialSearchValue });

    /** set up a listener on a search field that is outside this component
     * (rendered by Django/Wagtail) */
    const searchForm = document.getElementById(searchFormId);
    if (searchForm) {
      searchForm.addEventListener('keyup', event => this.onSearch(event));
    }
  }

  /** return filtered items based on the searchValue and that
   * value being included in either the group (eg. Location Page) or title.
   * Ensure we handle combinations of upper/lowercase in either part of data.
   */
  getFilteredItems() {
    const { items, searchValue } = this.state;

    if (searchValue) {
      return items.filter(({ group, title }) =>
        [group, title]
          .join(' ')
          .toLowerCase()
          .includes(searchValue.toLowerCase()),
      );
    }
    return items;
  }

  /** set state to loading and then call the API for the items data */
  fetchData() {
    const { apiUrl } = this.props;
    this.setState({ isLoading: true });
    fetch(apiUrl)
      .then(response => response.json())
      .then(({ message, ...data }) => {
        if (message) throw new Error(message);
        return data;
      })
      .then(getTransformedResponse)
      .then(({ items, defaultTimes, groups }) =>
        this.setState({
          defaultTimes,
          error: null,
          groups,
          isLoading: false,
          items,
        }),
      )
      .catch(error => this.setState({ error, isLoading: false }));
  }

  render() {
    const { className } = this.props;
    const {
      defaultTimes: { start, end },
      error,
      groups,
      isLoading,
      searchValue,
    } = this.state;

    return (
      <div className={classNames('timeline', className)}>
        {isLoading || error ? (
          <Messages error={error} isLoading={isLoading} />
        ) : (
          <CalendarTimeline
            defaultTimeEnd={end}
            defaultTimeStart={start}
            groups={groups}
            items={this.getFilteredItems()}
            sidebarWidth={250}
            stackItems
          >
            <TimelineHeaders>
              <SidebarHeader>
                {({ getRootProps }) => (
                  <div {...getRootProps()}>
                    {searchValue && (
                      <div className="search">
                        <strong className="search-label">Search: </strong>
                        <span className="search-value">{searchValue}</span>
                      </div>
                    )}
                  </div>
                )}
              </SidebarHeader>
              <DateHeader unit="primaryHeader" />
              <DateHeader />
            </TimelineHeaders>
          </CalendarTimeline>
        )}
      </div>
    );
  }
}

Timeline.defaultProps = {
  apiUrl: '/api/v2/pages/?limit=100',
  className: '',
  initialSearchValue: null,
  searchFormId: null,
};

Timeline.propTypes = {
  apiUrl: PropTypes.string,
  className: PropTypes.string,
  initialSearchValue: PropTypes.string,
  searchFormId: PropTypes.string,
};

export default Timeline;

For the sake of development testing, we can revise our demo (index.jsx) to include a search box.

// timeline/client/src/index.jsx

import React from 'react';
import { render } from 'react-dom';
import Timeline from './components/Timeline';

render(
  <main className="main">
    <header role="banner">
      <div className="row nice-padding">
        <div className="left">
          <div className="col header-title">
            <h1 className="icon icon-">Timeline</h1>
          </div>
        </div>
        <div className="right">
          <label htmlFor="id_q">
            Search term:
            <input type="text" name="q" id="id_q" placeholder="Search" />
          </label>
        </div>
      </div>
    </header>
    <Timeline className="additional-class" searchFormId="id_q" />
  </main>,
  document.getElementById('root'),
);

Add a bit of CSS polish, align the colours with Wagtail's Admin & make the timeline header sticky (Note: Will not work on IE11).

/* timeline/client/src/components/Timeline/timeline.css */
.timeline .react-calendar-timeline .rct-header-root {
  background: #007d7e; /* wagtail teal */
  position: sticky;
  top: 0;
  z-index: 90;
}

.timeline .search {
  align-items: center;
  color: white;
  display: flex;
  height: 100%;
  padding: 1rem;
}

.timeline .search .search-label {
  text-transform: uppercase;
  padding-right: 0.25rem;
}

Step 10 - Final View & Future Improvements

Now, run npm run build and test on your Wagtail instance. Also test submitting the form (pressing enter) after typing in the search box.

Here is an animation of the final state.

Future Improvements

This is a read-only timeline, and there are lots of ways this could be improved upon.
You could add milestones or coloured parts of the timeline bar to indicate when the Page has had changes or whether the Page is live or still a draft.
You may want to add the ability to click on a Page in the timeline and then a popover will show additional info and links.
Grouping should be specific to your Wagtail use case, you could even have various versions of the timeline that group in different ways (adding a Django view button to the header that will then be listened to by the React component).
Finally, you could add the ability to drag & drop or edit in the timeline, possibly to even determine when posts or pages will go live.

References & Links

Thanks to some of the Wagtail core team and Adam who helped proofread this.

Versions used

As at writing.

Django 2.3
Wagtail 2.7 (LTS)
Python 3
React 16.4
Node 10
Neutrinojs 9.0.0-rc.5 Pre-release
React Calendar Timeline 0.27

DEV Community: LB (Ben Johnston)

On mentoring for an an open-source internship

Core skills

Bonus learnings

What was achieved

Acknowledgements

Round two?

More about this project

Creating an interactive event budgeting tool within Wagtail

Goal

Tutorial

0. Getting started

Versions

1. Set up the data Model

2. Set up the field widgets

3. Set up a custom wrapper Panel container

4. Set up JavaScript sprinkles

5. Add total calculation logic to JavaScript

Next steps

Further reading

Ten tasty ingredients for a delicious pull request

Tasty ingredients

1. Read the [development] instructions

About ‘fork the code’

2. Read the issue and comments

3. Create a fresh branch for your contributions

4. Keep the changes focused

5. Write unit tests

6. Give your pull request a name with context

7. Reference the issue being fixed or resolved in the pull request

8. Review & fix the CI failures

9. Push to the same branch with fixes and do not open a new pull request

10. Eagerness balanced with patience

Final thoughts

Bonus: Learn how to rebase on main/master

Credits

Creating a schematic editor within Wagtail CMS with StimulusJS

Goal

Our approach

Versions

Assumptions

Tutorial

Part 1 - Create a new schematics app plus Schematic & SchematicPoint models

Code - models.py

Part 2 - Create a new ProductPage model that will use the schematic model

Code - models.py

Part 3 - Output the points over an image in the Page's template

Code - myapp/templates/schematics/product_page.html

Part 4 - Enhance the editor's experience to show a different image size

Part 4a - Adding Stimulus via wagtail_hooks

Create a new file schematics/wagtail_hooks.py

Part 4b - Creating schematics/edit_handlers.py with a custom ImageChooserPanel

Part 4c - Adding a custom EditHandler

In the file schematics/edit_handlers.py create a custom SchematicEditHandler

Use the SchematicEditHandler on the Schematic model

Part 4d - Adding initial JS & CSS for the schematic edit handler

Create schematic-edit-handler.js - Stimulus Controller

Create static/css/schematic-edit-handler.css styles

Part 5 - Enhance the editor's experience to show point positioning

5a - Add a SchematicPointPanel that will use a new template schematics/edit_handlers/schematic_point_panel.html

5b - Use the SchematicPointPanel in models.py & update attrs

5c - Add a template to templates/schematics/edit_handlers/schematic_edit_handler.html

5d - Update the SchematicEditHandler Stimulus controller to output points

5e - Add styles for the points in schematic-edit-handler.css

5f - Validation & congrats

Part 6 (Bonus) - Drag & Drop!

6a - Add more data attributes to the point template

6b - Update the SchematicEditHandler Controller to handle drag / drop behaviour

Finishing Up & Next Steps

Further Improvements

Why Stimulus and not ... other things

Updates

Adding Tasks with a Checklist to Wagtail Workflows

Journey

What We Are Building

Tutorial

Step 0 - Getting Started

Step 1 - Create the ChecklistApprovalTask Model

Code models.py

Step 2 - Revise the Actions to Always Show the Form Modal

Bonus: Learn how to rebase on `main`/`master`

Part 1 - Create a new `schematics` app plus `Schematic` & `SchematicPoint` models

Code - `models.py`

Part 2 - Create a new `ProductPage` model that will use the `schematic` model

Code - `models.py`

Part 3 - Output the points over an image in the `Page`'s template

Code - `myapp/templates/schematics/product_page.html`

Part 4a - Adding Stimulus via `wagtail_hooks`

Create a new file `schematics/wagtail_hooks.py`

Part 4b - Creating `schematics/edit_handlers.py` with a custom `ImageChooserPanel`

Part 4c - Adding a custom `EditHandler`

In the file `schematics/edit_handlers.py` create a custom `SchematicEditHandler`

Use the `SchematicEditHandler` on the `Schematic` model

Create `schematic-edit-handler.js` - Stimulus Controller

Create `static/css/schematic-edit-handler.css` styles

5a - Add a `SchematicPointPanel` that will use a new template `schematics/edit_handlers/schematic_point_panel.html`

5b - Use the `SchematicPointPanel` in `models.py` & update `attrs`

5c - Add a `template` to `templates/schematics/edit_handlers/schematic_edit_handler.html`

5d - Update the `SchematicEditHandler` Stimulus controller to output points

5e - Add styles for the points in `schematic-edit-handler.css`

6b - Update the `SchematicEditHandler` Controller to handle drag / drop behaviour

Step 1 - Create the `ChecklistApprovalTask` Model

Code `models.py`

Code `models.py`

Code `models.py`

Code `models.py`

3. Add the hooks for the `modelAdmin`

4. Customise the `Guide` menu item

4a. Add a method to the `Guide` model

4b. Create a `menu.py` file

5a. Importing the `shepherd.js` library

1. Extend the `AbstractFormField` Class

2. Extend the `FormBuilder` Class

3. Set the FormPage class to use `CustomFormBuilder`