Details
-
Improvement
-
Resolution: Unresolved
-
Major
-
None
-
1.6.3
-
None
-
None
-
Unknown
-
Description
The descriptions of the chartjs and tableToChartJS macros, and of their parameters, are what the Insert Macro and Edit Macro dialogs show to explain them. They describe the technique instead of what the macro adds, and never say what the content or the table must look like, which a user needs to know to get a chart.
The macros to change, with the file where most of the fix is done:
- chartjs: defined in WebHome.xml, descriptions in Translations.xml.
- tableToChartJS: defined in TableToChartJS.xml, descriptions in the same Translations.xml.
The main problems:
- The content of chartjs is a JSON object with labels and datasets, and the table of tableToChartJS must be on the same page and carry an id: neither description says it.
- The type of both macros lists values presented as complete, while horizontalBar, used in the documentation, also works.
- The parameters of tableToChartJS use Chart.js terms, data set and index, without saying what the table must look like.
KOs covered
| Macro | Criterion | Parameters | Problem |
|---|---|---|---|
| chartjs | D2 summary | "Simple HTML5 charts using the canvas element." describes the technique, the canvas element, in words that mean nothing to most users, and does not state the rule that the user needs to insert the macro: the content must be a JSON object with labels and datasets, and the type must be one of the Chart.js types, see C1 of the content. The name of the macro plus "charts" is mostly repeated. | |
| chartjs | C1 clarity | $content | "The chart data." does not say that the data is a JSON object with labels and datasets, which the dialog never describes, nor that each data set has a label and a list of numbers. The format is only visible in the examples of the documentation. |
| chartjs | C1 clarity | type | "The type of chart. Choose from: line, bar, radar, pie, doughnut, polarArea, bubble, scatter." says what it sets and gives the values, but the list is presented as complete while the horizontalBar of the examples of the documentation works and is not in it, and the values are the Chart.js identifiers, written as is, with the case that matters, see E2. |
| chartjs | C1 clarity | title | "Chart title, added as aria-label to the generated canvas" uses developer terms, and the name suggests a title drawn on the chart, like the title of the Chart macro of XWiki Standard, while it is only the text alternative of the canvas, which no title is drawn from. The meaning is clear once read. The name is the ID and the description is not translated in French and German. |
| tableToChartJS | D2 summary | "Draws a chart using ChartJS and the data read from a table." is the name spelled out, "Table to ChartJS", with a verb added. It does not state the rule the user needs to insert the macro: the table must be on the same page and carry an id, set with (% id="singleDataSet" %) in the source or in the Advanced tab of the table properties of the editor, and the macro gets that id in its table parameter. | |
| tableToChartJS | C1 clarity | type | "The type of chart. Choose from: line, bar, radar, pie, doughnut, polarArea, bubble, scatter." says what it sets and gives the values, but the list is presented as complete while the horizontalBar of the last example of the documentation works and is not in it, and the values are the Chart.js identifiers, written as is, with the case that matters, see E2. |
| tableToChartJS | C1 clarity | multipleDataSets | "Whether the specified table includes multiple data sets." uses a Chart.js term and does not say what the table must look like: the first column holds the labels and each other column is one data set, with the header cell as its name. Four of the five examples need it, since they have two data columns. |
| tableToChartJS | C1 clarity | table | "Identifies the source table." does not say what to type: the id of a table of the same page, which has to be set on the table first, see D2. It gives no possible value for a free field. |
| tableToChartJS | C1 clarity | dataSetLabel | "The index of the table column that represents the data set label." does not say that it only has an effect together with multipleDataSets, nor where the index starts: the last example sets "1" for a table whose second column, Project, holds the label, so it starts at 0. It uses developer terms, index and data set. |
Impact found on macro fluidity
These 9 KOs come from the WYSIWYG usability audit of the macros, under the criteria C1 clarity, D2 summary of its usability criteria. The page of each macro, linked in the table, has the full notes and the steps to reproduce. Fixing them means changing the translations of the macros and, for a name or a category, their definitions.