Best Practices for Making a Wagtail Site as Accessible as Possible with Scott Cranfill

Hello Django Knots. My name is Scott Cranville. My pronouns are he him, and this is my talk on best practices for making a Wagtail site accessible. Uh but wait, that's not quite right. Let me see. Yes, there we go. Best practices for making a Wagtail site as accessible as possible. Because perfect accessibility is not an achievable goal, but we can keep learning how to do better, and I'm hopeful that this presentation will help you do that. To introduce myself briefly, I work as a full-stack web developer at NASA's Jet Propulsion Laboratory, but I'm speaking here in my personal capacity, not from my employer. I'm recording this from my home office here in Rochester in the western part of New York State in the U.

S. which is closer to Niagara Falls than New York City. And aside from just using Wagtail at JPL, I'm also a member of the Wagtail Open Source Projects core team, which means that I pitch in on Wagtail development and community-building efforts. If you're not familiar with Wagtail, it is the leading Python-based open source content management system, or CMS, and it's built upon the awesome foundation of Django. It's also 100% free no matter what you want to use it for. Aside from JPL, it's used by a number of other well-known organizations such as Google, Mozilla. the UK's National Health Service and the U. S. Consumer Financial Protection Bureau.

You could learn more about Wagtail. by visiting wagtail. org or our main GitHub repository at github. com slash wagtail slash wagtail I have two target audiences for this talk. One is developers like me, who already work on Wagtail-powered websites and are looking to improve the accessibility of them. And two, those who might be hearing about Wagtail for the first time or are already considering it for their next project. Hopefully you will like what you see. Now we need to introduce accessibility a little bit. I won't go into an exhaustive list of accessibility rules and standards This talk is about mitigating some of the most common issues that I've seen as a developer, but I want to give a high-level overview for those who are new to the topic.

It's easy to find lots of information about accessibility out there, but here's a definition that I came up with off the top of my head. Accessibility is the practice of ensuring that our web content is able to be consumed by the widest possible spectrum of people with varying abilities and disabilities, whether they are using traditional browsers or assistive technology. Website owners in many locales have some legal obligations to meet certain accessibility requirements. Here in the U. S. we have the Americans with Disabilities Act of 1990, which applies to all websites that serve the general public, as it does to physical facilities that are open to the public. Domino's Pizza was famously sued under this act for their website

failing badly at accessibility, and they eventually settled with the plaintiff for an undisclosed amount of money after a six-year fight that went all the way to the Supreme Court. And more specifically for government websites, we also have Section 508 of the Rehabilitation Act of 1973, which is part of a 1998 amendment to that act. Its latest update requires that federal government websites conform to version 2. 0 of the Web Content Accessibility Guidelines, also known as WCAG, level AA or better WCAG is not just for government sites, though, it's been the world's leading set of web accessibility standards for over two decades now. But even if you're not bound by applicable laws in your area, I would argue that as website creators, we all have a duty to put some effort into the accessibility of our sites.

Building an inclusive world is everyone's responsibility, and web accessibility is one place where us developers can contribute with just a little bit of consideration and effort. Now I'll step off the soapbox and get to the meat of the talk. The Whitel project has made a pretty serious commitment to accessibility in recent years. It began with the forming of a dedicated sub-team in 2020 for working on accessibility issues. This team is led by my fellow Wagtail Core Team member Thibaut Kolos, who has been the number one driver of Wagtail's accessibility efforts over the years. Don't miss his closing talk today on Django 's accessibility track record at 4 p. m. Eastern, just a couple of hours from now.

And our accessibility subteam has worked together to devise an accessibility statement for the Wagtail project, which you can find at Wagtail. org slash accessibility. It explains some of the specific goals that we are striving for and serves as a public declaration of our commitment. In particular, it describes our two-pronged approach of wanting to both improve the accessibility of the Wigtail interface itself and also the accessibility of websites that White Tail has used to create. We've also had the pleasure of participating in the Google Summer of Code and Outreachy programs several times now, which has included two accessibility-specific projects, one on each prong.

The first was an improvement to forced color support in the Wagtail admin. For example, if you were using Windows High Contrast Mode. And that was with participant Anuja Raj Verma and mentor Jane Hughes. The second was the creation of an on-page accessibility checker for editors. with participant Albinia Stariakova and mentors Sage Abdullah and Joshua Munn. And hopefully you caught Sage 's talk on Monday afternoon. The accessibility checker, which was added in Whiteil 4. 2 earlier this year, is the hallmark feature of our efforts to improve the accessibility of sites made with Whiteil. It's based on the Axe engine from DQ

Systems, which you may be familiar with from its browser extension, or tools like Google's Lighthouse. And the goal is to make it easy for content editors to identify accessibility issues that they can address themselves. Let's take a quick look at it in action. This is Wagtail's bakery-themed demo site, which you can find at github. com slash Wagtails slash bakery demo. And I'll just go to the admin area here and log in. And then once I return to the homepage and refresh , We can now see the Wagtail button down here in the lower right.

We call this the user bar. This appears for logged-in users and it gives them easy access to different Wagtail functions And this is where the accessibility checker lives. And you can see right away that even our demo is not immune to accessibility issues. Let's see what it's telling us here. Okay, all page content should be contained by landmarks, and if we click here we can highlight the section of the page that it is identified as having the problem and it turns out to be our logo up here in the header. That is interesting. We'll come back to that. As I mentioned, the White Tail Accessibility Checker is primarily geared toward helping content editors find things they can correct, but

There is still a lot that developers need to do to set their editors up for success. And that is going to be the meat of this talk. What are our responsibilities? Or what are the guardrails that we can put in place to help ensure that we end up with a website that's as accessible as possible? So I'll quickly go through the list of topics that we're going to cover in the rest of the talk. Semantic markup and templates. Configuring Whitel 's accessibility checker. enforcing proper heading hierarchy, promoting good alt text, and not using it where it's not appropriate , Using ARIA labels to add context to links, and helping editors help themselves.

Starting with semantic markup in templates. That error that we saw in the accessibility checker is a good example of needing to start from a base of quality, accessible markup in our templates. The accessibility checker being used diligently by content editors doesn't mean squat if that code that they can't control has major accessibility problems. Semantic markup is crucial for your website to be understood by machines, whether that means assistive technology like a screen reader or things like search engine crawlers. Your primary concern in the context of templates for a Wagtail site is ensuring that all of the landmarks are in place. That error that we got was all page content should be contained by landmarks and it was pointing to our main logo, as we can see here again.

And let's take a quick look at the template for this part of the page and fix it. This is our header. html uh template where the uh header for this website lives you can't see the complete rendered HTML of the page in this in this partial template but in this case The issue is that our header here is in a div, and that div does not have the attribute of role equals banner, which would identify it as a banner landmark We could add that attribute, but an even better solution would be to change the actual tag to header, one of the relatively new semantic elements that was introduced When the HTML5

standard was developed. We can use header because header comes with the implicit role of banner, making the role attribute unnecessary So I'll save this and uh return to the browser, refresh our page, and we can see that the error has gone away. The accessibility checker is happy. Okay. I strongly encourage you to take advantage of the implicit roles provided by those new HTML5 elements. Aside from PETAR, there's the other And most important ones are footer, main, nav, and aside. They keep your markup cleaner and help avoid a bit of the div

soup that we so often fall into these days. We'll have more to cover on semantic markup when we get into the parts that editors have control over when building a page. Now there's something that I haven't mentioned yet about that error that the accessibility checker gave us. By default, on a fresh Wytail installation, that error would not be shown. Remember, the Accessibility Checker's primary audience is for content editors to preview the pages that they are building and identify changes that they need to make in their content. Errors of the kind that we saw, missing landmarks, are not something that editors can help with, so that wouldn't be shown. But the accessibility checker is configurable to show more kinds of errors, all of the kinds of errors that are supported by the Axe engine, in fact.

