Provide a location picker for the location parameters of the tag cloud and documents macros

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:

• tagcloud: defined in TagCloud.xml.
• documents: defined in DocumentsMacro.xml.

Where it is needed

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

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.