Add aria labels to PGML and unify their use. by somiaj · Pull Request #1493 · openwebwork/pg

somiaj · 2026-08-09T00:52:44Z

Update the generate_aria_label method to be given an input label. If the input label is defined and doesn't contain %s, return the label. If the input label is undefined (or blank) generate a default label based on the problem number, answer number, and part number. If the input label contains %s, replace it with the default generated label and return the result.

Update answer rules to more uniformly accept the aria_label option and use the generate_aria_label method. This required updating some and adding the option to others.

Update macros that use the generate_aria_label method to take advantage of the new method. The parserRadioButtons and parserCheckboxList will append "option X" to the end of the generated label. Matrix arrays will append "col N row M" to the end of the generated label.

Update PGML to accept the aria_label option in answer blanks to customize the label, "[_]{$answer}{aria_label => '%s label'}".

The biggest change was in parserRadioMultiAnswer which allows a new option ariaLabels which is the labels to send to the associated answer rules. Update its internal generate_aria_label function to match the changes to the one in PGbasicmacros. In addition the "subpart X" is only added to the label if there are more than one subparts, and the "part Y" will use the label of the part if displayLabels is set, otherwise it uses the number of the part.

This is a more general approach and replacement of #1489. Due to the discussion I am calling the option aria_label to match what was already in the code, label is not a correct name, and accessibility_label is just longer and would require making the code better deal with that. aria_label was already in use and is now just being used more uniformly. aria_label can be used in PGML or sent directly to various ans_rule or ans_array calls.

I went with @dpvc suggestion of allowing a single %s sprintf option to include the default generated label as part of the custom label. To not get any errors from sprintf, I went with just regex find/replace of the first instance of %s in the string.

Here is a problem I was using to test various different checkers and macros. Edit it to remove the aria_label option to check out default generated labels or remove %s to see any effects.

DOCUMENT();
loadMacros(qw(
    PGstandard.pl
    PGML.pl
    parserMultiAnswer.pl
    parserPopUp.pl
    parserRadioMultiAnswer.pl
    parserCheckboxList.pl
    parserRadioButtons.pl
    PGcourse.pl
));
Context('Matrix');
$f     = Compute("7x - 5");
$ma    = MultiAnswer("x + 2", "2x - 3")->with(singleResult => 1);
$M     = Matrix([ [ 2, 0, -3 ], [ -4, -3, -2 ] ]);
$popup = DropDown([ A .. F ], 2, useHTMLSelect => 0);
$rma   = RadioMultiAnswer(
    [
        [ 'Matrix %s*',       Matrix([ [ 0, 1 ], [ 2, 3 ] ]) ],
        [ 'Formula %s',       Formula('x+1') ],
        [ 'Number %s and %s', Compute(5), Compute(-7) ],
        ['No Input']
    ],
    2,
    ariaLabels =>
        [ '%s Matrix', '%s Formula %s', '%s Number1', '%s Number2' ]
);
$checks  = CheckboxList([ A .. F ], [ 2, 5 ]);
$buttons = RadioButtons([ A .. F ], 4);

BEGIN_PGML
[_]{$f}{aria_label => '%s %s function %s'}

[_]{$ma}{aria_label => '%s left hand side'} [`=`] [_]*{$ma}{aria_label => 'right hand side'}

[_]*{$M}{aria_label => '%s augmented matrix'}

[_]{$popup}{aria_label => '%s letter of graph'}

[_]{$rma}{aria_label => '%s radio multi answer'}

[_]{$checks}{aria_label => '%s checkbox list'}

[_]{$buttons}{aria_label => '%s radio buttons'}
END_PGML
ENDDOCUMENT();

somiaj · 2026-08-09T00:58:45Z

@drgrice1 One thing I was unsure about was parserPopUp when the useHTMLSelect => 0 would create an empty visually hidden span that contained the aria_label. I assuming it was correct, but feels weird that the label doesn't wrap the full popup menu being generated.

somiaj · 2026-08-25T21:31:28Z

I added @Alex-Jordan suggestion, PGML can now use [_aria label_] to set a custom label. Follow the same labeling rules as before, so [_%s my custom answer_] will replace %s with the generated label.

I made this its own commit to easily remove.

drgrice1 · 2026-09-07T11:20:28Z

@drgrice1 One thing I was unsure about was parserPopUp when the useHTMLSelect => 0 would create an empty visually hidden span that contained the aria_label. I assuming it was correct, but feels weird that the label doesn't wrap the full popup menu being generated.

That doesn't even make sense and wouldn't work. If the visually hidden span wrapped the popup menu, then the popup menu would also be visually hidden.

somiaj · 2026-09-07T16:51:50Z

Right, if the span did wrap the drop down, it shouldn't be visually hidden. I was just confused because the label is just by itself, <span class="visually-hidden" aria-label="answer 2 "></span>, and it isn't clear to me how this actually applies the label to the drop down button that follows it. Though I guess labels don't apply to children elements too, so why isn't this label just applied to the drop down button? Anyways, it was more just I didn't understand why it was sufficient to label this visually hidden element vs the button that is used for the drop down.

drgrice1 · 2026-09-07T19:50:54Z

There was some discussion on that in #1159. It was about getting the screen reader to announce the right thing when the dropdown menu is open.

