WCAG Compliance, patching standard UI5 controls without using extensions
Accessibility, WCAG, UI5….
If you’re reading this blog, you probably already know the painful reality that a lot of the standard controls in SAPUI5 are not very accessible, by no fault of your own, they simply do not render accessible html in some cases. As of the time of writing this, the latest version 1.73.1 has brought many much needed and welcome improvements to accessibility, but there’s still some lingering issues that we have no choice but to address ourselves for the time being.
In the past, I’ve used and advocated control extensions to fix WCAG issues (using the onAfterRendering function to make DOM corrections). This means you just swap out any given control with your own wrapped version. But this itself becomes very tedious to implement in all your views.
Recently, Bradley and myself pondered whether we could achieve the same sort of patching of controls, but without the use of extensions, so that nothing needed to be changed in an existing app to bring up its compliance level. We wanted WCAG patches to be applied to an app with a single line of code, and well… we achieved that goal!
We’ve developed a small wcagHelper library, that when loaded, automatically detects and patches each control in your app as they’re instantiated. So for example you can just use a standard sap.m.CheckBox in your views and the library will automatically append additional onAfterRendering logic to it to correct its aria tags. It does this by monitoring changes to the DOM, and tracing those elements back to UI5 controls.
In this blog I’ll be using the WAVE tool for chrome for WCAG testing (you should also use aXe). At the time of writing this we have only implemented a handful of WCAG fixes, but the pattern is simple, so you should have no trouble adding any and all corrections that you may need. We also found that a lot of our past corrections are no longer required in the latest version 1.73.1 so thankfully there’s A LOT of code we didn’t need to port over to this library from our previous projects.
So here’s some very simple UI5 XML, in version 1.73.1, as an example of a few aria tagging faults.
It renders like so…
Which appears to be fine visually, but when we run a tool such as WAVE for chrome, we can see a few issues.
Each of those orange and red icons are warnings and errors, most of these are issues with aria tags, for accessibility tools to work correctly they need to know which labels are associated with which input controls. By default these are not being placed correctly in the DOM. in the case of the select control a label element is being used to show content when a span is appropriate for that case.
So as previously mentioned, I would normally fix these issues by writing control extensions, and using those extensions instead of the default controls. But with the wcagHelper library, I instead, only need to load the library, and it will patch the controls as needed.
I do this in the component.js of my application. Note that your path (second parameter) may be different, depending on where you’ve placed the wcagHelper folder in your environment. But the proper use of libraries in UI5 is a whole separate topic.
As you can see, I even put this above my component definition itself, it’s the first thing that’s done. Technically it can go anywhere, but I like it to be right at the top so I can clearly see my dependencies.
Now that our library is loaded, I can run WAVE again, and see the improvements (NOTE: Nothing else has changed, the xml view remains unchanged)
Well well well, would you look at that. the errors and warnings are gone and everything appears to be labelled correctly. (the green icons of wave represent correct label tagging)
So now, patching for WCAG issues, is as simple as importing the library, and any additional improvements we make to the library along the way, will automatically apply to every view in every app that is using it!
The only way this could be better is if it just worked out-of-the-box 😉
We can also confirm that the library is working, by checking the browser console, where each control type will be mentioned like so
How it works
So I guess I should explain a little bit more, how the library achieves this.
The project structure looks like this…
The manifest.json and library.js are pretty standard looking library definitions. The other js files, are all global objects, most important is the UIMonitor.js, which listens for changes to the DOM, it is with this technique that we avoid having to make any changes to the views, as we can simply detect each control as it’s instantiated.
NOTE: Internet Explorer 9 and lower, will not execute the DOMNodeInserted event correctly, so if you absolutely need to support those “browsers” then I have bad news for you…
As you can see from the above, once a new control is detected, the patchControl function is called for it, which will find and apply the appropriate patches for that control type, which is where the files within the ControlPatches folder come into play. Each of these contain an onAfterRendering function, which will be attached to the control. For a patch class to be used, it needs to be listed I nthe UICatalog.js file.
Lets take a look at the select control for example
We can see that we have an entry in our UICatalog for sap.m.Select
Because there is an entry for this control, the ControlPatches/Select.js file will be loaded, which contains an onAfterRendering function
This onAfterRendering function, will be attached to every sap.m.Select control, so that during the render lifecycle, this code will run. In the case of our select control we are doing a simple element replacement, switching out the label element for a span element. The fixes here can be anything you need, just be sure to always use this.$() object when making DOM adjustments, to ensure you are only modifying within the context of the current control (this is no different to how you would do it within a control extension)
And that’s basically it, any control that needs a patch, gets a patcher class and an entry in the catalog, and that’s it!
Download & Contribute
You can find the full source of community.wcagHelper on GitHub:
Hopefully by the time you’re reading this there’s even more patches available. If there’s more simple DOM changes that you know of, that should be applied, then I encourage you to not only add them in for yourself, but to submit them to the GitHub live copy for the wider community, accessibility is a community problem, but as a community, we can solve it.
Bradley co-developed this library with me, he has some great blogs on Hana development, which you should definitely check out. He also wrote a chrome extension for detecting deprecated UI5 controls, very useful during landscape upgrades.
Interesting approach you are describing here to get around your accessibility issues. It might be used as a workaround on a short term basis, but I would not recommend this for productive use. Manipulating controls this way can have unforeseen effects as some control functions may rely on its exact (non-manipulated) structure or attributes and therefore this is evaluated as modification. Your library expects a fixed structure on DOM level, which is not an API and can change anytime without a notice. So whenever you upgrade your UI5 version your app can break.
In addition, with the new semantic rendering, we are patching directly the DOM and onAfterRendering is not always called. So, your library might not always patch or have side effects on controls already converted to the new rendering.
A much better approach is to report any accessibility issue you are facing within the UI5 framework back to the UI5 team, either by opening a support ticket or alternatively – in case the control is part of OpenUI5 – via GitHub. In the latter you could even contribute back by providing the fix and speed up things ?
This way everybody using UI5 can benefit without any additional work or further notice and without losing support.
Accessibility is an SAP Product Standard and we take this topic very seriously. As we’re committed to provide accessible software you can be sure that any accessibility issue being reported will be carefully examined and processed. Also when you check the UI5 roadmap you can see that we constantly invest into this topic to keep on track with latest regulations.
In your blog post you wrote you examined in several controls accessibility issues. As accessibility in UI5 controls is in my area of responsibility I would be more than happy to discuss your findings in more detail. Just ping me or let me know how to get in contact with you best.
I completely agree and acknowledge that having the fixes applied directly to the SAPUI5 library is preferable, but this takes a great deal of time, and clients require an immediate outcome, especially when they have customers (and even staff on site) with accessibility needs.
Thanks for the roadmap, it is great to see that accessibility is receiving much needed attention in 2020. What would be really great to see as part of this, is a commitment from SAP to meet the international WCAG AA and eventually AAA standards which our clients software must adhere to.
Yes some controls do not follow the render lifecycle, and while it isn't mentioned in this blog, the library handles these with an 'onPatched' function where additional hooks can be added for special cases. This is already typical for container controls like forms and tables, sounds like this will become a more common occurrence in future, but hopefully by that time, we won't need as many (if any) patches.
During an upgrade, of course things can change, thorough regression testing is always important during any upgrade, and especially when patching a control. It is sad to read that you would consider this modification and retract support over such a light-touch approach, as this creates further tension on client sites where issues like this (especially WCAG compliance) are already causing clients to reconsider their use of SAP products.
Check this page on SAP Software Accessibility:
“SAP takes pride in its diverse workforce. To foster a global culture of inclusion, we are strongly committed to respecting and protecting human rights throughout the lifecycle of our products and services: from design through development to use. Hence, our products are increasingly guided by the Web Content Accessibility Guidelines 2.0 (WCAG) and the US Section 508.”
This also involves SAPUI5, so I believe customers benefits the most when any accessibility issue is reported back to SAP so this can be fixed in the standard solution.
I can understand that timelines in customer projects are sometimes challenging and can lead to some project-based solutions. But I believe also any customer would prefer to get back to standard as close as possible.
That is where the beauty in the solution lies, remove one line of code, you are back to standard. when the standard library catches up, you can remove the patch.
could you please elaborate a bit on the user impact of the WCAG issues detected by WASP? Does the end user experience any difference with and without using your solution?
Hi Phillip, As agreed I have added your blog to the SAP Fiori Accessibility Wiki
I think it would be helpful for people reading this blog to understand a little of the history.
As I understand it from our conversation yesterday, your initial comment “the painful reality that a lot of the standard controls in SAPUI5 are not very accessible” was based partly on your experiences with SAPUI5 1.38 – which is admittedly very early in the SAPUI5 accessibility journey.
As you also state, things are much better now, around 4 years later with SAPUI5 1.73.
Even so it’s a continuing journey.
To give a little history & set expectations for those not able to get to the latest SAPUI5 level… I offer a brief personal history from my perspective as someone who has been dealing in this area for the last 5 years (this is not an official list by any means).
This is by no means the end of the story!
Accessibility as you well know is something of a moving target, with standards being updated (WCAG 2.0 -> WCAG 2.1, ARIA 1.0 -> ARIA 1.1), accessibility software versions being updated (JAWS, NVDA), new technologies and tooling coming into play (e.g. native accessibility capabilities in tablets, and phones) to name just a few of the challenges.
And of course even accessibility validation tools are themselves software and subject to the same challenges of new versions, limitations and bugs.
Plus as we create new SAPUI5 controls, and as we see new combinations of controls used for different patterns, and create new floorplans, new challenges emerge and need to be overcome.
So accessibility and accessibility conformance is very much a continuing journey for all of us, and we welcome contributions like this and experiences at customers that help us all move forward.
Thanks for sharing!
Thank you very much for highlighting the issues and providing a solution? Is there a more recent VPAT available for SAPUI5 1.73. since the one from 2015? Why can SAP not outsource the testing to an open group of differently-abled users?