New: Add priority labels to templates and schemas (fix #816)

[swashbuck]

Fix #816

📋 To-do

• Migration scripts

New

• Adds priority labels to headings

Notes

• Can be configured to show optional labels, required labels, both, or none
• Each content type can have different behavior for showing labels
• Classes added so that the type of label can be styled differently (e.g. red labels for required and orange for optional)

Dependencies

• For styling: New: Add basic styling for heading priority labels (fix #566) adapt-contrib-vanilla#567
• For Box Menu: New: Required and optional labels added (Fixes #191) adapt-contrib-boxMenu#193

❓ Questions

1. Should we show priority labels when there isn't a displayTitle? For instance, if we have a graphic component that is optional but doesn't have a displayed title, do we need to show "optional" when components are configured to show them?
2. Should we include an exclamation mark icon? If so, should be it for required, optional, or both?

In this example, there is no displayed title for the optional Graphic component so the optional label is not shown (1). Then, the optional label has an exclamation mark (2).

Configuration

In course.json, add the following to _globals and enable/disable labels as desired.

The following example configuration will show optional labels only for menu item and page headings. In contentObjects.json, set "_isOptional": true to make content objects optional.

"_priorityLabels": {
  "_iconClassOptional": "",
  "_iconClassRequired": "icon-exclamation",
  "_menuItem": {
    "_showWhenOptional": true,
    "_showWhenRequired": false
  },
  "_page": {
    "_showWhenOptional": true,
    "_showWhenRequired": false
  },
  "_article": {
    "_showWhenOptional": false,
    "_showWhenRequired": false
  },
  "_block": {
    "_showWhenOptional": false,
    "_showWhenRequired": false
  },
  "_component": {
    "_showWhenOptional": false,
    "_showWhenRequired": false
  }
},

[swashbuck]

Ready for review.

[oliverfoster]

Should the icons be defined in the json? I'm not sure what the standard is there. CSS only or json define class name?

[swashbuck]

Should the icons be defined in the json? I'm not sure what the standard is there. CSS only or json define class name?

I like the idea of setting this in the JSON config. This could be two new props that would apply to all types (box menu item, article, etc). I don't feel that we would need a different icon for each type. So, we would have:

"_priorityLabels": {
  "_iconClassOptional": "", // no icon for optional
  "_iconClassRequired": "icon-exclamation", // exclamation mark for required
  "_menuItem": {
    "_showWhenOptional": true,
    "_showWhenRequired": false
  },
  "_page": {
    "_showWhenOptional": true,
    "_showWhenRequired": false
  },
  etc.....

Thoughts about this approach? We would need to remove it from the Vanilla theme PR as the icon is currently hard-coded in the Less.

[swashbuck]

@kirsty-hames Any thoughts on the icon config proposed solution?

[kirsty-hames]

"_priorityLabels": {
"_iconClassOptional": "", // no icon for optional
"_iconClassRequired": "icon-exclamation", // exclamation mark for required

@kirsty-hames Any thoughts on the icon config proposed solution?

I'm happy with the above suggestion thanks @swashbuck. When I've seen optional/progress labels used in projects, I've only seen icons used as suggested (no icon for optional, exclamation mark for required). Whilst I can't see much scope for changing the icons at least it's future proofing for customisation.

[kirsty-hames]

Hey @swashbuck, just thinking on this from an a11y perspective, whilst the optional/required labels are accessible, they don't have context of the content they refer to. As per my suggestion in the PLP optional content visual indicator PR, is it worth adding the optional / required labels to the model headings like we already do for complete/incomplete?

Alternatively, we could add the model title to the optional/required labels as hidden labels. However, I think it makes sense to update the model headings for the following reasons:

• headings are often used as landmarks to navigate page content by SR users so heading level labels would mean a learner could easily identify optional/required content
• consistency with the existing complete/incomplete labels we add to headings
• avoid duplicate reading of title text when linear reading through a page

If we did do this then we should set the priority labels to aria-hidden="true" to avoid duplicate reading when a model title exists.

[swashbuck]

Icon classes have been implemented.

is it worth adding the optional / required labels to the model headings like we already do for complete/incomplete?

@kirsty-hames I think this makes sense. Would we only show optional / required when the relevant priority labels are configured to be shown? In other words, only show optional when _showWhenOptional is true for that type (ex. box menu item, component)?

Also, this is how the titles could be read. Is this what you had in mind?

Content Type	Heading Announcement
Optional incomplete	"Optional. [Title]"
Optional complete	"Optional. Complete. [Title]"
Required incomplete	"Required. Incomplete. [Title]"
Required complete	"Required. Complete. [Title]"

[kirsty-hames]

Would we only show optional / required when the relevant priority labels are configured to be shown?

Thanks @swashbuck. Yep this is what I had in mind. If an on screen label doesn't exist then there's no reason to provide the alt text equivalent.

[swashbuck]

Thanks, @kirsty-hames .

When a displayTitle isn't present:

1. Should we show the priority label at all? Currently, it's shown as long as there is a displayTitle, body text, or instruction text. So, an optional Graphic without any text will not show the label.
2. If we do show the label when there is no title, how should we announce the status to assistive technologies? Would they read the onscreen label or would we add a new AT-only span tag?

Screenshots showing 3 optional components: Text, MCQ and Graphic. Note that the label is not shown for the optional Graphic.

[kirsty-hames]

When a displayTitle isn't present:

1. Should we show the priority label at all? Currently, it's shown as long as there is a displayTitle, body text, or instruction text. So, an optional Graphic without any text will not show the label.
2. If we do show the label when there is no title, how should we announce the status to assistive technologies? Would they read the onscreen label or would we add a new AT-only span tag?

Good points @swashbuck. I'm open to either but my preference would be to only display the priority label when displayTitle is present. A couple of reasons why:

• From an a11y perspective, I think all required content should have a title so users can easily evaluate and navigate required content. Less of an issue for optional content.
• Flexibility in content layout. For example, the MCQ and Graphic instance you've provided above, a double up on labels is unnecessary and adds visual clutter.

[swashbuck]

Thanks, @kirsty-hames. I agree on both points. That said, I can think of one use case that might be a problem: when we use a block header to replace the component header. For example:

Block header with "MCQ" title and body text
Single width MCQ with no displayed title / body text	Single width Graphic

But we probably wouldn't want the priority label to be positioned above the title-less MCQ component either. Maybe we shouldn't worry about this edge case, although we do often use this layout. Could also use block priority labels instead of component labels in this case.

With block priority labels enabled: