Search keywords for macros in Quick Actions and the Insert Macro dialog

Development
1

Context

Users look for a macro with the word they have in mind, which is often not its exact name: “callout” or “note” for a message box, “latex” or “formula” for MathJax, “columns” for Container, “subpages” for Children, “carousel” for Gallery. Quick Actions and the Insert Macro dialog only match the identifier, the name and the description of a macro, so these words give no result, and users can conclude that XWiki has no such macro. Today, /latex lists Template, and /equation and /callout list nothing. See XWIKI-25444.

Adding the synonyms to the descriptions would make them match “as expected”, but the descriptions would get longer and less useful as a summary of what the macro does.

Proposal

Let a macro declare search keywords, translatable like its name and description:

  • Declared through a new rendering.macro.<id>.keywords translation key, holding a comma separated list, e.g. rendering.macro.mathjax.keywords=latex, equation, formula, math.
    It sits next to the existing .name and .description keys, so Java macros declare it in their ApplicationResources and wiki macros in a translation document, and each language gets its own words.
  • The macro keywords are never displayed to the end user (except in the doc maybe).
  • This proposal is just for the mechanism, not the exact values we want for each macro.

No change to the rendering API is needed. The other option would be a keywords field on MacroDescriptor in xwiki-rendering, used as the untranslated default, like the name and description. I’d keep it for later, if extensions ask for it.

Opinion

+1 for these new translation keys and their use in the macro pickers/filters because:

  • This implementation reuses a structure every macro already follows for its name and description.
  • Keywords are very related to the language, so they belong in the translations, and translators can add the synonyms people really use in their language.
  • It’s cheap and safe: a macro without the key behaves exactly as today.

Conclusion

  • Do you agree to let macros declare search keywords with a rendering.macro.<id>.keywords translation key?
  • Do you agree to match them in both Quick Actions and the Insert Macro dialog? Is there any other place where it should be used?

Thank you in advance for sharing your opinion!
Lucas C.

2

I’m very +1 for the general idea in Quick Actions and Insert Macro dialog.

So is it possible to declare my own keywords in my wiki with adding them to a translation key via XWiki.TranslationDocumentClass object in one or both ideas?

I would like the possibility to enhance the keywords to find macros very much. Find them by their original (english) keywords too would be best.

3

I planned on using it for both places. Note that it’s only for macro addition.

4

So it will be a feature of the MacroService (xwiki-platform-wysiwyg-ui, which needs to add the translated keywords to the returned macro descriptors JSON) and the WYSIWYG editor implementation (both CKEditor and BlockNote, which need to take the keywords from the retrieved macro descriptors JSON into account when searching for macros).

MacroService also returns macros that are not installed. These are indexed by the Extension Manager. An extension can declare in its POM the macros it provides:

<!-- Indicate to the XWiki Extension Manager that this extensions contributes a Macro component -->
<xwiki.extension.components>
  org.xwiki.rendering.macro.Macro/simple-example
</xwiki.extension.components>

I’m fine to start by supporting keywords only for installed macros.

Thanks,
Marius