And that is how the bakery demo is set up. I recommend that you, as a Wagtail developer, configure your site similarly so that as you personally browse the site, you can catch errors that may need to be addressed through code rather than content. And there's a handy recipe for doing this in the Whitetail docs, which is linked to from the bottom of the slide. Let's move on to one of the most common accessibility errors out there, but it's an easy one to address, incorrect heading hierarchy. I 'll return to the bakery demo and take a look at this breads page here. And I'll demonstrate a couple common errors on this website, and one that is developer responsibility and one that is an editor responsibility.

And if we take a look at this reds page here, you'll see that we're getting getting an error for incorrect heading hierarchy Avoid skipping levels, and it's pointing to this Balani heading, uh the first of these different kinds of bread cards. Uh and the issue is that we have our H1 up here, Breads, the top-level heading on the page, but we're skipping right to H3 on this Balani heading, with no H2 in between Screen readers and site crawlers rely on having a logical document structure to understand the content of your page, and the headings are the primary way in which they interpret that structure. One way to think about this is to think back to high school when you had to write a research paper

and your teacher had you outline it in a big multi-level numbered outline You know, probably you wrote it in Microsoft Word. If you had this big multi-level numbered outline and you indented two levels at once, that would look pretty strange, wouldn't it? Similarly, the web page headings should avoid skipping levels because they create that virtual outline of the page. So the checker is telling us that we have this error, but if we look at the page's edit view, which I can get to through the user bar here. You'll see that we can't do anything about that. Uh the editor cannot do anything about it because this page is coded to automatically pull in these cards and the heading level is hard coded in the template. So let's take a look at that.

This listingcard. html template is the card that these bread cards are rendered with And all we have to do is come down here to this H3 and change that to an H2. Save that. Return to the browser Back to the live page, refresh, and the accessibility checker is happy now. Alright. This text has gotten a bit bigger, you may notice, but you can either live with that or make a simple tweak to the CSS to bring the text back down to the size that it was before, the

perhaps the designer's visually intended size. Now if we go to one of our blog pages, Great Icelantic Baking Show. We don't have an error here yet, but I will edit this page and create one for us. If we were to edit this page body, we have a stream field here, and what a to digress briefly, a stream field is a white-tail feature that lets you add any number of different kinds of content blocks to a page. such as the paragraph block and the image block that you see here. And there is also within that a heading block. So we can create a heading block and we're going to enter Heading level 3.

We get to choose the size. We can choose between H2, H3, and H4, and if we choose H3 and publish the page, You'll see that Whitetail has no problem with this by default, but if we refresh the live page We have our new heading here, and we now have an error in the accessibility checker. Incorrect heading hierarchy, avoid skipping levels. Right there. So we can easily remedy this by converting it to an H2 in the editor. But uh we might want to provide some help to art editors to realize that they shouldn't be doing this. So Whitel 5. 0 introduced some new ways to validate stream field blocks.

And I want to give a tip of the hat to Whitel core developer Matt Westcott for this feature. And using these, it's pretty simple to validate on save whether or not the headings in a stream field are in proper order. So let's return to VS Code and open our blocks. py file where this heading block is defined. And we first I want to show actually that we have this base stream block. This is what defines the stream field and the blocks that are available to it, the heading block, the paragraph block Image block, block quote, and an embed block. That's what we currently have. And if you look back up here at the heading block, this is where there's the heading text

sub block and the size subblock that set up our heading. Now In a pattern that may be familiar to you if you're experienced with Django, you can override the StreamBlock ParentClasses clean method that is used to try to validate the stream block on save, this base stream block here. Rather than write it on the fly, I will paste in some code that I've already written Right here. So now we have a new clean method. And uh what's going on here is that First, we start with the initial results of the default clean method.

And then I've got a headings list that we will loop through. in a moment. Actually first we we loop through all of the blocks in the result from the initial validation of the stream block and if a block that it finds is a heading block we want to get the level of that block and append that to this list of headings that we're building of all of the headings on the page And also note that I put in a a mock h1 block with index of zero because we don't have an h1 in the stream field, it's just coming from the title of the page.

