Ckeditor5: Multiline toolbar (wrapping toolbar)

[thorleifjaocbsen]

Would love to see a possibility as CKEditor4 to have "/" as a toolbar item which breaks it to a new line when using the option "shouldNotGroupWhenFull"

---

If you'd like to see this feature implemented add 👍 reaction to this post.

[Reinmar]

Thanks for the feature request. I guess we're doing everything to avoid having multiline toolbars (e.g. by introducing toolbar grouping), but let's see how many people would still prefer this way of handling big number of buttons.

[Reinmar]

It's possible to create line breaks by:

1. Registering a component named e.g. "/" which will render something like a <span class="break-line">.
2. Styling it to something like flex-basis:100%; height:0; margin:0; padding:0.
3. Styling the entire .ck-toolbar__items with flex-wrap: wrap.
4. Once this is done, you can use a toolbar item called "/" to create line breaks.

[Reinmar]

I've been looking at demos of "document presets" such as https://ckeditor.com/docs/ckeditor5/latest/features/export-pdf.html and the buttons don't fit there even despite the wide column.

I think we need to prioritize wrapping the toolbar finally.

Also, we changed the styling of the vertical separator which makes that simpler now.

The tricky bit here is how to implement the separator as the child of the toolbar collection in a way that the focus cycler will ignore it.

We also need to disable toolbar wrapping for such toolbars. It does not make sense to try to make both features compatible with each other.

[Reinmar]

• Automatic vs manual (declarative) toolbar wrapping.
  
  
  
  • Declarative is more predictable.
  
  
  • Automatic may end up with 18 items in the first line and 2 in the second. Would anyone be happy with that?
  
  
• We need to document that this does not work with "group when full" so requires using "shouldNotGroupWhenFull".
  
  
  
  • Perhaps we can even automate this so when there's / in the toolbar, we disable grouping automatically.
  
  
• We should document that this is not optimal when considering small mobile screens.
• Future: automatically switch grouping on when hitting the "small screen starts wrapping 2 lines into 4 :facepalm: case".
  
  
  
  • TODO: can we do something reasonable for this case now, or is our only option documenting this.
  
  
  • Related issue: https://app.zenhub.com/workspace/o/ckeditor/ckeditor5/issues/5586.
  
  
• Future: each line grouped separately 🔥. Report a followup.
  
  
  
  • Worth researching how similar editors (with similar toolbars) behave
  
  

[oleq]

• PoC in i/6146-multiline-toolbar
• I decided to leave the toolbar auto-grouping enabled for all editors by default for backward compatibility.
  
  
  
  • In other words, for the toolbar line break to work shouldNotGroupWhenFull: true must be specified in the toolbar configuration.
  
  
  • See (Problems) below to learn more.
  
  
• I went with '/' for toolbar break in the toolbar configuration.
  
  
  
  • (For the record) We use '|' for separators.
  
  
  • (Idea) We could go with '-' instead because it is clearly horizontal.
  
  
  • (Task) Tests are missing.
  
  
  • (Task) Docs are missing
    
    
    
    
    
    • module:core/editor/editorconfig~EditorConfig#toolbar needs to be updated.
    
    
    
    • Probably also we could mention this in https://ckeditor.com/docs/ckeditor5/latest/builds/guides/integration/configuration.html
    
    
    
  
  
  • The configuration using '/' looks like this:
  
  

toolbar: {
    items: {
        'bold',
        'italic',
        'underline',
        'strikethrough',
        '/',
        'alignment',
        '|',
        'numberedList',
        'bulletedList',
    }
}

• (Feedback needed) Let's make sure '/' is the right direction (future-proof). For instance, we're going to implement proper button groups sooner or later. Would the following make sense?

toolbar: {
    items: {
        { name: 'basic styles', items: [ 'bold', 'italic', 'underline', 'strikethrough' ] },
        '/',
        { name: 'other group', items: [ 'alignment', '|', 'numberedList', 'bulletedList' ] }
    }
}

• (Task) Let's figure out the default toolbar layout for document build. I went with something like this and let's say I'm not thrilled about this

Even if we went back to the full-height separators and added some border to the line separator, this does not look great

• I tried adding more features to the toolbar and IMO it looks better (for instance, individual alignment buttons). I also slightly re-arranged the buttons for better semantics.
  
  
  
  • Unfortunately, this will increase the side of the build.
  
  
  • OTOH this kind of build should offer all features a traditional native word processor would offer so this course of action makes sense to me.
  
  
  • This layout looks good enough to me.
  
  

