This issue has been created
 
 
XWiki Platform / cid:jira-generated-image-avatar-0f57ef15-259d-450a-99f7-0c96c3403d02 XWIKI-25018 Open

The example macro from the Help application should be internal and fixed

 
View issue   ยท   Add comment
 

Issue created

 
cid:jira-generated-image-avatar-ac91afc9-d95c-446c-8100-04bb80958d0a Charpentier Lucas created this issue on 17/Sep/26 16:54
 
Summary: The example macro from the Help application should be internal and fixed
Issue Type: cid:jira-generated-image-avatar-0f57ef15-259d-450a-99f7-0c96c3403d02 Improvement
Assignee: Unassigned
Components: Help
Created: 17/Sep/26 16:54
Priority: cid:jira-generated-image-static-major-525dd22a-2a54-4951-9c60-35494a1b7470 Major
Reporter: Charpentier Lucas
Description:

The example macro shipped by the Help application (Help.Code.ExampleMacro) is only meant to build the Help pages: it is used 19 times across the Help.Macros.* pages to show a rendered example next to its source. It is not documented anywhere for end users, yet it is exposed to them like any other macro, which adds noise when inserting a macro. See the analysis in https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros#Hexample

Problems

  • The macro default category is Formatting, so it is listed in the WYSIWYG macro picker and in the quick actions next to user-facing macros.
  • When inserted from the WYSIWYG editor, its content cannot be edited, even though the content is mandatory and is the only input of the macro.
  • The "Example" and "Source" tab labels are hardcoded in English instead of using translation keys.
  • The tab ids are computed from the content hash plus a random number between 1 and 100, so two examples on the same page can end up with the same id and break tab switching.
  • The border color of the tab content is hardcoded to #DDD instead of following the color theme.

Proposal

  • Move the macro to the Internal category so that it is hidden by default from the macro picker. Hiding it from the quick actions as well depends on XWIKI-21063.
  • Translate the tab labels.
  • Generate unique tab ids.
  • Use a color theme variable for the border.