Once we have our list of headings in this list here, then we can loop through that list. Compare, uh we start with the second heading in the list, so our first, in this case the H3 , Compare it to the previous settings level, which in this example is an H1, and if the difference is more than 1, then we can add a validation error to the errors array And then after going through all of the headings on the page, if we had any errors, we can raise the stream block validation error and display that to the editor. So save this and we'll take a look at it in action.

Gonna Go ahead and try to save this edit uh this page as a draft again and we'll see the Ah, and I've made this mistake before. Uh I forgot to import the new validation error classes. My apologies for that So we need to from Django Core Exceptions Import the basic validation error and for my tell blocks we need to import struct block sorry stream block validation error Save that and we'll try this

one more time And there we go. We now have our validation error appearing on the page. Incorrect heading hierarchy, avoid skipping levels. Now if I change this to an H2. Try to save again, we'll see that the error has gone away. I can also demonstrate that if we now add an H4 below that We'll get the same error for skipping from H two to H four. There you go. All right.

So heading hierarchy issues are sometimes the responsibility of developers like you, and sometimes the responsibility of editors, but in that latter situation, you can use custom validation to help them out. I demonstrated how it can be done for a heading block, which is not something that's baked into Wagtail but a common pattern. But the same approach could be applied to the built-in rich text block with headings enabled. You would inspect the rendered markup from the block, looping through the heading elements and doing the same sort of comparison as I did for our heading blocks. Whitel also has a rich text field, a standard Django model field that can be used to provide a rich text editor outside of a stream field. And in that situation you could subclass rich text

field and add your own custom clean method If you have a page that supports combinations of the above, you can override the page models clean method, looping through all of it, stream field, model field, whatever. to build a complete list of headings on the page and then checking out each one of those in succession Let's move out of the realm of issues that the accessibility checker will flag and onto a topic that always gets a lot of attention, alt text. If you're not familiar, Alt Text is a way to provide a textual alternative of an image to screen readers, not displayed visibly, so that people who cannot see the image can hear what it is depicting

This is done using the alt attribute on an image element. The key question to ask yourself when considering alt text for an image is what description of this image would be useful to someone who's hearing the page read aloud? And bear in mind that the answer may be none. Decorative images do not need alt text if hearing a description of them would not be useful. However, all image elements should have an alt attribute and it should be left empty if the image is decorative. You can find many articles on when and how to use alt text, but let's discuss how we can implement it in Wagtail. Whigtail has never had a field for alt

text in its default image model, but it will default to using an image's title for the alt text if you render an image with WhiteTel's standard image template tag. We know this isn't great because the title that you want to see in the admin interface may have no relation to what useful alt text would be for that image. In Whitel's early years, the standard advice was to use a custom image model instead of the default and add in your own field for alt text. along with other fields you might need on your images, such as caption or credit fields. More recently, we have determined that it's a good thing for there not to be an alt-text field on the image itself because

any given image may be used in multiple places on a site, and it's important that the alt text be relevant to the context the image is in. The context could be different from page to page, so having a single piece of alt text for an image would make it hard to write alt text that is suitable for any usage. You should probably still set up a custom image model when starting a new Wagtail project, even if you're not sure whether you need additional fields, because it's much harder to transition to one after real image content gets into the database. So, because we don't want to store alt text on the image itself, and because we want to override the automatic generation of alt

text from the image title, We need to set up a way to set alt text in each place an image is used. For Whittail Stream fields, this means that the best approach is to create a custom image block that incorporates an image chooser and an optional to alt text field. Now, you may have noticed earlier but the Bakery demo already has a custom image block in its stream field. Here's one on this blog post we've been dealing with. You can see that it has a caption and attribution fields already. And here's another look at how they render on the front end. If we inspect this image, you can see that the alt attribute is set to baking soda.

And uh that is also the title of this image in Wagtail One problem with this specific example is that screen readers are going to repeat themselves reading baking soda for the image alt and then immediately again for the caption that's visible here on the page. So let's add a dedicated alt field so that we can give this some some better alt text. Here again in our blocks. py file, we'll scroll down to the definition of the image block And under the image caption and attribution fields that we already have, we'll add a new one for alt text. So now it's going to be another character block.

