New: Added Navigation Button API #339

oliverfoster · 2023-03-30T16:02:03Z

fixes #338

New

NavigationButtonModel To hold the properties for each button
NavigationButtonView For extensions to make their own buttons and for legacy injected button management
NavigationModel To hold the navigation configuration
All model updates will be reflected in the DOM.

General API layout:

import navigation from 'core/js/navigation';
navigation.model.set('_showLabel', true); // Show all labels

const backButton = navigation.getButton('back');
backButton.set('_order', 400); // Move the back button to the right
backButton.set('text', 'New Label'); // Change the back button label text


navigation.removeButton(backButton); // Remove back button

// Remove all buttons
navigation.buttons.forEach(button => navigation.removeButton(button));

To make a home button:

import Adapt from 'core/js/adapt';
import navigation from 'core/js/navigation';
import NavigationButtonModel from 'core/js/models/NavigationButtonModel';
import NavigationButtonView from 'core/js/views/NavigationButtonView';

// Extend the model and view classes to add own behaviour

Adapt.on('navigation:ready', () => {
  const model = new NavigationButtonModel({
    _id: 'home',
    _order: 0,
    _event: 'homeButton',
    _showLabel: null,
    _classes: '',
    _iconClasses: 'icon-medal',
    _role: 'link',
    ariaLabel: 'Home',
    text: '{{ariaLabel}}'
  });
  const view = new NavigationButtonView({ model });
  navigation.addButton(view);
});

Each button has the potential for custom _id, _order, _event, _showLabel, _classes, _iconClasses, _role, ariaLabel and text, with global settings for _showLabel, _navigationAlignment and _isBottomOnTouchDevices.

_event has some default behaviour at "backButton", "homeButton", "parentButton", "skipNavigation" and "returnToStart".

Example:
Added visua11y and the above home button to the vanilla course

Backward compatibility

Older buttons should have an aria-label attribute or an .aria-label element in order for a text label to be automatically generated. A <span class="label" aria-hidden="true">{{ariaLabel}}</span> will be appended automatically to any existing button, if it doesn't exist, and will otherwise be automatically updated from the value of the aria-label attribute or .aria-label element. This is as model text defaults to {{ariaLabel}}. On older buttons "ariaLabel", "_role" and "_classes" have no effect when changed from the model as they should be supplied by the injected buttons themselves. "text", "_order", "_showLabel", "_id" and "_event" should work as expected on older injected buttons.

Requires

https://github.com/adaptlearning/adapt-contrib-pageLevelProgress/pull/174
https://github.com/adaptlearning/adapt-contrib-trickle/pull/188
https://github.com/adaptlearning/adapt-contrib-vanilla/pull/415 - ✅ Merged

Testing

In the console it is possible to use:

require('core/js/navigation').model.set('_showLabel', true);
require('core/js/navigation').getButton('back').set('_order', 400);
require('core/js/navigation').getButton('back').set('text', 'New Label');

swashbuck · 2023-04-04T21:44:25Z

Created adaptlearning/adapt-contrib-pageLevelProgress#174 for Page Level Progress style changes.

swashbuck · 2023-04-04T21:51:47Z

@oliverfoster I've added a class called has-label-bottom that will move the labels below the icons. This should be an option at both the course level and the extension level.

Question: Are two text label position options enough? Default would be label on the right, and the new option would be label under the icon. Would it be better to have something like _labelPosition that can be set to top, left, right or bottom?

oliverfoster · 2023-04-05T07:00:26Z

@oliverfoster I've added a class called has-label-bottom that will move the labels below the icons. This should be an option at both the course level and the extension level.

Question: Are two text label position options enough? Default would be label on the right, and the new option would be label under the icon. Would it be better to have something like _labelPosition that can be set to top, left, right or bottom?

I'm sure there will be an rtl requirement at minimum. @guywillis positioning controls at a course level?

swashbuck · 2023-04-05T14:56:27Z

I'm sure there will be an rtl requirement at minimum. @guywillis positioning controls at a course level?

@oliverfoster Ok, I can create classes for has-label-bottom, has-label-top, has-label-left, and has-label-right. That should cover everything. Then, we'll need a new setting/property for the model.

I think course-level positioning is probably fine?

swashbuck · 2023-04-11T17:48:49Z

Hide text below medium

I've implemented this in the Less for now. If we need to give devs more control (which might be overkill), we could add another course.json property.

Property name: _showLabelAtWidth

empty - Always show the label
small - Show at small width and up
medium - Show at medium width and up
large - Show at large width and up

This would add a class to .nav like show-label-small which can then be used to show the labels at certain breakpoints.

  "_navigation": {
    "_showLabel": true,
    "_showLabelAtWidth": "medium"
  }

oliverfoster · 2023-04-11T17:59:35Z

Hide text below medium

I've implemented this in the Less for now. If we need to give devs more control (which might be overkill), we could add another course.json property.

Property name: _showLabelAtWidth

empty - Always show the label

small - Show at small width and up

