Macro integration UX proposal

[tkrieck]

Hi everyone,

This proposal comes as a two-in-one because it is for Cristal, but also for XWiki. For Cristal this is, of course, the first implementation, but in XWiki we have some Jiras regarding this subject as well. The proposal is the same for both.

We have three processes in here which are important.
1 - Adding a macro
2 - Configuring the macro
3 - Moving the macro

Adding a Macro

This is already done as a slash menu. It is the same as selecting the heading styles, inserting attachments and so on. This menu features a list of macros and blocks and a search bar at the top.

It also the default that comes with BlockNote, TipTap and others, a pretty standard in block level editors right now.

Slash menu

Configuring the Macro

Configuring the macro however is where things get different. On XWiki this is done by double-clicking a macro, but this is visually hidden, and users needs to discover this feature on their own.

Code Snipped macro in an XWiki editor

To make it more friendly, I propose that we present a toolbar above every macro when they are focused.

This toolbar should not occupy its own space in the flow of text but rather float above it, this is only for edit mode of course. This toolbar should have the macro name, a drag handle (for moving), configure and delete icons and also a way of moving by touching, clicking or selecting via keyboard (I propose two arrows for that).

Example of macro with the toolbar visible

Anatomy of the Toolbar

Visiblity of the toolbar
When the macro is not focused, this toolbar should be invisible, giving way for the text that may be behind it when active. A blue border helps the user distinguish where the macro content starts and ends.

Examples:

Focused Macro

Unfocused Macro

To help the user understand what piece of content can be selected, I propose a light shade of blue on hover

Hovering a macro block

Moving Macros

There are two ways of moving a macro between blocks, drag-and-drop and clicking (perhaps a keyboard shortcut also? @CharpentierLucas ).

Drag-and-drop

The same as it works in XWiki right now. Starting the drag on the drag handle and moving to the new place. When dragging the contents of the macro disappears and only the toolbar is visible, this is because the macro can have big dimensions and make it difficult to move. The destination block should be visually marked.

Example of drag and drop move

Move buttons

Another way of moving macros is using the move buttons featured on the toolbar. This is mostly for accessibility reasons, as drag and drop can be very taxing on some users.

Empty Macros

It is important to clearly show the user where in the document the macro is, but is empty. For that I propose a standard block, with a light shade stating the Macro icon, name. Hovering this empty state show the remainder elements (config, delete, move, etc.).

Two empty Macros, code and image

When hovering or on touch the rest of the buttons are visible:

When selecting the cog icon the config dialog should appear. This dialog will be different between each macro, so it’s difficult to predict all the fields in this proposal. @amilica has a pretty nice ongoing proposal for tackling issues inside this dialog.

Configuration dialog example

It is important to make sure that the main buttons of this dialog remain visible even if a scrollbar is present.

Scrolling example

Nested Macros

Macros can be nested (a code macro inside an info box, for example). In this case, all of the above rules stay true, and two toolbars should be present. Here it’s even more important to have the macro name visible to differentiate them.

Finishing thoughts

I think this covers most of the usability use cases for the macro integration, but let me know if you have some more.

One last thing that I would like to show you is that I made an alternative view for the slash menu, featuring a grid of blocks and macros.

This layout has the advantage of showing more blocks in a given space, but also has the disadvantage of making the user eyes move in two dimensions instead of just one. I am unsure if this is the right way to go, so give me your thoughts please.

Grid layout for blocks example

---

That’s it for now, thank you very much for reading. As always, I welcome any feedback that you might have.

Thiago

[mleduc]

Thanks for the proposal. Looks good overall!

@tkrieck

Slash menu

In this picture, I’m not sure to understand the Search field. In XWiki’s CKEditor and in Blocknote, the search query is usually directly following the / in the content of the page. So it the search field achieving something else?

@tkrieck

Regarding the up and down arrows. Editors typically already have their own way to move blocks around. I’m not sure want to duplicate this with our mechanism.
Though, we need to make sure the mechanism provided by the underlying editor is accessible. We also need to make sure we have a mechanism to move inline macros as well.

@tkrieck

This layout has the advantage of showing more blocks in a given space, but also has the disadvantage of making the user eyes move in two dimensions instead of just one. I am unsure if this is the right way to go, so give me your thoughts please.

I have doubts about that one. The two-dimensional aspect also makes it required to use 4 arrows (top bottom left right) instead of 2 arrows (top bottom) to navigate the suggestions.
Moreover, it takes more horizontal space, which might not be desirable for small screens (though this could be addressed with a special case for small screens)

A few other things I’d like to see discussed are:

1. In XWiki we have a modal to search specifically for macros, allowing to search by keywords and to filter by categories, is it something we’d like to keep having (possibly with a bit of restyling)?
2. How macros behave in inline mode.
3. I’m also wondering if it could be interesting to have some macro configuration available directly from the macro’s toolbar (the rest of the config would still be behind the cog button).

And topics that are not here but that could be interesting later:

1. ability to split a macro (e.g., transform a warning macro with two paragraphs into two warning macros with one paragraph)
2. ability to merge macros (e.g., transform two warning macros with one paragraph in a single warning macro with two paragraphs)

[CharpentierLucas]

@tkrieck

There are two ways of moving a macro between blocks, drag-and-drop and clicking (perhaps a keyboard shortcut also? @CharpentierLucas ).

We definitely need to think about an alternative for keyboard users and accessibility. AFAIK there’s no alternative way to move a large block of content at once (source-> Ctrl+C->Ctrl+V ).

The way we did this drag-and-drop alternative on XWiki Livedata columns is:

• Make sure the drag and drop handle is focusable. Semantically it should be a button.
• On the handle, we listen to some specific keyboard events. Here, AFAIK, we want to drag and drop mostly vertically, so we should listen to up and down arrows for example. When the arrow keys are pushed, move the block accordingly. The distance moved should be the same every time or at least be consistent (e.g. always between two other blocks).
• Add an explanation as a aria-description or aria-describedby so that AT users know how to use this handle as soon as they get on it.
• Make sure the interaction is described in documentation too. Most power users won’t read aria-describedby but might want to use this feature.

Thanks for researching this subject!

Lucas C.

[tkrieck]

@mleduc

In this picture, I’m not sure to understand the Search field. In XWiki’s CKEditor and in Blocknote, the search query is usually directly following the / in the content of the page. So it the search field achieving something else?

You’re right, I’ve modified my mock to use the standard, directly from the text:

@mleduc

Regarding the up and down arrows. Editors typically already have their own way to move blocks around. I’m not sure want to duplicate this with our mechanism.

From what I’ve seen, most editors rely on drag and drop. Now, there are accessible ways of moving blocks by keyboard shortcuts (ctrl+shift+arrows). The advantage of up/down icons is that there’s a visual cue for it (besides the drag handle). Perhaps we can simplify and go with the standard of the editor and check for feedback on this feature.

@mleduc

In XWiki we have a modal to search specifically for macros, allowing to search by keywords and to filter by categories, is it something we’d like to keep having (possibly with a bit of restyling)?

I don’t find that modal to be very usefull to be honest. The slash command does everything that the modal do in a more streamlined way. For example searching for development tools, in the slash command I can just type “development” and all appropriate macros are filtered. In the dialog I need to use the category field for it.

Slash command

Dialog

That doesn’t mean that we shouldn’t have a discrete icon on the toolbar, though (for visibility reasons) I would just open the same menu as the slash command.

@mleduc

How macros behave in inline mode.

I couldn’t find a complex macro inline on XWiki, most of them are just styling options, so I wouldn’t develop something too advanced for them (maybe just a button to remove the styling).

@mleduc

I’m also wondering if it could be interesting to have some macro configuration available directly from the macro’s toolbar (the rest of the config would still be behind the cog button).

That’s a good option, I think we could have a reserved space (and rules) about them. The reserved space would be contextual to the macro being edited of course, the fixed buttons should always remain in their places.

@mleduc

• ability to split a macro (e.g., transform a warning macro with two paragraphs into two warning macros with one paragraph)
• ability to merge macros (e.g., transform two warning macros with one paragraph in a single warning macro with two paragraphs)

That’s an interesting use case, but I guess it should only be available when two identical macros are selected, right?

@CharpentierLucas

AFAIK there’s no alternative way to move a large block of content at once (source-> Ctrl+C->Ctrl+V ).

I had to dig a bit but found the ctrl+shift+arrows on Notion and Blocknote.

@CharpentierLucas

The way we did this drag-and-drop alternative on XWiki Livedata columns is:

Thanks for the reminder. This is a UI paradigm that needs to have the same behavior as the one in the editor.

[mleduc]

@tkrieck

That’s an interesting use case, but I guess it should only be available when two identical macros are selected, right?

yes, or at least have some sort of compatibility check before offering to merge adjacent macros.

[vmassol]

@tkrieck

Adding a Macro

This is already done as a slash menu.

Are you proposing to drop the “insert macro” editor toolbar menu entry in XS and not having one in Cristal?

While the slash command is nice, it makes it also a bit less discoverable by users so I’m wondering if we need to keep the editor toolbar entry too.

EDIT: I see you’ve answered:

@tkrieck

That doesn’t mean that we shouldn’t have a discrete icon on the toolbar, though (for visibility reasons) I would just open the same menu as the slash command.

Also, while the slash command works fine when you know what you want to use, it could still be interesting to allow users to navigate in the list of available macros and filter by categories.

EDIT: You’ ve also answered:

@tkrieck

I don’t find that modal to be very useful to be honest. The slash command does everything that the modal do in a more streamlined way. For example searching for development tools, in the slash command I can just type “development” and all appropriate macros are filtered. In the dialog I need to use the category field for it.

That works when you already know the names of the categories And when there aren’t too many macros in a given category, no? (can I see all macros from a given category in the slash menu?)

What about browsing? If type slash, can I browse the list of all macros? Maybe typing /macro will list all macros? But the menu is limited in vertical size, no?

Now there’s another topic we’re missing here. We’ve already discussed in the past that we needed to improve the Macro dialog to display a preview of the macros with an example, so that the user can see what the macro does (similar to Confluence). See for example https://design.xwiki.org/xwiki/bin/view/Proposal/MacrosBrowser (see also https://community.atlassian.com/forums/image/serverpage/image-id/323495i75B6A5476BA15B03/image-size/large?v=v2&px=999 )

Could that be done with the slash menu?

And also to add different icons for different macros, but that’s doable in the slash menu too.

Thanks

[tkrieck]

@vmassol

That works when you already know the names of the categories And when there aren’t too many macros in a given category, no? (can I see all macros from a given category in the slash menu?)

What about browsing? If type slash, can I browse the list of all macros? Maybe typing /macro will list all macros? But the menu is limited in vertical size, no?

For visibility and browsing, the proposed way might not be ideal, indeed. It can work, but the category names are a bit lost.

What could be done is offering a compact version with the category names beside it. The macro list is still complete, so searching would work. Clicking the category names would scroll the macro list to the desired position.

@vmassol

Could that be done with the slash menu?

It could be done, but the menu would need to be much bigger to accommodate the images in place of icons.

The way Notion works with this is showing an image and a description inside a tooltip on mouse over. I don’t know if it’s a good pattern here but it’s an option to explore.

(Sorry for the screenshot in Portuguese, but for some reason Notion is not respecting my English preferences)