Add support for quick actions to the WYSIWYG editor

Hi everyone,

For the past few weeks @douakli and I have been working on adding support for quick actions to the WYSIWYG editor. By quick actions we mean the ability to perform WYSIWYG editing operations using only the keyboard but without the need to remember shortcut keys. You can find more about this at Quick Actions (Proposal.QuickActions) - XWiki . We’d like to include this new feature in XWiki 15.5. In short, this means:

  • advertising the ‘/’ shortcut keys for quick actions on focused empty lines (paragraph, list items, table cells)
  • enabling the ‘/’ shortcut key
  • exposing most of the current editing features as quick actions
  • exposing rendering macros directly in the quick actions panel, but also adding a ‘{’ shortcut dedicated solely to macros
  • adding a ‘!’ shortcut for quick image insertion (similar to ‘[’ quick link shortcut), exposing it on quick actions panel of course

Here’s a preview of how it will look like:

quick-actions

And here’s how table editing can be made faster:

quick-actions-table

+1 to include this in XWiki 15.5.

WDYT?

Thanks,
Marius

3 Likes

+1 looks very good, and looking forward to try it out!

Will it be possible to contribute a custom provider from an extension?

Yes, it’s possible to define custom quick actions both through configuration (e.g. from the CKEditor administration section) and through code (API) from a custom CKEditor plugin provided by an XWiki extension.

1 Like

It looks really nice to use! Definitely +1

I’m going to push my changes on master in order to see if they break anything, but of course I will revert if someone has doubts about this feature or how it was implemented.

+1 for me :slight_smile:
As for advertising quick action functionalities, I think it might be relevant to add a new Help.TipsPanel to the xwiki-platform-help-ui module.
tipsPanel

How does this interfere with normal editing? E.g., if I want to type xwiki/2.1, is there a way to dismiss the actions? Also, it seems to me in the video that the first action is automatically selected. So when I type xwiki/2.1 and then press enter, would an action be executed (assuming an entry matches “2.1”)?

I’m asking because while I think the quick actions could be very useful, I also fear they could interfere with regular typing and I think this interference should be kept to a minimum in order to not to be annoying. So I think at least a) it should be possible to easily dismiss the action (e.g., using escape) such that they won’t come back until the text time you type / and b) at least when the match is only fuzzy, no action should be executed unless the user presses some key like a down arrow (or tab) to move into the actions list.

Apart from this, +1.

@CharpentierLucas do you have any idea about the accessibility implications of this feature? Are the completions announced by screen readers? Is there anything to consider regarding regular editing experience (e.g., users of a screen reader might not be aware that they are executing an action when, e.g., pressing “return” to create a new paragraph)?

The feature should not bring any specific problem, it will all depend on the implementation. I checked out quickly how the drop-down for completion was implemented (draft PR). It’s using editor.config.mentions which is itself based off the ckeditor autocomplete list. I didn’t check further but if there’s accessibility concerns with this drop-down it’s nothing new and we’ll have to take care of it at one point anyway. The use case is similar so I think using the same structure won’t be a problem when it comes to semantics.

I think this doesn’t change much in regards to editing, all the shortcuts do actions that could already be done (in more time) AFAIK. I’ll have to check how the advertising of the feature on empty lines is read out, but for the drop-down if we use correct semantics (id est follow an accessible pattern like Editable Combobox With List Autocomplete Example | APG | WAI | W3C) I’m pretty sure we’re good. There might be a couple special interaction not used in this pattern, but they have their aria implementation. Using aria-attributes correctly should solve those cases. All that is work that already needs to be done once for mentions, so I don’t have any problem with including this feature.

Created a new ticket for the accessibility of the mention drop-down: XWIKI-20947.

+1, I like the idea very much

Thanks,
Alex

Indeed, since we have a tip for the mention shortcut it makes sense to also add a tip for the slash shortcut.

Yes, you can use the Escape key to close the quick actions drop down. But, in our implementation typing afterwards may still open the drop down (if what you typed has a match). From the applications I checked:

  • Notion, Confluence and Affine don’t re-activate the quick actions drop down, you have to type ‘/’ again
  • GitHub and Microsoft Loop re-activate the quick actions drop down if what you type after Escape has matches

I believe keeping the quick action drop down closed after Escape until you type ‘/’ again is the correct behaviour so I’m going to fix this in our implementation.

