|
| Description: |
The chart, liveData and dashboard macros take values from a list in free text fields of the Edit Macro dialog, so the user has to know the accepted values, and a wrong one fails when the macro renders or gives "(No entries)".
The macros to change, with the file where most of the fix is done:
* chart: [ChartMacroParameters.java|https://github.com/xwiki/xwiki-platform/blob/master/xwiki-platform-core/xwiki-platform-chart/xwiki-platform-chart-macro/src/main/java/org/xwiki/rendering/macro/chart/ChartMacroParameters.java].
* liveData: [LiveDataMacroParameters.java|https://github.com/xwiki/xwiki-platform/blob/master/xwiki-platform-core/xwiki-platform-livedata/xwiki-platform-livedata-macro/src/main/java/org/xwiki/livedata/macro/LiveDataMacroParameters.java].
* dashboard: [DashboardMacroParameters.java|https://github.com/xwiki/xwiki-platform/blob/master/xwiki-platform-core/xwiki-platform-dashboard/xwiki-platform-dashboard-macro/src/main/java/org/xwiki/rendering/macro/dashboard/DashboardMacroParameters.java].
The main problems:
* The type and source of chart are fixed lists, which a Java enum would turn into a select with no other change: they do not depend on another ticket.
* The Live Data sources are components, and the layouts a list of several values, so their values have to come from a provider.
* The style of dashboard has one predefined value, panels, but accepts any CSS class, so it needs suggestions with free input.
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. This also applies to the properties and the source parameters of a Live Data, which the chosen source declares, to a Live Data content that is not JSON, and to the layout of dashboard, a fixed list that only holds columns today. The endless spinner of a layout that cannot be loaded is XWIKI-24835.
The source of chart must also declare inline as its default value, the value of the most common example, so that the select preselects it instead of opening empty.
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.
h2. KOs covered
||Macro||Criterion||Parameter||Problem||Depends on||
|[chart|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/chart/]|C4 input-assistance|{{type}}|A free text field for one of the 12 chart types, where a select, ideally with a preview of each type, could be used: {{Pie}} is accepted and fails at rendering.|-|
|[chart|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/chart/]|C4 input-assistance|{{source}}|A free text field for inline or xdom, where a select could be used: {{source="foo"}} is accepted and fails at rendering.|-|
|[liveData|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/liveData/]|C4 input-assistance|{{source}}|A plain text field for one of the installed Live Data sources, which a select could offer.|XWIKI-23045|
|[liveData|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/liveData/]|C4 input-assistance|{{layouts}}|A plain text field for a list taken from table and cards, which checkboxes or a multiple select could offer.|XWIKI-23045|
|[dashboard|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/dashboard/]|C4 input-assistance|{{style}}|A plain text field, while the only predefined value, panels, is given in the description only: a field suggesting it and accepting any CSS class would show it.|XWIKI-23045|
|[chart|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/chart/]|E2 errors|{{source}}, {{type}}|source="foo" gives a component lookup error, and type="foo", or "Pie" with a wrong case, gives "Invalid value for parameter [type]: [foo]", which does not list the accepted values. Partly covered, see below.| |
|[liveData|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/liveData/]|E2 errors|{{source}}, {{layouts}}, {{properties}}, {{sourceParameters}}|An unknown source gives "TypeError: Cannot read properties of undefined" with its stack trace, an unknown layout stays a loading spinner, and unknown properties or a sourceParameters class that does not exist give an empty table, all with no message naming the parameter. A content that is not JSON gives the error of the JSON parser. Partly covered, see below.| |
|[dashboard|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/dashboard/]|E2 errors|{{layout}}|An unknown layout gives "Could not find dashboard renderer noSuchLayout" with a stack trace, which names the value but not the parameter, and does not say that columns is the only layout. Partly covered, see below.| |
|[chart|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/chart/]|C3 defaults|{{source}}|The field opens empty, which stands for inline when the macro has a content, the value of the most common example, so the example renders, but the field does not show which value it stands for. Partly covered, see below.| |
h2. Impact found on macro fluidity
These 8 9 KOs come from the [WYSIWYG usability audit of the macros|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/], under the criteria C4 input-assistance and , E2 errors and C3 defaults 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 chart, liveData and dashboard are only partly covered here, for these parameters. 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.
The C3 defaults KO of chart is only partly covered here, for the value to preselect. The same KO is also partly covered by XWIKI-23759, which adds custom placeholders to the macro fields; a placeholder alone does not show the value the empty field stands for. |
|
