Adding Help Text to Improve the Content Editor Experience - Wagtail Wednesday

By Catherine McDonough Christopher Shaw

When creating a website with a CMS one of the most important factors to consider is the content editor experience. Developers should do the hard work to make things simple for content editors, assume nothing and be informed by user research. Adding content should be clear and easy, cryptic field names should be made simpler and supporting help text will go a long way in helping your users manage content effortless.

In this video we will talk you through the steps you can take to add some useful supplementary text fields to the Wagtail admin, helping you in your journey to creating great sites for yourself, your clients and your users.


Section 0 - Intro

In this video we’re going to show you how to add supplementary text to fields in the Wagtail admin to help make it clearer and easier for content editors. We’ll also briefly touch on some best practices in terms of what you should be thinking about when actually creating this text.

While it’s not terribly difficult to do, there are some nuances and slight differences to keep in mind when trying to add supplementary text to different types of fields, blocks and chooser panels but hopefully after watching this video you’ll be comfortable with it.

Section 1 - Fields

Here we have an example of a page with a variety of different types of field, including some chooser panels for images and pages and so on.

Looking at our file, we can see how these fields have been declared. We have a mix of fields, blocks and choosers in here.

First, we’re going to add some help text to our hero header, here. The field name might be self explanatory to some people, but we can add something like ‘Very large, front and centre page header - ideally under 25 characters’ just to give our content editors a bit of a hint on how the field will be used in the template and how long they should aim to make the input text.
You could also let them know about any length limits you might have imposed in the back end - in the models here you can see we’ve capped the title character field to 100 characters so lets make sure to add that into our help text too.

Now we can refresh our admin view, and we can see that the help text has appeared!

Section 2 - Blocks

Now that we know how to add help text to a basic field, lets have a look at adding it to a block.

If you don’t know, blocks are what we use when we are working with Streamfields. Here we have a basic Streamfield set up with a few blocks that we can select and add. Lets just add a basic Text block to keep things simple for now.

Blocks work a little differently than fields, but the implementation is relatively similar. Here we can see our Streamfield with our text block defined inside it. We can add some help text to the block in the exact same way that we added it to our character field earlier.

If we look at our admin view we’ll see that our help text has appeared but it looks a little different than the help text for our title field. For one thing, the block help text is always visible and it displayed underneath rather than the right hand side. But this is a basic block with one field, lets take a look at something more complicated.

Here we have a custom Multi Field block. This is a struct block that we’ve created to allow us to easily create quotes. It contains a text block for the quote text, a character block for our authors name and a link block to contain a url that could be used to link back to the source for attribution purposes.

If we just add some help text to the StructBlock itself just like we did for the text block previously, you can see that the help text behaves differently again. This time the help text appears above the block but also retains some properties similar to the field help text in that it only appears when you’re interacting with that block and then fades out when you moved away from it. The question mark icon is also present.

If we go back to our model and add some help text to the quote text block, you can see that the help text appears underneath that individual block as you’d expect.

We usually add help text that pertains to the use of the overall block to the struct block and then help text for each individual field on the blocks within it. Let's just add some text to our struct block here saying something along the lines of ‘A block for adding uplifting quotes from external sources.’ Then lets add some help text to each of our children blocks, just explaining exactly what they are and what the format should be. Now we should finally have some helpful text on all the fields.

Section 3 - Chooser Panels

Next, we’re going to take a look at chooser panels and how we add help text to those. Chooser panels like this one are used to select things like images, pages, documents and so on that exist on your Wagtail site. It’s a lot less error prone than just putting a link into a url field for local assets as all references will automatically update if you change anything like the name or link of the target.

If we take a look in the file, we can see that these are a little bit more complicated. We have an image chooser panel here referencing this cover image variable which holds a foreignkey value. To add help text to this chooser, we actually have to pass the attribute to the ForeignKey call, so lets add one here underneath the related_name attribute. Now, if we refresh our editor view, we’ll see the help text appear on the right hand side, similar to a regular field.

Chooser blocks also exist for use in Streamfields, but you can just treat those like regular blocks and add the help text into the block itself.

Section 4 - Multifield Panels

The last thing that we’re going to cover in this video, is a way to move help text for fields from the right hand side of the input field to underneath - similar to blocks. Lets see an example of why we might want to do this.

If we modify the help text to be very long, we can see that it no longer fits in the small box on the right hand side.

Going back into the code, lets put our FieldPanel inside a MultiFieldPanel.

When we refresh we’ll see that the help text for any fields inside our multi field panel is now displayed underneath.

We can also add some help text to the Multi Field panel itself. Help text entered here will be displayed on the right hand side of our Multi Field panel fields in the editor.”

Don't forget to make and run migrations for your app after making changes to your fields.

Section 5 - Show Good Help Text On All Fields And Ideas

So applying what we’ve learnt to all the fields on the page, we can end up with something like this. We’ve added help text that describes each field in more detail, and made sure to point out any limitations and/or recommendations for the data that will be going into them.

Section 6 - Outro

Thanks for watching our brief video on using help text in Wagtail. To be notified when we release more videos subscribe to our channel below.

Want Early Access To Future Videos?

Pop your email address in the box below and receive new videos before everyone else!

<< Back to Insights