This issue has been created
 
 
XWiki Platform / cid:jira-generated-image-avatar-e42d0f9a-86fa-4528-b364-69446fdebd07 XWIKI-25444 Open

Allow macros to declare search keywords for Quick Actions and the Insert Macro dialog

 
View issue   ยท   Add comment
 

Issue created

 
cid:jira-generated-image-avatar-7bbe59fd-c682-4da7-af78-872eafb7f207 Charpentier Lucas created this issue on 21/Oct/26 18:08
 
Summary: Allow macros to declare search keywords for Quick Actions and the Insert Macro dialog
Issue Type: cid:jira-generated-image-avatar-e42d0f9a-86fa-4528-b364-69446fdebd07 Improvement
Affects Versions: 17.10.14, 18.8.0
Assignee: Unassigned
Components: CKEditor, WYSIWYG Editor
Created: 21/Oct/26 18:08
Priority: cid:jira-generated-image-static-major-d993805a-49d1-42e6-9b82-cfc25783c859 Major
Reporter: Charpentier Lucas
Description:

Users look for a macro with the word they have in mind, which is often not its name: "callout" or "note" for a message box, "formula" or "latex" 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 the user can conclude that XWiki has no such macro.

Steps to reproduce

  1. Edit a page with the WYSIWYG editor.
  2. Type /latex, then /equation, then /callout.

Expected

/latex and /equation list the MathJax macro first, and /callout lists the message macros.

Actual

/latex lists Template, and /equation and /callout list nothing.

The WYSIWYG usability audit of the macros found this on 51 of the 67 macros reviewed, nearly always for a common synonym.

Proposal

  • Let a macro declare search keywords, translated like its name and description, for example with a rendering.macro.<id>.keywords translation key holding a comma separated list. Each language then gets its own words, and wiki macros can declare them the same way.
  • Return the keywords with the name and description in the macro list of XWiki.WYSIWYG.MacroService, and match them in Quick Actions and in the filter of the Insert Macro dialog.
  • Fill the keywords of the macros of XWiki Standard. The synonyms recorded by the audit for each macro are a starting list.

Notes

  • The Insert Macro dialog keeps the macros whose name or description contains the typed text, see filterMacros in macroSelector.js. Quick Actions runs a fuzzy search on the identifier, the name, the words of the description and the group, see the search configuration of the xwiki-slash plugin.
  • Adding the synonyms to the descriptions would make them match, but it would make the descriptions longer and less useful as a summary of what the macro does.