Uploaded image for project: 'XWiki Platform'
  1. XWiki Platform
  2. XWIKI-25018

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

    XMLWordPrintable

Details

    • Improvement
    • Resolution: Unresolved
    • Major
    • None
    • None
    • Help
    • None
    • Unknown

    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.

      Attachments

        Issue Links

          Activity

            People

              Unassigned Unassigned
              Lucas C Charpentier Lucas
              Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

              Dates

                Created:
                Updated: