| The tag cloud and documents macros take the location of the pages they cover, and the Edit Macro dialog shows it as a plain text field: the user has to type the full reference of a page they cannot browse for, in a format the field does not explain, and a location that does not exist is accepted silently. The macros to change, with the file where most of the fix is done:
Where it is needed
| Macro |
Parameter |
Value |
| tagcloud |
spaces |
locations, several values, today as quoted references separated by commas, like 'Space1','Space2' |
| tagcloud |
space |
one location |
| documents |
location |
one location, matched anywhere in the full reference of the listed pages |
The space parameter of the documents macro is left out: it is deprecated, and hiding it is tracked by XWIKI-13363. Proposal XWIKI-24636 added a location picker, which suggests locations as you type and lets the user browse for them in a tree, and an HTML displayer edit template for List<SpaceReference> that uses it with several values.
- Add an HTML displayer edit template for SpaceReference, which uses the same picker with a single value.
- Declare List<SpaceReference> as the type of the tagcloud spaces parameter, and turn the typed value back into the quoted list that the macro expects, so that a list typed without the quotes stops failing with a stack trace.
- Declare SpaceReference as the type of the tagcloud space and documents location parameters. A typed location is matched anywhere in the reference, like "Beau" matching France.Paris.Beaubourg.Office, so the picker must keep accepting free text, or the existing pages using it change their result.
XWIKI-17818 proposes to rename the tagcloud space and spaces parameters to page and pages. The picker fits both names, since a location is a page that can have children. KOs covered
| Macro |
Criterion |
Parameter |
Problem |
| tagcloud |
C4 input-assistance |
spaces |
A plain text field for a list of pages, where a picker accepting several pages could be used. |
| tagcloud |
C4 input-assistance |
space |
A plain text field for the page whose tags are shown, with its child pages, where a picker could be used. |
| documents |
C4 input-assistance |
location |
A plain text field, where a picker could set the location of the listed pages, the use of every example. |
| tagcloud |
E2 errors |
space, spaces |
space="No.Such", and a nested page given without its parent, show "No tag has been added on this page or on its children" with no word on the page not existing; spaces="Sandbox", without the quotes, fails with a stack trace. |
Impact found on macro fluidity These 4 KOs come from the WYSIWYG usability audit of the macros, under the criteria C4 input-assistance and E2 errors of its usability criteria. The page of each macro, linked in the table, has the full notes and the steps to reproduce. The E2 errors KO of tagcloud is only partly covered here, for the locations. The same KO also reports the invalid limit values accepted silently, covered elsewhere: the value conversion by XCOMMONS-3847 and the wording of the error by XRENDERING-823. |
