Page MenuHomePhabricator

Add help text to Special:Block for Partial Blocks
Closed, ResolvedPublic3 Story Points

Description

We want to explain partial blocks directly on Special:Block


Rough mockup

Please note that the spacing is incorrect, this is a MS Paint edit job :)


Acceptance criteria
  • Add help text under the 'Sitewide' radio button
  • Add help under the 'Partial' radio button
  • Learn more. should point to Special:MyLanguage/Help:Blocking_users

Copy / Strings
  • Sitewide: Every page on the wiki and all other contribution actions.
  • Partial: Specific pages or namespaces. Learn more.

Event Timeline

TBolliger triaged this task as Medium priority.Jan 7 2019, 5:28 PM
TBolliger created this task.

We should also consider where our solution appears: on wikis with Partial Block enabled or on all wikis

TBolliger renamed this task from Solve for tooltips on Special:Block to Solve for tooltips on Special:Block (aka product orientation).Jan 8 2019, 12:45 AM
Prtksxna updated the task description. (Show Details)Jan 9 2019, 9:27 AM

@Tchanders from your previous comment I understand that its going to be tricky to add help text (tooltip, or inline) on the radio options. I wanted to ask if its going to be possible at all, or should we be thinking of other solutions?

If it is possible we could make our help labels more concise and add links in them for those who need to find out more.

I'll let Thalia comment with the ease of adding tooltips, but in F27812901 she showed what they would look like if we were to use the existing copy.

I think a valid solution could be to have one brief tooltip with a link to a help page, but that's your call @Prtksxna. :)

Tchanders added a comment.EditedJan 23 2019, 12:15 PM

@Prtksxna Tooltips/inline text can currently be added to an OO.ui.FieldLayout or an OO.ui.FieldsetLayout, by setting a config option. The 'help' config option is not currently passed through to the FieldLayout for each radio option, so it is not possible to add tooltips for each option in this way. We can implement this, but it didn't seem worth it for the demo on my previous comment.

From Recent Changes, perhaps something we can emulate.

Prateek is going to add in help text with a link to https://www.mediawiki.org/wiki/Help:Blocking_users. We'll need to update that help page.

TBolliger renamed this task from Solve for tooltips on Special:Block (aka product orientation) to Add help text to Special:Block for Partial Blocks.Jan 31 2019, 12:05 AM
TBolliger updated the task description. (Show Details)

This is what I had in mind, smaller help texts that can fit in just one line and links out to documentation wherever needed. Would something like this work?

@Prtksxna That looks good to me!

Only thing that strikes me is that the "(learn more)" after editing might be overkill now, with all the inline help messages?

I say we drop the help text on the Pages input field and keep them only for the radio buttons. Otherwise — looks good!

Only thing that strikes me is that the "(learn more)" after editing might be overkill now, with all the inline help messages?

Would all these Learn more links be pointing to the same place? If yes, I agree, let's drop it.

I say we drop the help text on the Pages input field and keep them only for the radio buttons. Otherwise — looks good!

Agreed, the partial blocks help messages already tells us what the pages field would be used for.

Yes, the links would point to the same place. Personally I like the link in the help text best, so let's go with:

Sounds good to me!

TBolliger removed Prtksxna as the assignee of this task.Feb 13 2019, 5:26 PM
TBolliger updated the task description. (Show Details)
TBolliger set the point value for this task to 3.

Change 493330 had a related patch set uploaded (by Tchanders; owner: Tchanders):
[mediawiki/core@master] Add help text to "partial" and "sitewide" options on Special:Block

https://gerrit.wikimedia.org/r/493330

@TBolliger Can we change the message text to this?

  • Sitewide: Every page on the wiki and all other contribution actions.
  • Partial: Specific pages or namespaces. Learn more.

I think the form makes it clear that you can configure it, it makes it clear what option is which, so you don't need to restate it, it also makes it clear that it applies to the target and that this is specific to editing. That means the only thing we need to do is explain what "Sitewide" and "Partial" mean.

@TBolliger Can we change the message text to this?

  • Sitewide: Every page on the wiki and all other contribution actions.
  • Partial: Specific pages or namespaces. Learn more.

I think the form makes it clear that you can configure it, it makes it clear what option is which, so you don't need to restate it, it also makes it clear that it applies to the target and that this is specific to editing. That means the only thing we need to do is explain what "Sitewide" and "Partial" mean.

I love it. Including "Sitewide blocks..." is redundant, and the 'Learn more' link is there for those who want more details.

Tchanders updated the task description. (Show Details)Feb 28 2019, 9:02 PM

On the patch, @dbarratt points out that clicking on the help text selects the associated option. This is a problem because we have a "Learn more" link in the text for the "partial" option, and it doesn't seem user friendly that clicking on that link selects the option.

Why this happens

Many input widgets have associated labels, explaining what they do (here, this means the "Sitewide" and "Partial" labels next to the radio buttons). Additionally, they can have associated help text labels, giving more detail. Both the main label and the help text label are <label> elements. For many input widgets, these have a "for" attribute that points to the widget, which means the widget reacts when the user clicks on them. It is recommended not to put links inside such labels, for accessibility purposes: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label#Accessibility_concerns

For some widgets, such as the button input widget, none of the associated <label> elements are clickable in this way.

See Special:Preferences for examples of clickable and non-clickable help labels.

The radio input widget needs a clickable main label, and there isn't currently a way for an input widget to have a clickable main label, but a non-clickable help label.

Possible solutions

  • Simply move the "Learn more" link out of the help label. The help labels will still be clickable, but will no longer contain a link. If we do this, we obviously shouldn't move the link to a help text label associated with a widget.
  • Create some mechanism for specifying that, for radio input widgets, the main label should have the "for" attribute (i.e. be clickable), but the help label should not.

Which of these is better probably depends on whether it is desirable for the help label to be clickable. @Volker_E is the help label deliberately clickable for accessibility reasons (i.e. does it have the "for" attribute for accessibility reasons)?

I think we can remove the 'Learn more' link out of the help label.

Also: Not sure if fixing T208547: Just clicking on the empty space around should not change the type of block radio button selection would make this easier.

is the help label deliberately clickable for accessibility reasons (i.e. does it have the "for" attribute for accessibility reasons)?

Yes. That is a best practice that needs to be preserved (and should be fixed anywhere it is not):
https://developer.mozilla.org/en-US/docs/Learn/Accessibility/HTML#Meaningful_text_labels

Otherwise, there is no way to tell which label is associated with which form input.

Although, the help text, idealy, should not be within a <label> element at all, since it is not a label.

This is a problem because we have a "Learn more" link in the text for the "partial" option, and it doesn't seem user friendly that clicking on that link selects the option.

Luckily, that's not the case. An <a> receives precedence over a label and also doesn't activate the option, example here.

It is recommended not to put links inside such labels, for accessibility purposes: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label#Accessibility_concerns

My informed guess is, that devs ended up putting a long anchor into a label, nulling the label's focus intention.

For some widgets, such as the button input widget, none of the associated <label> elements are clickable in this way.

A connected <label> on a ButtonInputWidget moves to focus on the button itself, additionally to providing a longer associated explanation to screen readers.

Possible solutions

  • Simply move the "Learn more" link out of the help label. The help labels will still be clickable, but will no longer contain a link. If we do this, we obviously shouldn't move the link to a help text label associated with a widget.
  • Create some mechanism for specifying that, for radio input widgets, the main label should have the "for" attribute (i.e. be clickable), but the help label should not.

Which of these is better probably depends on whether it is desirable for the help label to be clickable. @Volker_E is the help label deliberately clickable for accessibility reasons (i.e. does it have the "for" attribute for accessibility reasons)?