Yes. All the applications I checked (see the design page) behave like this: the first suggestion is selected by default and pressing Enter selects that suggestion. Moreover, this is also consistent with the behaviour of other auto-suggest widgets we use in XWiki or anywhere else.

There is something though that not all applications agree on: should any ‘/’ trigger the quick actions or only when it follows a word boundary?

  • Notion, Affine: ‘/’ triggers the quick actions even when there is text right before it (as in your example)
  • Confluence, Microsoft Loop: you need to be a the start of the line or leave a space (word boundary)
  • GitHub: you have to be a the start of the line

I find GitHub’s behaviour too strict, as it prevents you to use quick actions to insert in-line content, like a link or emoji. But I’m open to implement the second option (require word boundary) if others think this is better.

Agreed. Escape already closes the drop down but I’ll make it stay closed until the next ‘/’.

I don’t agree with this. Users almost never type the full action name. You stop typing when the first suggestion is the one you’re looking for. This is also consistent with the behaviour of an auto-suggest widget. For instance, if I want to insert a table it should be enough to type ‘/ta’ and press Enter (provided the Table action is the first suggestion). I don’t like what you propose because:

  • it makes quick actions slow
  • it’s not consistent with other auto-suggest widgets
  • it’s not consistent with itself: users won’t understand why sometimes the first suggestion is selected, and some other times it’s not

Thanks,
Marius

1 Like

This looks great, well done to both of you!