Update the `generate_aria_label` method to be given an input label. If the input label is defined and doesn't contain `%s`, return the label. If the input label is undefined (or blank) generate a default label based on the problem number, answer number, and part number. If the input label contains `%s`, replace it with the default generated label and return the result. Update answer rules to more uniformly accept the `aria_label` option and use the `generate_aria_label` method. This required updating some and adding the option to others. Update macros that use the `generate_aria_label` method to take advantage of the new method. The parserRadioButtons and parserCheckboxList will append "option X" to the end of the generated label. Matrix arrays will append "col N row M" to the end of the generated label. Update PGML to accept the `aria_label` option in answer blanks to customize the label, "[_]{$answer}{aria_label => '%s label'}". The biggest change was in parserRadioMultiAnswer which allows a new option `ariaLabels` which is the labels to send to the associated answer rules. Update its internal `generate_aria_label` function to match the changes to the one in PGbasicmacros. In addition the "subpart X" is only added to the label if there are more than one subparts, and the "part Y" will use the label of the part if `displayLabels` is set, otherwise it uses the number of the part.

drgrice1 · 2026-09-17T11:39:25Z

-	foreach my $i (0 .. $#choices) {
-		my $value = $self->{values}[$i];
-		my $tag   = $choices[$i];
+	my $label = main::generate_aria_label($name, delete $options{aria_label});


This is adding aria labels back to parserRadioButtons.pl answers. These were just removed a release or two ago. That is because these should not have an aria label when they already have an actual visible label. See #1224.

Ahh, I should have looked deeper as to why these were not present. It did feel odd they were not there, and I now see that in parserRaidoMultianswer, the aria labels are added to the additional inputs but not the actual radio select buttons.

Would it be worth adding a label to the radio-buttons-container or checkbox-container so there could be a label for the whole radio/checkbox select stating either what problem it is or allowing users to label?

The problem author sets the text which is the label. I think that the author can also always add a statement before the radio or check container that is for everyone to see. So I would say not to an aria label on those.

Okay removed that here and the other place you noted that was incorrect. Though there is still a small change with the code cleanups I did. I can remove those changes if you prefer.

I also noticed that NAMED_ANS_RADIO_BUTTONS was still using aria_label, but then passed it to a method that didn't use them, so I cleaned up that method to also no longer have that unneeded logic.

drgrice1 · 2026-09-17T11:52:47Z

+				name       => $name,
+				id         => $name,
+				value      => $value,
+				aria_label => generate_aria_label($name, $options{aria_label}),


This also was removed in #1224, and should not be added back. The same for line 492 below.

This adds being able to parse the aria label from the PGML answer blank directly using `[_aria label_]`.

somiaj marked this pull request as draft August 9, 2026 00:52

somiaj mentioned this pull request Aug 9, 2026

Add ansLabels option to parserMultiAnswer. #1489

Closed

somiaj force-pushed the aria_labels branch 2 times, most recently from c9c5189 to f0b699a Compare August 13, 2026 21:04

drgrice1 reviewed Aug 14, 2026

View reviewed changes

Comment thread macros/core/PGbasicmacros.pl Outdated

somiaj force-pushed the aria_labels branch 5 times, most recently from a89d1b7 to 42c7f4a Compare August 18, 2026 21:26

somiaj force-pushed the aria_labels branch from 42c7f4a to a4739cd Compare August 25, 2026 21:29

somiaj force-pushed the aria_labels branch 2 times, most recently from 1f2d1eb to e36d6e4 Compare September 1, 2026 20:58

somiaj force-pushed the aria_labels branch from e36d6e4 to 17824a6 Compare September 7, 2026 16:41

somiaj force-pushed the aria_labels branch from 17824a6 to 75ca95e Compare September 7, 2026 17:16

somiaj force-pushed the aria_labels branch 2 times, most recently from 218074f to b279f53 Compare September 9, 2026 14:05

somiaj force-pushed the aria_labels branch from b279f53 to ac193fe Compare September 15, 2026 20:04

drgrice1 reviewed Sep 17, 2026

View reviewed changes

Add aria label to PGML answer blanks.

afd588d

This adds being able to parse the aria label from the PGML answer blank directly using `[_aria label_]`.

somiaj force-pushed the aria_labels branch from ac193fe to afd588d Compare September 17, 2026 17:31

Navigation Menu

Uh oh!

Add aria labels to PGML and unify their use. - #1493

Add aria labels to PGML and unify their use.#1493
somiaj wants to merge 2 commits into
openwebwork:developfrom
somiaj:aria_labels

somiaj commented Aug 9, 2026

Uh oh!

somiaj commented Aug 9, 2026

Uh oh!

Uh oh!

somiaj commented Aug 25, 2026 •

edited

Loading

Uh oh!

drgrice1 commented Sep 7, 2026

Uh oh!

somiaj commented Sep 7, 2026

Uh oh!

drgrice1 commented Sep 7, 2026

Uh oh!

drgrice1 Sep 17, 2026

Uh oh!

somiaj Sep 17, 2026

Uh oh!

drgrice1 Sep 17, 2026

Uh oh!

somiaj Sep 17, 2026

Uh oh!

drgrice1 Sep 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

somiaj commented Aug 9, 2026

Uh oh!

somiaj commented Aug 9, 2026

Uh oh!

Uh oh!

somiaj commented Aug 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

drgrice1 commented Sep 7, 2026

Uh oh!

somiaj commented Sep 7, 2026

Uh oh!

drgrice1 commented Sep 7, 2026

Uh oh!

drgrice1 Sep 17, 2026

Choose a reason for hiding this comment

Uh oh!

somiaj Sep 17, 2026

Choose a reason for hiding this comment

Uh oh!

drgrice1 Sep 17, 2026

Choose a reason for hiding this comment

Uh oh!

somiaj Sep 17, 2026

Choose a reason for hiding this comment

Uh oh!

drgrice1 Sep 17, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

somiaj commented Aug 25, 2026 •

edited

Loading