As I've mentioned above, the link doesn't affect the rest of the label, nor the option. I think
a) that it's fine to leave the link part of the label due to the link being short in contrast to the rest of the label, ensuring pointer activation and guiding focus.
b) that it is an in-detailed description for the option (orienting on screenshots above) and therefore semantically qualifies as label – in response to latest comment by @dbarratt

Luckily, that's not the case. An <a> receives precedence over a label and also doesn't activate the option, example here.

If you checkout the patch in: https://gerrit.wikimedia.org/r/493330 you can see it happening (at least in Firefox)

b) that it is an in-detailed description for the option (orienting on screenshots above) and therefore semantically qualifies as label – in response to latest comment by @dbarratt

This is accurate as long as the text is in the same element (i.e. you ought not have more than one label for a single form element).

Change 494285 had a related patch set uploaded (by Tchanders; owner: Tchanders):
[oojs/ui@master] Allow inline help text to be passed to FieldLayouts around options

https://gerrit.wikimedia.org/r/494285

b) that it is an in-detailed description for the option (orienting on screenshots above) and therefore semantically qualifies as label – in response to latest comment by @dbarratt

This is accurate as long as the text is in the same element (i.e. you ought not have more than one label for a single form element).

How do you get to this conclusion? HTML 4 specification stated:

The LABEL element may be used to attach information to controls. Each LABEL element is associated with exactly one form control.

So a label can reference only one form control, but multiple labels can be associated to the same form control.
HTML 5.2 isn't as explicit about it any more, but browser vendor implementation and HTML validation paved the way.

b) that it is an in-detailed description for the option (orienting on screenshots above) and therefore semantically qualifies as label – in response to latest comment by @dbarratt

This is accurate as long as the text is in the same element (i.e. you ought not have more than one label for a single form element).

HTML 5.2 specifically gives all the examples we've been discussing here about :)
https://www.w3.org/TR/html5/sec-forms.html#the-label-element From example 4 on.

It's stated as “bad example - link inside label reduces checkbox activation area”, which in our use case above seems fine for given reasons.

dbarratt added a comment.EditedMar 4 2019, 7:03 PM

See https://developer.mozilla.org/en-US/docs/Learn/HTML/Forms/How_to_structure_an_HTML_form#Multiple_labels which says:

Strictly speaking, you can put multiple labels on a single widget, but this is not a good idea as some assistive technologies can have trouble handling them. In the case of multiple labels, you should nest a widget and its labels inside a single <label> element.

What they are probably referring to is NVDA, reading out only the first label associated with the form (at least until a year ago). Which doesn't imply it's negatively affecting one or the other screen readers, as the primary label is still working well and the secondary provides additional context where supported.

Tchanders added a comment.EditedMar 4 2019, 8:20 PM

@Volker_E Thanks for explaining about the precedence of <a> and <label>.

@dbarratt is correct that the clicking the link selects the option (PS1 of https://gerrit.wikimedia.org/r/493330). It seems there's something in the JavaScript doing this, because it doesn't happen if JS is disabled (that's the case whether JS is disabled before or after the page loads).

If we can live without the link, then I think the quickest way to solve this will be to remove the link. However, we should file a follow-up task to look into why clicking on the link selects the option. Does that sound OK to you @TBolliger ?

(I've also filed a follow-up task to create a better way of passing help text into a radio option - T217693)

Sounds good to me Thalia!

Change 493330 merged by jenkins-bot:
[mediawiki/core@master] Add help text to "partial" and "sitewide" options on Special:Block

https://gerrit.wikimedia.org/r/493330

Considering this is quite a small change, I am not doing any testing especially for this task.

I have been testing the Special:Block form as part of other tasks. I see no problems caused by these extra labels.

I have incidentally tested the form on Firefox, Chromium, IE11, IE8 and Android, and also in German.

I did not test it with a screen reader. If I am interpreting T213101#4999290 correctly, the risk seems low.

TBolliger closed this task as Resolved.Mar 12 2019, 4:48 PM

👍