medium - Show at medium width and up

large - Show at large width and up

This would add a class to .nav like show-label-small which can then be used to show the labels at certain breakpoints.
  "_navigation": {
    "_showLabel": true,
    "_showLabelAtWidth": "medium"
  }

I'd like to get @guywillis input on this bit as it was his biggest concern, along with a review of the styling.

oliverfoster · 2023-04-11T23:18:11Z

I think, in lieu of an option in the JSON, these classes should be sufficient for custom styling.

What should be the default in either case?

swashbuck · 2023-04-12T16:17:27Z

I think, in lieu of an option in the JSON, these classes should be sufficient for custom styling.

What should be the default in either case?

I think 'medium' is a good default. That's what we usually use in projects.

swashbuck · 2023-04-14T16:36:31Z

Positioning and breakpoint settings have been added at the top level.

course.json

  "_navigation": {
    "_showLabel": true,
    "_showLabelAtWidth": "small|medium|large", // default is medium
    "_labelPosition": "left|right|top|bottom" // default is right
  },

Schemas will need to be updated.

swashbuck · 2023-04-17T18:28:30Z

Schemas have been added for the new options.

swashbuck · 2023-04-25T22:00:12Z

One final comment to raise from myself. The setting _showLabelAtWidth assumes the course creator will always want to hide the labels at a certain adapt breakpoint - what if I want to always show the labels?

@guywillis I've modified the styles a bit and added a new option called "any" that will show the labels at any size. Labels can still be hidden completely at the global level with _navigation._showLabel: false or at the plugin level (ex. PLP adaptlearning/adapt-contrib-pageLevelProgress#180 ).

swashbuck · 2023-04-25T22:11:13Z

Just for my own sanity, these are all of the Navigation Button API-related PRs:

https://github.com/adaptlearning/adapt-contrib-core/pull/339 - ✅ Merged
https://github.com/adaptlearning/adapt-contrib-pageLevelProgress/pull/174 - ✅ Merged
https://github.com/adaptlearning/adapt-contrib-pageLevelProgress/pull/180 - ✅ Merged
https://github.com/adaptlearning/adapt-contrib-trickle/pull/188 - ✅ Merged
https://github.com/adaptlearning/adapt-contrib-vanilla/pull/415 - ✅ Merged

guywillis

👍

Couple of comments to adjust defaults but otherwise I'm happy - really nice work

js/models/NavigationModel.js

js/views/navigationView.js

swashbuck

👍

oliverfoster · 2023-04-28T14:52:23Z

One more approval and we're ready to merge.

js/views/navigationView.js

templates/navButton.jsx

# [6.34.0](v6.33.0...v6.34.0) (2023-05-02) ### New * Added Navigation Button API (#339) ([d64f999](d64f999)), closes [#339](#339)

oliverfoster · 2023-05-02T08:43:22Z

🎉 This PR is included in version 6.34.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

# [6.34.0](v6.33.0...v6.34.0) (2023-05-02) ### New * Added Navigation Button API (#339) ([d64f999](d64f999)), closes [#339](#339)

…/adapt-contrib-core#339)

oliverfoster added 2 commits March 30, 2023 16:02

New: Added Navigation Button API

d9dfbab

Fixed new button creation

1d1866b

oliverfoster requested a review from joe-replin March 30, 2023 16:02

oliverfoster self-assigned this Mar 30, 2023

oliverfoster added the enhancement New feature or request label Mar 30, 2023

oliverfoster and others added 2 commits March 30, 2023 17:33

Added missing filters to classes

9775269

Icon and label alignment

c2d187f

This was referenced Apr 4, 2023

Navigation Button API compatibility adaptlearning/adapt-contrib-pageLevelProgress#173

Closed

