Allow extensions and users to customize easily toolbar items.

[fcollonval]

References

Fixes #10419

• Add a new registry for toolbar widgets
• Create toolbar items asynchronously in Widget factory. (not needed)
• Add helper to get the toolbar factory from the settings and the new registry.
• Apply it on notebook panel
• Allow to set a custom icon & label in CommandToolbarButton to cover commands without icons
• Refactor notebook toolbar widget to use the associated command for homogeneity with the menus and shortcuts.
• Apply it on other factories
• tests
• documentation

Code changes

• Add a new toolbar widget registry
  That registry can generate toolbar item widget based on a factory name (the one use to create the container) and the item name. It has a default widget factory to build item from definition (in particular to create CommandToolbarButton)
• Allow CommandToolbarButton to receive an icon and or a label that overrides the one define by the command (mainly to cover command without icon).
• If a toolbar command button is generated with the default widget factory, an additional argument toolbar = true will be passed to tune icon, label,... of the command.
• The toolbar factory is passed when defining the document factory using the existing API. This keep the separation of concern between the new registry, the settings and the document factories.

User-facing changes

Users can now customize toolbar items. They can hide existing items in the same matter than the menus or the shortcuts (aka set disabled to true). They can add new items; for now the default factory supports only spacers and command buttons.

In the example below, the restart and run all button is hidden and a new button to trigger clear all outputs is added.

Keyboard shortcuts appear now in toolbar as we reuse commands:

Before

After

The customizable toolbar has been applied to the following document factory:

• CSV Viewer
• HTML Viewer
• File Editor

Here is an example on the text file editor:

Backwards-incompatible changes

CSVDelimiter widget toolbar has been changed to fit the usual pattern of receiving the document widget rather than using signal. This was considered as ok as that part of the code is unlikely to be reused else where.

Reference:

jupyterlab/packages/csvviewer/src/toolbar.ts

Line 27 in 9fa65ce

export class CSVDelimiter extends Widget {

[jupyterlab-dev-mode]

Thanks for making a pull request to JupyterLab!

To try out this branch on binder, follow this link:

[krassowski]

js-csvviewer failures seem relevant.

[lumberbot-app]

Owee, I'm MrMeeseeks, Look at me.

There seem to be a conflict, please backport manually. Here are approximate instructions:

1. Checkout backport branch and update it.

$ git checkout 3.2.x
$ git pull

2. Cherry pick the first parent branch of the this PR on top of the older branch:

$ git cherry-pick -m1 386b5758bbf4d56f08786df9c3f4e5bda14563f5

3. You will likely have some merge/cherry-pick conflict here, fix them and commit:

$ git commit -am 'Backport PR #10469: Allow extensions and users to customize easily toolbar items.'

4. Push to a named branch :

git push YOURFORK 3.2.x:auto-backport-of-pr-10469-on-3.2.x

5. Create a PR against branch 3.2.x, I would have named this PR:

"Backport PR #10469 on branch 3.2.x (Allow extensions and users to customize easily toolbar items.)"

And apply the correct labels and milestones.

Congratulation you did some good work! Hopefully your backport PR will be tested by the continuous integration and merged soon!

Remember to remove Still Needs Manual Backport label once the PR gets merged.

If these instruction are inaccurate, feel free to suggest an improvement.

[blink1073]

@fcollonval I attempted to backport this manually but there were a lot of conflicts and I think you'd be better suited to handle them. We could also save this one for 4.0.

[fcollonval]

Thanks @blink1073 to try backporting this one. I'll have a look.

[fcollonval]

Ok let's not include this one on 3.2.x.

[jtpio]

Ok let's not include this one on 3.2.x.

Just checking: did we decide not to backport because of the amount of conflicts? But it could be backported because there is no breaking change, apart from the note in the top comment?

[blink1073]

I'm fine with this being backported, from my perspective it was a lack of bandwidth.

[fcollonval]

I think we should consider a 3.3 version due to notebook v7 (aka nb7). Because in addition to this one, we need to add customization for widget shell positioning; for example:

• the inspector panel should appear in a down panel in nb7
• we may want to have the same behavior to allow associated console with a notebook
• this could provide a generic way to deal with extension that are added in sidebars; we may want to define in nb7 if they should appear in the tree page like the file browser and running widgets or in the notebook or editor like ToC, metadata edition, debugger

Going a bit further into the implementation, we could extend the shell.add method options to receive an optional unique identifier for panel (fallback could be the panel id) and for widgets generated from factory that identifier would be the factory name. Then this identifier will be used as key in a position mapping defined by settings (more precisely that could override the default positioning).

[fcollonval]

It could be good to discuss what should be changed in jlab to support nb7 and check if it can be based on a v3.3 or should wait for v4.

[jtpio]

For reference, checking whether customizing toolbars was available in 3.2 came up while looking at jupyterlab/retrolab#283

[jtpio]

Because in addition to this one, we need to add customization for widget shell positioning;

@fcollonval mind opening a new issue to discuss this? Thanks!

[fcollonval]

mind opening a new issue to discuss this?

Done

[fcollonval]

@meeseeksdev please backport to 3.3.x

[lumberbot-app]

Owee, I'm MrMeeseeks, Look at me.

There seem to be a conflict, please backport manually. Here are approximate instructions:

1. Checkout backport branch and update it.

git checkout 3.3.x
git pull

2. Cherry pick the first parent branch of the this PR on top of the older branch:

git cherry-pick -m1 386b5758bbf4d56f08786df9c3f4e5bda14563f5

3. You will likely have some merge/cherry-pick conflict here, fix them and commit:

git commit -am 'Backport PR #10469: Allow extensions and users to customize easily toolbar items.'

4. Push to a named branch:

git push YOURFORK 3.3.x:auto-backport-of-pr-10469-on-3.3.x

5. Create a PR against branch 3.3.x, I would have named this PR:

"Backport PR #10469 on branch 3.3.x (Allow extensions and users to customize easily toolbar items.)"

And apply the correct labels and milestones.

Congratulations — you did some good work! Hopefully your backport PR will be tested by the continuous integration and merged soon!

Remember to remove the Still Needs Manual Backport label once the PR gets merged.

If these instructions are inaccurate, feel free to suggest an improvement.