Wagtail Wednesdays #01 - Adding Help Text to Improve Wagtail Editor Experience

Hi, welcome to our first Wagtail Wednesday, a weekly video designed to help you get the very best out of the Wagtail CMS for your users 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. 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 models. py 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 that we've capped the title character field to 100 characters, so let's 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. Now that we know how to add help text to a basic field, let's have a look at adding it to a block. If you don't know, blocks are what we use when we are working with stream fields. Here we have a basic stream field set up with a few blocks that we can select and add. Let's 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 stream field 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's displayed underneath rather than at the right hand side. But this is a basic block with one field. Let's take a look at something more complicated. Here we have a custom multi-field block. This is a struck 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 author's 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 strup block 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 move 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 textbook You can see that the health 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 let's 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 of the fields. Next, we're going to take a look at chooser panels and how we add help text to those. Coser 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 the link of the target. If we take a look in the models. py 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 foreign key value. To add help text to this chooser, we actually have to pass the attribute to the foreign key call So let's 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.

Choose a block also exists for use in Streamfields, but you can just treat those like regular blocks and add the help text into the block itself. 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. Let's 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, let's put our field panel inside a multi-field panel.

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.

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 Thanks for watching our brief video on using HelpTax in Wagtail. To be notified when we release more videos, subscribe to our channel below.