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": {
  "_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?

[joe-replin]

Suggested change

	const type = this.constructor.type;
	// Early exit if not a supported content type
	if (!['menuItem', 'page', 'article', 'block', 'component'].includes(type)) {
	const SUPPORTED_TYPES = ['menuItem', 'page', 'article', 'block', 'component'];
	const type = this.constructor.type;
	// Early exit if not a supported content type
	if (!SUPPORTED_TYPES.includes(type)) {

Consider extracting supported types for maintainability.

[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.