|
| Description: |
The content reuse macros take generated or internal identifiers in plain text fields of the Edit Macro dialog: a heading id, a template file name, a UI extension or an extension point. The user has to know the exact value, and a typo renders nothing or an error.
The macros to change, with the file where most of the fix is done:
* display: [DisplayMacroParameters.java|https://github.com/xwiki/xwiki-platform/blob/master/xwiki-platform-core/xwiki-platform-display/xwiki-platform-display-macro/src/main/java/org/xwiki/rendering/macro/display/DisplayMacroParameters.java].
* include: [IncludeMacroParameters.java|https://github.com/xwiki/xwiki-platform/blob/master/xwiki-platform-core/xwiki-platform-rendering/xwiki-platform-rendering-macros/xwiki-platform-rendering-macro-include/src/main/java/org/xwiki/rendering/macro/include/IncludeMacroParameters.java].
* template: [TemplateMacroParameters.java|https://github.com/xwiki/xwiki-platform/blob/master/xwiki-platform-core/xwiki-platform-template/xwiki-platform-template-api/src/main/java/org/xwiki/template/macro/TemplateMacroParameters.java].
* uiextension: [UIExtensionMacroParameters.java|https://github.com/xwiki/xwiki-platform/blob/master/xwiki-platform-core/xwiki-platform-uiextension/xwiki-platform-uiextension-api/src/main/java/org/xwiki/uiextension/macro/UIExtensionMacroParameters.java].
* uiextensions: [UIExtensionsMacroParameters.java|https://github.com/xwiki/xwiki-platform/blob/master/xwiki-platform-core/xwiki-platform-uiextension/xwiki-platform-uiextension-api/src/main/java/org/xwiki/uiextension/macro/UIExtensionsMacroParameters.java].
The main problems:
* The section of display and include is the generated id of a heading of the chosen page, like HMyHeading, which the user has to work out: the headings of that page could be offered, so the list depends on the page field.
* The template, UI extension and extension point are identifiers that XWiki knows at runtime, which a searchable list could offer to the developers who use these macros.
A value outside these lists must also fail when the macro renders, with an error that names the parameter and lists the accepted values, instead of being ignored or giving a technical message.
h2. Depends on
Most of these fields cannot be offered before these generic changes, each giving the macro the means to declare the expected value:
* XWIKI-23045, which lets a parameter get its values from a provider, with or without custom values.
* XWIKI-25180, which lets a parameter depend on another one, whose value its list of values follows.
h2. KOs covered
||Macro||Criterion||Parameter||Problem||Depends on||
|[display|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/display/]|C4 input-assistance|{{section}}|A plain text field for a generated heading id, while the headings of the chosen page could be offered; a heading with accented letters gives an id like HCafE9.|XWIKI-23045, XWIKI-25180|
|[include|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/include/]|C4 input-assistance|{{section}}|A plain text field for a generated heading id, while the headings of the chosen page could be offered.|XWIKI-23045, XWIKI-25180|
|[template|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/template/]|C4 input-assistance|{{name}}|A plain text field for the exact file name of a template, extension and case included: a typo renders nothing. The templates of the skin, the filesystem and the classloader could be offered.|XWIKI-23045|
|[uiextension|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/uiextension/]|C4 input-assistance|{{id}}|A plain text field for the exact identifier of a UI extension: a typo gives an error. The UI extensions of the wiki, with their extension point, could be offered.|XWIKI-23045|
|[uiextensions|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/uiextensions/]|C4 input-assistance|{{extensionPoint}}|A plain text field for the exact identifier of an extension point: a typo renders nothing. The extension points that have extensions could be offered.|XWIKI-23045|
|[template|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/template/]|E2 errors|{{name}}|An unknown name, a wrong case or a blank name renders nothing, with no message, and name="" gives a NullPointerException message. Partly covered, see below.| |
|[uiextension|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/uiextension/]|E2 errors|{{id}}|An unknown identifier gives "Failed to find an extension id id [...]", which repeats "id" and speaks of an extension instead of a UI extension, and id="" renders nothing, with no message. Partly covered, see below.| |
h2. Impact found on macro fluidity
These 5 7 KOs come from the [WYSIWYG usability audit of the macros|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/], under the criterion criteria C4 input-assistance and E2 errors of its [usability criteria|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Usability%20criteria/]. The page of each macro, linked in the table, has the full notes and the steps to reproduce. Fixing them means changing the declaration of the parameters in the macro definitions.
The E2 errors KOs of template and uiextension are only partly covered here, for the name and the identifier. The same KOs also report other invalid values, covered by the other issues listed on the page of each macro, among them XCOMMONS-3847 for the conversion of the values and XRENDERING-823 for the wording of the error. |
|