I have some questions about the extra shortcut keys {, ! and [. I thought that the point of introducing / was to reduce the namespaces we were using and provide a single one. Now it means 4 special characters that have special meanings. This raises 2 questions:

  • Can the user type the a sentence with these characters without having to press any other extra key to dismiss anything?
  • Where do we stop adding specific characters? For example, with a similar logic, why not add * too for bold, - for lists, to allow for fluent typing (I’m asking because AFAIK, Confluence supports that, see Confluence Wiki Markup | Confluence Data Center and Server 8.3 | Atlassian Documentation). Do we need them because / is not fast enough (one more char to type)?

Thanks

By “fuzzy” I didn’t mean matching a prefix but a real fuzzy match that doesn’t match any substring in the title of the action. I haven’t tried the feature yet so I don’t know what kind of “fuzziness” is supported but my understand is that you’re using a fuzzy matching library that, e.g., matches “lock” when you type “look”. When applying this also to the description of the action, I could imagine that pretty much any word after a / would match something. Also, do you stop matching on the next word boundary or how long does this continue? I agree that it is not very consistent if the selected state depends on the type of match and this will be surprising for users as they won’t expect or understand the difference.

So I would suggest just trying this out and then we’ll see if it disrupts the typing flow of users. In the worst case, we could move to another activation trigger like // that is less likely to occur in regular text or use less fuzzy matching.

You forgot @ for mentions and : for emojis. And no, we never discussed about removing shortcuts (for mentions, links or any other feature). That’s not the point of the slash shortcut. Having a slash shortcut that exposes features such as linking and mentioning doesn’t mean we have to slow down power users by preventing them from using existing shortcuts:

  • force them to type /men + Enter instead of simply @
  • force them to type /lin + Enter instead of simply [

Note that all these shortcuts you mentioned (maybe except {) provide suggestions that are not directly available in the slash (quick actions) drop down, so they help power users speed up the editing.

The auto-suggest drop down doesn’t prevent the user from typing. The only issue is if you press Enter while there is a suggestion (e.g. quick action) selected in the drop down. This will activate the suggestion, inserting some content or executing some command. If you don’t want that then you need to use the Escape key to close the drop down.

I don’t know. I haven’t seen any complains from our users that we have too many shortcut keys. If a feature is used often and we can introduce a shortcut key to help the power users without annoying the simple users then I don’t see why we shouldn’t do it.

We already have a shortcut for Bold, that is well known. I’m not sure adding another one brings much value. As for lists, I don’t know. If our users will ask for it or if someone is willing to sponsor it then I guess we can implement it, but I don’t think it brings as much value as the link or mention shortcuts, that provide you with information that is not always easy to get (e.g. page reference or user reference).

It’s not only one more char to type, e.g. you need to type /men + Enter (i.e. you usually type until the first suggestion is the one you’re looking for). I think that:

  • / will be used by simple users, that don’t want to bother remembering other shortcuts, or at least until they discover the other shortcuts (that are shown in the slash drop down)
  • dedicated shortcuts will be used by power users, once they learn then.

Thanks,
Marius

Yes, we’re using https://fusejs.io/ for fuzzy searching. We experimented with many configurations but we settled to this one Quick Actions (Proposal.QuickActions) - XWiki :

  • we search in action id, name and description, as well as in group id and name
  • action name and description, as well as group name are split by white-space into tokens in order to give more weight to word prefix matches
  • We allow one character mismatch in 4 (i.e. match at least 3 characters when the input text is 4 characters)
  • we’re matching only the first 25 characters, which is fine considering that we split the indexed information into tokens (by white-space)

So yes, “look” will match “lock”.

Not really. Chances are indeed high to get an unrelated suggestion when you type a few letters, e.g. less than 4, but once you type more letters then unrelated suggestions are pretty rare (because we don’t split the search text into tokens).

We don’t stop at word boundary. This was actually a requirement to be able to continue searching even after pressing space for instance. ATM we stop after 30 characters from the slash, but I’m open to decrease this if we notice problems.

fusejs gives me an aggregated score based on the field weights (you can have an exact match in one field and a fuzzy match in another one, or even different matches in the same field) so it’s not straight forward to determine if there was an exact match or not. But even if it were, I still don’t like the inconsistency.

Thanks,
Marius

Had forgotten @ indeed. As for :, I didn’t know about it :slight_smile:

Indeed, I don’t remember any either. Let’ see what users say after we add the 3 new shortcut keys ({, ! and /). We’ll have 5 in total. I hope that the “enter” thing is not going to be an issue too often. Using an exclamation mark at the end of a sentence in quite common for example.

Now, I think that the shortcuts you added make sense not because they’re used more often (we don’t know that since we’re not measuring how often a “feature” is used ATM. It could well be that for example list items are used more often than images. At some point we should implement something like Data Sharing | IntelliJ IDEA Documentation), but because they’re more complex features to use and having autocompletion directly in the editor for them is a great timesaver.

Thanks

Note that we’re going to drop the { shortcut for now because it doesn’t bring anything new compared to the / shortcut (it only adds more work). The macros will be listed in the quick actions (slash) drop down.

ok, thanks for the info. I guess that makes it a bit inconsistent with the other actions which have a specific shortcut. How do you differentiate a macro name from a quick action name? For example imagine a macro named list. I guess in this case that the quick action suggestions will propose both to create a list and to insert a list macro? But then the user might need to use the up and down arrow to choose the macro, no? Or does it mean macros will always be listed first in the quick actions suggestion list? Thx

I don’t see the inconsistency. The quick actions that have a dedicated shortcut need additional information (e.g. the page name or the user name) that is not present in the quick actions drop down (we can’t list all users or all pages in the quick actions drop down, as we do with macros). Basically we need to choose:

  • either define a dedicated shortcut (e.g. {) and have only an entry point in the quick actions down down (e.g. “Browse Macros”)
  • or put everything in the quick actions drop down and thus remove the need for a dedicated shortcut

Why should we differentiate? Inserting an info message (macro) is not different than inserting a heading. Both quick actions insert some HTML in the editing area. Simple users don’t care that an info message is implemented with a rendering macro under the hood while the heading has a dedicated wiki syntax. The user will type / and search for a feature not for a macro.

First of all each quick action has a description, so the user will decide based on it what action to take (if the name is the same). Moreover, the search looks also in the quick action description so you can adapt the search to match the target description, although it may be easier to use the Down/Up arrow keys instead. This is not different than typing /list and choosing between numbered and bulleted list.

Then, if these two actions really provide the same feature then an administrator can remove one of them through CKEditor configuration (there’s a configuration to remove existing quick actions and to add new quick actions). If they provide different features, then the user will have to choose.

The order varies:

  • for an empty search (just type /) the order depends on the quick action group and the insertion order inside that group;
    • if the 2 actions are in different groups then the order depends on the group order
    • if the 2 actions are in the same group, then the order is the insertion order, and macro quick actions are inserted after the standard quick actions because they require additional HTTP requests to fetch the macro list and macro descriptors.
  • for a non empty search (e.g. /list) the order depends on the search score (fusejs)
    • if the 2 actions are in different groups then the order is also influenced by the group score which is the max score inside the group
    • if the 2 actions are in the same group then the order is based only on the search score.

Thanks,
Marius

ok makes sense, thanks for the details Marius. We can iterate as we get feedback fro users.