Breaking: Navigation Button API compatibility (fixes #173) adaptlearning/adapt-contrib-pageLevelProgress#174

Merged

Additional positioning options, changed label class

2b89e20

This was referenced Apr 5, 2023

Navigation Button API support adaptlearning/adapt-contrib-vanilla#414

Closed

Fix: Add font size variable for nav button label (fixes #414) adaptlearning/adapt-contrib-vanilla#415

Merged

Only show labels for medium and above

c9d2fc5

swashbuck added 3 commits April 14, 2023 09:01

Merge remote-tracking branch 'origin/master' into issue/338

33c8d2b

Add positioning and breakpoint properties / classes

16e4e93

Remove label font size - fixed by Vanilla issue #414

410d063

oliverfoster marked this pull request as ready for review April 17, 2023 16:01

swashbuck added 2 commits April 17, 2023 12:16

Merge remote-tracking branch 'origin/master' into issue/338

8baa0c9

Schema updates for the new nav label options

1cc4aa6

oliverfoster requested a review from cahirodoherty-learningpool April 17, 2023 20:34

swashbuck added 2 commits April 25, 2023 15:49

Add option to show label at any size

5a90c7d

Fix for hiding labels globally

833d975

guywillis approved these changes Apr 26, 2023

View reviewed changes

js/models/NavigationModel.js Outdated Show resolved Hide resolved

js/views/navigationView.js Outdated Show resolved Hide resolved

oliverfoster mentioned this pull request Apr 26, 2023

Add API for listening to DOM element modifications #360

Closed

Update _labelPosition default to 'auto'

c43a400

swashbuck requested a review from kirsty-hames April 26, 2023 15:25

Nest rtl/ltr styles under has-label-auto

635c8c7

oliverfoster requested review from eleanor-heath and swashbuck April 28, 2023 09:42

Merge branch 'master' into issue/338

596291f

swashbuck approved these changes Apr 28, 2023

View reviewed changes

eleanor-heath reviewed May 2, 2023

View reviewed changes

js/views/navigationView.js Outdated Show resolved Hide resolved

eleanor-heath reviewed May 2, 2023

View reviewed changes

templates/navButton.jsx Outdated Show resolved Hide resolved

Suggestions and loading fix

c2475b5

eleanor-heath approved these changes May 2, 2023

View reviewed changes

oliverfoster merged commit d64f999 into master May 2, 2023

oliverfoster deleted the issue/338 branch May 2, 2023 08:42

github-actions bot pushed a commit that referenced this pull request May 2, 2023

Chore(release): 6.34.0

b20e6f8

# [6.34.0](v6.33.0...v6.34.0) (2023-05-02) ### New * Added Navigation Button API (#339) ([d64f999](d64f999)), closes [#339](#339)

oliverfoster added the released label May 2, 2023

oliverfoster added a commit that referenced this pull request May 4, 2023

New: Added Navigation Button API (#339)

7d9e81b

oliverfoster pushed a commit that referenced this pull request May 4, 2023

Chore(release): 6.34.0

ae17c2c

# [6.34.0](v6.33.0...v6.34.0) (2023-05-02) ### New * Added Navigation Button API (#339) ([d64f999](d64f999)), closes [#339](#339)

kirsty-hames mentioned this pull request Jul 12, 2023

Navigation properties need documenting #408

Closed

hanshillen mentioned this pull request Sep 17, 2023

Skip navigation button text is hidden #443

Closed

swashbuck mentioned this pull request Mar 27, 2024

Migrate drawer button to Navigation Button API #512

Open

henrietta-k pushed a commit to henrietta-k/adapt-learning-wiki that referenced this pull request Apr 7, 2024

Navigation button API updated (info taken from PR notes adaptlearning…

59971e1

…/adapt-contrib-core#339)

chris-steele mentioned this pull request Apr 19, 2024

Allow UI plugins to customise the content header adapt-security/adapt-authoring-ui#284

Open

1 task

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

New: Added Navigation Button API #339

New: Added Navigation Button API #339

oliverfoster commented Mar 30, 2023 •

edited

Loading

swashbuck commented Apr 4, 2023

swashbuck commented Apr 4, 2023 •

edited

Loading

oliverfoster commented Apr 5, 2023

swashbuck commented Apr 5, 2023 •

edited

Loading

swashbuck commented Apr 11, 2023 •

edited

Loading

oliverfoster commented Apr 11, 2023

oliverfoster commented Apr 11, 2023

swashbuck commented Apr 12, 2023

swashbuck commented Apr 14, 2023 •

edited

Loading

swashbuck commented Apr 17, 2023

swashbuck commented Apr 25, 2023

swashbuck commented Apr 25, 2023 •

edited

Loading

guywillis left a comment

swashbuck left a comment

oliverfoster commented Apr 28, 2023

oliverfoster commented May 2, 2023

New: Added Navigation Button API #339

New: Added Navigation Button API #339

Conversation

oliverfoster commented Mar 30, 2023 • edited Loading

New

Backward compatibility

Requires

Testing

swashbuck commented Apr 4, 2023

swashbuck commented Apr 4, 2023 • edited Loading

oliverfoster commented Apr 5, 2023

swashbuck commented Apr 5, 2023 • edited Loading

swashbuck commented Apr 11, 2023 • edited Loading

oliverfoster commented Apr 11, 2023

oliverfoster commented Apr 11, 2023

swashbuck commented Apr 12, 2023

swashbuck commented Apr 14, 2023 • edited Loading

swashbuck commented Apr 17, 2023

swashbuck commented Apr 25, 2023

swashbuck commented Apr 25, 2023 • edited Loading

guywillis left a comment

Choose a reason for hiding this comment

swashbuck left a comment

Choose a reason for hiding this comment

oliverfoster commented Apr 28, 2023

oliverfoster commented May 2, 2023

oliverfoster commented Mar 30, 2023 •

edited

Loading

swashbuck commented Apr 4, 2023 •

edited

Loading

swashbuck commented Apr 5, 2023 •

edited

Loading

swashbuck commented Apr 11, 2023 •

edited

Loading

swashbuck commented Apr 14, 2023 •

edited

Loading

swashbuck commented Apr 25, 2023 •

edited

Loading