Hi Team, we are looking for a11y in our application. We got to know GoJS 3.x providing accessibility support. I need help with that.
Thanks
I assume you meant upgrading to GoJS version 3, from a previous version.
The WCAG guidelines are meant for developers like you to make web pages/apps more perceivable, operable, understandable and robust.
That is not something that any diagramming component can provide out-of-the-box because implementing those guidelines should be different for each app. Only you know what it is that your diagram is really showing and how it should really be used.
So the Accessibility sample is just an example of the start of accessibility support. Your app will need custom behaviors to best help users understand and use your diagram, depending on the semantic relationships that the diagram presents and the information provided by the nodes and links and groups.
Hi, @walter We are looking to explore a11y for loops nodes, links & interactive elements(context menu). Does gojs(v3.x) a11y supports by default navigations for those?
No â again, what you would want to do would depend on the semantics of your diagram/graph.
Okay. But we have a usecase where we must navigate to inner html/node/interactive elements. As shown in the picture below, if we add a11y, we can navigate between the nodes(which is highlighted in the pictureâs last row) but our usecase is to navigate within the node ex: to email, phone which are interactive elements in a node. How can we achieve this using gojs a11y?
You would need to write custom code to do it. Probably you donât want to iterate over the Nodeâs GraphObjects themselves, but use the Node data in some meaningful way.
As a basic example, maybe you want to output information about the node somehow when a user presses a key like âxâ:
myDiagram.commandHandler.doKeyDown = function () {
// method override must be function, not =>
const diagram = this.diagram;
const e = diagram.lastInput;
const k = e.commandKey;
if (k === 'x' && diagram.selection.count !== 0) {
// do something with the node data
const data = diagram.selection.first().data;
console.log(`the Node's key is ${data.key}`);
console.log(`the Node's color is ${data.color}`);
// or any other data.property
} else {
go.CommandHandler.prototype.doKeyDown.call(this);
}
};
This is close to what the Accessibility sample does, except that sample describes surrounding nodes instead of the node itself. But thereâs no reason you cannot modify it or add to it to describe the node itself. (Note this sample also uses the letter x for something already)
In the case of the org chart sample, youâd want to look at data.name, data.dept etc. These (whichever are relevant) are specific to your app.
@simon Do these code changes need v3.x upgradation? or can we do it with v2.x itself?
These particular customizations can be done with 2.3.x versions, at least.
Okay. What will we get in terms of a11y if we upgrade to 3.x? Currently, we have customized accessibility but we are facing focus issues. Undo/Redo/Delete is not working as the focus is shifting from diagram to node.
Itâs difficult to know precisely what changes will be in your app, there are a number of new features which may or may not be relevant to you. From our point of view its always good to update to the latest major version so that if you do encounter a bug, we can fix it (or at least be sure it hasnât already been fixed).
In terms of a11y we may have made minor changes to the library in order to create our accessibility sample, but I cannot recall any. So you probably donât need to update.
You may want to review all changes:
Okay. Currently, we are implementing a11y using hidden buttons & navigating accordingly. Due to the hidden button, the focus is shifting from the diagram/canvas to the hidden buttons. Can we get rid of the usage of hidden buttons & use **myDiagram.commandHandler.doKeyDown = function () {
// method override must be function, not => ** to implement custom a11y @simon ??
Could you please describe more precisely and thoroughly exactly what functionality you want to implement in your app in order to replace the use of the mouse/finger? It would help a lot if you provided screenshots showing before and after for each input event.
We are looking for a11y for group nodes & interactive elements.
As shown below, the image:
Can we achieve this using an a11y extension ?? At least by overriding the existing functionality provided as part of AriaCommandHandler ?
Yes, I believe so. But it isnât clear to me exactly what keyboard commands you would want to implement, nor what kind of highlighting you want to do. Thatâs why I was asking for a more detailed description of the keyboard input events.
But the general answer is âyesâ, by implementing various keyboard commands whose behavior is dependent on the current state of the navigation and of the diagram.
@walter We want Arrow Keys for our scenario & we are looking for navigating groups, nested nodes & and interactive elements i.e. ContextMenu.
I recommend copying the extension into your own project and modifying it to suit your needs, as we recommend for any of the extensions which one might use that need customization.
Thanks for the confirmation @walter
We have a few questions on how A11Y works with the extension:
Query
One more question. How can I iterate through a GraphObject/Interactive Elements?
As shown in the below image if I gave findSubGraphParts() on the Group node itâs giving me only nodes & links but not any GraphObject/Interactive elements(In our image its expand/collapse icon)
First, please understand that âaccessibilityâ isnât an entity with agency. Itâs a characteristic of an app, not something that does something.
Second, I hope you see now why the concept of accessibility must be tailored for each specific app. The code that we supply cannot know which node you want users to start from, nor which nodes you want users to go to next, nor which non-Node & non-Link (i.e. non-Part) objects to be able to navigate to.
There might be any number of buttons in your Node (or in your Link!), but we canât know what you want to be able to navigate to and in what order and under what circumstances. In your case, when the user is focusing on the âZetaâ Group, which command should change focus to the âEtaâ Node, which command should change focus to the âSubGraphExpanderButtonâ, which command should change focus to which Node that follows âZetaâ? And might users want to focus on the Links?
So use the Accessibility sample just as a framework for defining the behavior that you want in order to support accessibility for your users. I recommend that you either accept or reject each bit of functionality that it offers.
We have a scenario where we must implement custom a11y for our diagram. We do have a snippet to navigate via links & nodes. However, we need to extend it further for interactive elements/graph objects that are part of a Node. Once we reach the interactive graph object we need to open a context menu kind of model & further traverse.
What we are doing in the below code is once the user presses the arrow down/up we are navigating from each node & link recursively (further in a Node we have interactive elements data which is used to find the graph object using findObject() ) adding it to wcagEntities array & doing necessary changes for navigating to each part.
Issue
Here is the diagram screen:
Can you help further on how to proceed ??
import triggerMouseEnter from 'src/utils/trigger-mouse-enter';
import triggerClick from 'src/utils/trigger-click';
function getListOfPartsForKeyboardNavigation(diagram) {
// Start with root nodes - those who do not have parents
let startNodes = diagram.findTreeRoots();
// If startNodes is empty, it's a cycle. Grab the first visible node.
if (startNodes.count === 0) {
const firstNode = diagram.nodes.filter(node => node.isVisible()).first();
if (firstNode)
startNodes = new go.List().add(firstNode).iterator;
}
/** @type {go.Part[]} */
const result = [];
/** @param {go.Node} node */
const traverseGraphForWcag = (node) => {
if (result.includes(node))
return;
result.push(node);
node.data?.interactiveGraphObjects[0] ? result.push(node.diagram.findNodeForKey(node.data.key).findObject(node.data?.interactiveGraphObjects[0]?.name)) : "";
/** @type {go.List<go.Node>} */
const nodesToTraverseFurther = new go.List();
node.findLinksOutOf().each((link) => {
if (link.isVisible() && link.toNode) {
if (result.includes(link))
return;
link.data?.interactiveGraphObjects ? result.push(link.diagram.findPartForKey(formLinkKey(link.data)).findObject(link.data?.interactiveGraphObjects[0].name)) : "";
nodesToTraverseFurther.push(link.toNode);
}
});
nodesToTraverseFurther.each(traverseGraphForWcag);
};
startNodes.each(traverseGraphForWcag);
return result;
}
export class CustomGraphKeyboardHandler extends go.CommandHandler {
constructor() {
super();
}
/**
* This implements custom behaviors for arrow key keyboard events.
*/
doKeyDown() {
const diagram = this.diagram;
const e = diagram.lastInput;
// Determine the function of the arrow keys
if (e.key === 'Up' || e.key === 'Down' || e.key === 'Left' || e.key === 'Right') {
const wcagEntities = getListOfPartsForKeyboardNavigation(diagram);
const selectedPart = diagram.selection.first();
const selectedIndex = selectedPart ? wcagEntities.indexOf(selectedPart) : -1;
let nextIndex = selectedIndex;
if (e.key === 'Down' || e.key === 'Right') {
nextIndex++;
if (nextIndex >= wcagEntities.length)
nextIndex = 0;
}
if (e.key === 'Up' || e.key === 'Left') {
nextIndex--;
if (nextIndex < 0)
nextIndex = wcagEntities.length - 1;
}
const nextEntitySelect = wcagEntities[nextIndex];
if(!nextEntitySelect.data){
triggerMouseEnter(nextEntitySelect,diagram);
//nextIndex++;
triggerClick(nextEntitySelect,diagram);
}else{
diagram.select(nextEntitySelect);
}
e.handled = true;
return;
}
// Handle ENTER and SPACE key
if (e.key === '\r' || e.key === ' ') {
const selectedPart = diagram.selection.first();
if (selectedPart && selectedPart.click) {
selectedPart.click(e, selectedPart);
e.handled = true;
}
}
// Otherwise still perform all standard commands
super.doKeyDown();
}
}
Itâs hard for us to give good advice when we do not know all of the goals and constraints that you have for the functionality that you want to users to access.
For each GraphObject that you might want the user to focus on, imagine all of the information that you want to show and all of the next steps that they could take.
Youâll want there to be an abstract notion of focus that indicates which GraphObject has the âfocusâ and provides the information to be communicated and which commands apply for further navigation or actions. The GraphObject might be a Part (such as a Node or a Link or an Adornment), or it could be a GraphObject within such a Part (such as a âButtonâ or other GraphObject acting as a control of some sort).
Of course only you know what information to provide about each object of focus, and only you know what all of the commands might apply to that focus object â which navigation commands and which action commands.
For any focus object, including Parts, there could be GraphObject.click or doubleClick event handlers that you could invoke, as well as maybe showing its contextMenu or toolTip.
For any Node, there are a bunch of properties and methods that you can use to determine its relationship with connected Links and connected Nodes.
If you app is tree-structured, there are various properties and methods on the Node class to deal with trees.
If your app has Groups, you can find a Groupâs contained Nodes and Links via the Group.memberParts property. And for any Part, use its Part.containingGroup to find what itâs a member of, if anything.
For any Link, there are a bunch of properties and methods that you can use to determine its relationship with Nodes. That includes Link.fromNode and toNode, but also fromPort and toPort if node might have more than one port per node.
I donât know if this applies to your app, but a Link can also contain Nodes, Link.labelNodes, for attaching Links to Links. Your app probably does not use this feature.
Adornments are Parts, so a context menu or a tooltip (if implemented in GoJS rather than in HTML), or any GraphObject within it, would also be a valid focus object.