And we want it to be required false because again we don't always need alt text. And then we just need to edit the block specific template here in image block. html. And here in this image tag we can pass in an alt attribute to override the default of the image title, and we'll set it to our new Alt text child block. Save that, switch back to the browser, go to the editor, Refresh that. We're gonna get our heading validation error again, but that's okay.

We can correct that And we see we now have our alt text field. Now we can put in something that would be better for a screen reader to read, something like a small porcelain bowl of baking soda with a card wooden scoop. That should do and we'll publish this. Ah, yeah, submit in the the validation error. Let's go ahead and correct that Try it again to publish. Alright, and if we refresh the page, we can see that our baking soda image now has the alt text that we gave it. Alright, so that is the primary alt

text recommendation I have for you. Ensure that you have a place to enter it alongside every Stream Field Image Chooser block. Hopefully this will get a bit easier in the future. Please keep an eye out for a proposal we have for a new contextual alt-text feature that would eliminate the need for developers to add their own alt-text fields. You could even comment on it. More enthusiasm from the community might help nudge it into existence more quickly. Our final major topic is on the subject of ARIA labels. ARIA stands for Accessible Rich Internet Applications and it's a set of HTML features. that define ways to make web content and web applications more accessible.

The landmarks that we discussed earlier are also a part of ARIA. Now consider the snippet shown here. It's an excerpt from a list of annual reports. For your average sighted user, it makes perfect sense to have the text of these links simply be download. Because the visual association with the report that they belong to will be readily apparent. But if you're a screen reader user and you're tabbing through all of the focusable elements on the page, you're going to get this list and all you're going to hear is download, download, download. Well download what? Imagine how frustrating that would be to not know what it's telling you to download. Fortunately, we can do something about it. We can use the aria

label attribute to change how a screen reader announces this link With that in place, instead of just reading download, it will instead say download 2023 annual report. This sort of repetitive link issue can crop up often. Other common examples include things like read more, or go, edit, and so on. So let's talk about some approaches to handling ARIA labels in Wagtail. To continue the example we just gave before. Let's say that you're building this list of annual reports using a Stream Fields list block, which lets you select any number of files from Wagtail's document library and list those on the page for download.

When declaring your download list block, if you assign a block-specific template and put this code in it, That will give you the Neat and Tidy Visual List while also automating the ARA label attribute to provide more context to screen readers. This kind of approach works fine when you you know exactly what the purpose of of the list block that you're building is and you can hard code that ARIA label helper in here like this. And that works in some situations, but in other situations we will need editors to be able to add ARIA labels to their own links. Unfortunately, when working with links in rich text fields, this is not yet possible. But for stream fields, we can again rely on a custom block setup to get this done.

Creating a link block is a rite of passage at this point for Wagtail developers. Everyone eventually wants this sort of block, where you can choose one of several kinds of link destinations. Enter your link text, and I'll put the resulting link markup. I borrowed this example from the Wagtail Docs page listed below, and it's got a required child block for the text of your link And it's got optional child blocks for either choosing an internal page or entering an external URL. You might also want to consider options for linking to a document in Yytel's document library, email links, or anchor links. These link blocks could get you know pretty fancy with all of that stuff included.

I've also added an ARIA label child block where editors can enter that if their link warrants it. Then in our linkblock. html template, we can conditionally output the ARIA label attribute if that field has been populated. How can we help editors know if an ARIA label is needed, though? The answer again is custom validation. You can override the clean method on your link block to check enter link text against a list of generic link text that would be unhelpful to hear on its own, things like read more and the others I listed earlier. and throw an error if the ARIA label field hasn't also been filled in. Let's take a look at that.

Alright. Here again in our blockstopy file, I'll paste in the link block code that I've already prepared. I'm gonna put it toward the end here, right before the V stream block And uh what you can see is that we have the text page external URL and RA label triad blocks that I uh I showed earlier. And then we have this custom clean method. We start by again running the basic clean on this struct block and then we I give it a generic link text list of all the things that we want to be looking out for.

And then we have a check for two things. First we make sure that the ARIA label field has not been filled in yet. And then we look to see if the entered link text is found in our list of generic link text. And if both of those things are true, we want to raise this validation error that the entered link text is very generic. Please add a more descriptive RA label for screen readers. Actually I didn't say please because I want to be very firm about it. Now before we run this, I need to remember to copy in some new imports And we also need to add the link block to our

stream field so that it can actually be used Alright, save that. Return to our editor and reload the page And now within our body stream field we can add a link block. I'll go ahead and Type in something you know something bad and generic from our list like read more and I won't enter select a page or enter URL because I don't really need to, but I also definitely will not enter an ARIA label And now if I try to save this, we have a validation error.

Enter link text is very generic. Alright, so we'll enter something. Like read more about Whittail. Try to save it again. And this time the uh we have success. Now this kind of thing cannot prevent an editor from from entering a bad ARA label, but hopefully it will at least prompt them to pause and think about it. But even so, we could give them a little more guidance So the last subject I want to cover today is about providing timely help to editors as they are editing their page to help them catch accessibility errors before the checker or an actual human reports them.

Something you may have noticed as I was going through my earlier examples, especially if you were familiar with Django, is that I didn't include any help text Help underscore text, the classic uh Django attribute, which is a built-in way to provide hints about a given field to the user as they are editing. This was due in part to space constraints and the desire to keep the text large enough to be readable, but normally I'm a huge fan of help text, so let's go back and take a look at what we could have done. Looking back at the heading block, here is an example of the kind of help text that I would add to its size field, its size subblock. Note that you can use Django's MarkSafe utility to be able to include HTML in your help text, which is useful for linking to more detailed guidance.

So I've said please ensure that you do not skip heading levels. For example, the next heading after an H2 should only be either an H3 or another H2. and then provided a link that uh the MarkSafe will render. And here's what that the result of that in the editor. We have that text appearing right here between the heading of the field and the actual widget for it Now returning to the image block, here's an example of the kind of help text that I would add to its alt text field. If this image is not purely decorative, Enter a text alternative to be displayed if images fail to load or uh or to be read by screen reader software.

And we again we have a reference link. And here's the result of that in the editor. And finally, looking again at the link block, here's an example of the kind of help text that I would use for its ARA label field. If your link text is generic, like read more or download, enter something more descriptive to be read by screen readers instead, like read more about our commitment to accessibility, and again a reference link. And here is the result of that in the editor. One other thing that you can do if you're looking to give editors some guidance at the page level rather than the individual field level

is to add a help panel. I won't go too deep into explaining why tail editor panels, but in short, a help panel has no fields for content entry. It simply lets you define any arbitrary HTML to display to your editors. And so you could use this, for example, as a cleaner alternative to having help text on every image's alt text field on an image heavy page type. Check out this link at the bottom to the White Hill docs for more on how to use the help panel. Alright, to wrap things up, let's recap my recommendations for you, potential Wagtail developer. Number one, use semantic markup and templates.

2. Configure Wytail's accessibility checker to show developers all errors. 3. Enforce proper heading hierarchy through the use of custom validation. 4. Add alt text fields and promote better alt text. 5. Add aria label fields and educate editors on when to use them. And finally provide timely help to editors as they work on their content. To learn more about making a Wagtail site as accessible as possible, I strongly recommend that you check out this page in the Wagtail docs. In addition to specific technique recommendations like the ones I've given, it also has a list of links to other great resources if you want to learn even more about

web accessibility. Thank you very much for watching. I hope you're inspired to make some changes to help your Wagtail sites be more accessible. And you can find these slides and code examples at github. com slash Scotchester. slash DjangoCon dash Wagtail dash accessibility. I don't do Twitter anymore and haven't taken the Mastodon plunge yet, but if you have questions, the best place to connect with me would be on the DjangoCon or Wagtail Slack workspaces. Or find me in the hall if you're here in Durham. Hope you enjoy the rest of DjangoCon. Thanks again.