• (Problem) I wanted  ToolbarView to be smarter and disable automatic item grouping whenever the line break appears in the configuration.
  
  
  
  • It turned out not so simple because the behavior of the toolbar (static vs. auto-grouping) is applied in the constructor when the items of the toolbar are unknown.
  
  
  • ToolbarView#fillFromConfig() can be called at any time (but after constructor() and render()) and only then the toolbar would know if it can enable auto-grouping or not depending on the presence of line breaks in the config.
  
  
  • Re-writing the logic so the toolbar can adapt to the config when it's already rendered is a major refactoring of the entire component. We didn't see that coming when we first implemented auto-grouping.
  
  
  • TBH for this all to make sense, the toolbar would need an ability to switch between auto-grouping and static (break-compatible) layout on every change of it's #items collection. Developers can use ToolbarView#fillFromConfig() but they may also fill the toolbar with items manually by adding to the #items collection. It could be that the third button added to the toolbar is a line break and the auto-grouping feature must be from now on disabled.
    
    
    
    
    
    • I estimate this is at least a couple of MD of work and I'd rather see this as a follow-up.
    
    
    
  
  
• (Problem) I tried multi-line toolbar in InlineEditor (but the same applies to the ballon editor etc.) and it turns out all floating toolbars use the .ck-toolbar_floating class that disables flex-wrap. Without flex-wrap multi-line toolbars won't break at a specific point.
  
  
  
  • Disabling flex-wrap is necessary for auto-grouping (enabled by default) to work, though. So here we've got a problem.
  
  
  • I thought this would be as easy as getting rid of the .ck-toolbar_floating class whenever a line break appears in ToolbarView#items but the class is added externally by editor UI implementations (like InlineEditorUIView) via extendTemplate() and ToolbarView does not know about it.
  
  
  • The only solution I see now is passing a property like isFloating to the ToolbarView constructor and allowing the toolbar to decide whether the CSS class is added
    
    
    
    
    
    • .ck-toolbar_floating would be set only when constructorOptions.shouldGroupWhenFull === true and constructorOptions.isFloating === true
    
    
    
  
  

[Reinmar]

I went with '/' for toolbar break in the toolbar configuration.

That's what CKE4 uses, so it may be a simpler upgrade path.

• (Idea) We could go with '-' instead because it is clearly horizontal.

Makes sense too.

• (Feedback needed) Let's make sure '/' is the right direction (future-proof). For instance, we're going to implement proper button groups sooner or later. Would the following make sense?

It worked for CKE4 (that had groups too), so it seems fine.

• I tried adding more features to the toolbar and IMO it looks better

Yeah, I think I agree that there needs to be a balance between a too empty toolbar and too wide. In the end, this will be the integrator's choice anyway as they will choose the included features, but we should have some reasonable defaults.

I don't have problems with extending the document build. The demo that we have on https://ckeditor.com/ckeditor-5/demo/#document has more features anyway. I'd run this by @wwalc as he'll have the most input.

(Problem) I wanted  ToolbarView to be smarter and disable automatic item grouping whenever the line break appears in the configuration.

What if fillFromConfig() checked the current state of the toolbar once it is about to add the '-' item and log a warning? That's not going to catch all situations and it will not resolve them automatically, but will give the developer a cue in the most probable scenario.

• The only solution I see now is passing a property like isFloating to the ToolbarView constructor and allowing the toolbar to decide whether the CSS class is added

Sounds reasonable.

[oleq]

TODOs

• [x] Ask @wwalc for an opinion about the changes in the document build.
• [x] Implement warning in ToolbarView#fillFromConfig() when the toolbar has item grouping enabled to let developers know why declarative breaks don't work.
• [x] Implement the isFloating constructor option in the ToolbarView.
  
  
  
  • [x] Migrate all occurrences of extendTemplate() that add .ck-toolbar_floating to the constructor option API.
  
  
  • [x] Make ToolbarView smart enough to add the CSS class in the template only when constructorOptions.shouldGroupWhenFull === true and constructorOptions.isFloating === true to avoid situations when the declarative toolbar breaks don't work because of this CSS class.
  
  
• [x] Write tests.
  
  
  
  • [x] In ckeditor5-ui
  
  
  • [ ] ~In ckeditor5-build-decoupled-document~ (removed during Nov 18th F2F talk)
  
  
• [x] Write docs
  
  
  
  • [x] (Nov 18th F2F talk) Create the "Toolbar configuration" guide with different kinds of toolbars and different configs (multi-line, grouping, etc.)
  
  
  • [x] Update module:core/editor/editorconfig~EditorConfig#toolbar (how to create multi-line toolbars?)
  
  
  • [x] Update module:ui/toolbar/toolbarview~ToolbarOptions (what does isFloating do? how does it work together with shouldGroupWhenFull?)
  
  
  • [x] Update the migration guide https://ckeditor.com/docs/ckeditor5/latest/builds/guides/migrate.html. Probably worth mentioning in the "toolbarGroups" section.
  
  
  • [x] Update toolbar config in https://ckeditor.com/docs/ckeditor5/latest/features/pagination.html to take advantage of the multi-line toolbar.
  
  
  • [x] Update toolbar config in https://ckeditor.com/docs/ckeditor5/latest/features/export-pdf.html to take advantage of the multi-line toolbar.
  
  
  • [x] Probably the same in https://ckeditor.com/docs/ckeditor5/latest/features/pasting/paste-from-word.html
  
  
  • [x] And in https://ckeditor.com/docs/ckeditor5/latest/features/pasting/paste-from-google-docs.html
  
  
• [x] Ask QA for help.
• [x] Ask @usqr to update the document editor demo on ckeditor.com (postponed after the release).
• [x] We need to support line breaks in https://ckeditor.com/ckeditor-5/online-builder/. It's not a blocker for the release, but should be resolved in a near future. The challenge here – if a line break was added, we need to set shouldGroupWhenFull to false automatically in the generated build's config.
• [x] Handle #5586.
• [x] (Nov 18th F2F talk) Revert changes in ckeditor5-build-decoupled-document; we're not going to update the default toolbar config/featureset until we collect some on-line builder stats.

[Reinmar]

Pinged @wwalc for feedback. Let's gather it before we'll move forward to avoid surprises.

[oleq]

Food for thought: here's the document editor build in action on a 1280x800 laptop screen 

• with the declarative multi-line toolbar 
• and toolbar items flowing to the next line

[Reinmar]

Another TODO: we need to support line breaks in https://ckeditor.com/ckeditor-5/online-builder/. It's not a blocker for the release, but should be resolved in a near future.

[wwalc]

• Let's go with declarative multi-line toolbar for the document editor build. I will recheck what features could land there taking this occasion that we will have more space there.
• The last design looks the best IMHO (the one without line separating toolbar lines).
• Our online builder will have to support multiline toolbar - there may a simple way to implement support - e.g. just render 3-4 pseudo-toolbars instead of one and include them in the configuration if at least one button is added in a toolbar (well, a little bit troublesome may be rendering the initial state of the toolbar in the online builder UI if one enabled all plugins). Such a pseudo toolbar could be grayed out in the UI until at least one button is placed in it. Anyway, just a quick idea, there are probably many ways how we can quickly add it.
  
  
  
  • As for / vs - I'd roll a dice, because / will be less confusing for users upgrading from CKEditor 4, while - seems to be more intuitive.
  
  
  • While we agree that there are many problems still left to be resolved (mobiles etc.), we can just ignore them for now. E.g. I imagine that on systems where the document editor is used, a minimum length of the document (and the space for the editor toolbar) will be enforced, so a proper toolbar configuration that takes into consideration the minimal space for the toolbar will prevent users from seeing an editor with malformed toolbar. I'd just start gathering ideas on what direction we could take in the future with the toolbar further, but keep it in the backlog due to other priorities.
  
  

[Reinmar]

BTW, @oleq what about #5586? Can we add it to the TODOs?

[pkwasnik]

In paste from word/google and export to pdf we have only one/two extra buttons, so the multiline toolbar will look not so good. I propose just to remove those buttons to make it fit. I could also go the other way and add more buttons, but I am not sure if we have to show multiline in those demos. One line always looks better IMO.

VS

OR

About the separator: both are good, but my vote is slightly towards -. / looks too similar to |. When creating the config it is easier to see the difference when there is -.

[Reinmar]

TODO:

• Document the line separator in the migration guide.
• Link to the new toolbar guide from the configuration guide.
• Move all works on the documentation to a separate ticket.

[pkwasnik]

Follow up about "Toolbar configuration" guide: https://github.com/ckeditor/ckeditor5/issues/8513

EDIT: I've closed follow up, as I've included docs in this branch.

[oleq]

Can we address https://github.com/ckeditor/ckeditor5/issues/6146#issuecomment-732006953? This is the main reason why we're working on the multi-line toolbar. 

Personally, I'm for a multiple-line declarative toolbar with as many features as possible to mimic the document build. 

cc @Reinmar

[vishwakarmanikhil]

when has this issue gone be solved? waiting for the next update of ckEditor5.

[AnnaTomanek]

Follow-up for the docs: #8493

[pkwasnik]

Follow-up for supporting line breaks in online builder: #8567

Follow-up for updating the document editor demo: cksource/bigbang-ckeditor.com#2217