|
| Summary: |
Improve the descriptions and categories of the page list and tree macros and of their parameters |
| Issue Type: |
 Improvement |
| Affects Versions: |
17.10.14, 18.8.0 |
| Assignee: |
Unassigned |
| Components: |
Index, Tag, Tree, Wiki |
| Created: |
22/Oct/26 11:58 |
| Priority: |
 Major |
| Reporter: |
Charpentier Lucas |
| Description: |
The descriptions of the macros that list pages, and of their parameters, are what the Insert Macro and Edit Macro dialogs show to explain them. Many use developer terms or repeat the macro name, and some are wrong, so a user cannot tell what the macro shows or what to type in a field. The macros to change, with the file where most of the fix is done:
The main problems:
- Several parameters use developer terms with no explanation: space, node id, objects, class, class properties, pretty name, Livetable.
- The expected format of a value is rarely given, like a node id such as document:xwiki:Main.WebHome for the root, openTo and exclusions parameters, or a filter of the documents macro.
- Some descriptions are wrong: the root of children, the parent of documents, which is the legacy parent field, the description of tree, which names a source parameter that does not exist, and the description of wikis, which lists only the wikis the user can view.
- documents and tagcloud are in the Content category, while children and documentTree, which also lead to other pages, are in Navigation.
KOs covered
| Macro |
Criterion |
Parameters |
Problem |
| children |
D2 summary |
|
The description speaks of child pages only, while the tree also lists the Translations and Attachments of the root page: {{children root="document:Sandbox.WebHome"/}} shows "Translations" and "Attachments" nodes before the child pages. It also says "children pages" instead of "child pages". |
| children |
C1 clarity |
root |
The description is technical and wrong for this macro: "The root node id. [...] The entire tree is displayed if the root node is not specified." It speaks of nodes, a documentTree notion, while an empty Root shows the child pages of the current page, not the entire tree. |
| documentTree |
D2 summary |
|
The description "Displays the tree of XWiki pages." repeats the name "Page Tree", and does not say that the tree lists the pages of the wiki, or of a given page, as links that expand on click. |
| documentTree |
C1 clarity |
showWikiPrettyName |
"Pretty Name" and "wiki id" are technical terms: the name does not say that it shows the title of the wiki instead of its identifier, like "Show wiki titles". |
| documentTree |
C1 clarity |
showSpaces |
"Spaces" is a technical term that the UI no longer shows since nested pages, and the description, "The pages are grouped by space", does not explain it. |
| documentTree |
C1 clarity |
showObjects |
"Objects" is a developer term, while the macro targets every user: nothing explains it in the dialog. |
| documentTree |
C1 clarity |
showClassProperties |
"Class Properties" is a developer term, while the macro targets every user: nothing explains it in the dialog. |
| documentTree |
C1 clarity |
hierarchyMode |
The values "reference" and "parentchild" and the description, "the nested spaces component of the page reference", "the parent page field from the database", are technical terms that do not say which tree the user gets. |
| documentTree |
C1 clarity |
filterByClass |
"Class" is a developer term, while the macro targets every user. The description gives an example, Blog.CategoryClass, but does not explain what a class is. |
| documentTree |
C1 clarity |
filterHiddenDocuments |
The name and description say "documents" while the rest of the dialog says pages, and "Filter Hidden Documents" checked does not filter them for a user whose preferences show hidden pages. |
| documentTree |
C1 clarity |
exclusions |
The description says the nodes are "specified by their id and separated by comma" but does not give the format of a node id, like document:xwiki:Main.WebHome, which only the documentation gives. |
| documents |
D2 summary |
|
"Displays a list of pages in a Livetable" is outdated: "Livetable" is the developer name of the table component that the macro no longer uses: it renders a Live Data. It does not say that the table can be sorted, filtered and paged through, nor that it adds Likes and Actions columns, with Copy, Rename and Delete, by default. |
| documents |
D3 category |
|
The macro is in Content, like liveData, while children and documentTree, the other macros that list pages, are in Navigation, where a user looking for a list of pages would also look. |
| documents |
C1 clarity |
space |
"space" is a technical term that the UI no longer shows since nested pages, and the description does not say that the full space reference is needed. |
| documents |
C1 clarity |
id |
"Livetable id" uses a developer term, and the wrong one, the table being a Live Data, and does not say what the id is for: styling the table, and telling apart two tables of a page. |
| documents |
C1 clarity |
parent |
"Only list pages having the specified parent" means the legacy parent field, not the page that contains the listed pages: on a page with two nested child pages, {{documents parent="<that page>.WebHome"/}} shows "(No entries)". The description does not say it. |
| documents |
C1 clarity |
filters |
"Provide a default filter to apply in the documents Live Data" does not give the format, like doc.author=Admin, which only the documentation gives. |
| tagcloud |
D2 summary |
|
"Displays the cloud of tags in this wiki or in the specified space, if any." repeats the name, "Tag Cloud", and does not say what a tag cloud is: the tags of the pages, each one larger the more pages use it, and each one a link to the list of its pages. It also uses "space", a term the UI no longer shows, and does not mention the several spaces of spaces nor the limit. |
| tagcloud |
D3 category |
|
The macro is in Content, like documents, while children and documentTree, which also lead the user to other pages, are in Navigation, where a user looking for a tag cloud, a set of links to the pages of each tag, would also look. |
| tagcloud |
C1 clarity |
limit |
The description does not say that an empty field shows every tag, nor which tags are kept, the most used ones. The French name and description are left in English, to fix on l10n.xwiki.org. |
| tree |
D2 summary |
|
The description "Displays a tree hierarchy defined by the macro content or the source parameter." names a "source" parameter that does not exist, the parameter is Reference, and "tree hierarchy" mostly repeats the name: it does not say that the tree shows a nested list as nodes that expand and collapse on click. |
| tree |
C1 clarity |
$content |
The description "You can use nested HTML unordered lists to describe the tree structure. See http://www.jstree.com/docs/html/ for more information." speaks of HTML and of the jsTree library, while the user types a wiki syntax bulleted list, and does not say that anything other than a bulleted list, like a paragraph, a table or a numbered list, is dropped, see E2. |
| tree |
C1 clarity |
reference |
"Reference" does not say that it is the page providing a dynamic tree, and the description uses technical terms, "resource", "URL/path", without saying that a URL needs the "path:" prefix, which only the documentation gives. |
| tree |
C1 clarity |
root |
"root node id" is technical, and the description does not give the format of a node id, like document:xwiki:Main.WebHome, nor that it only works with a dynamic tree. It also says the root node is not displayed, while showRoot can display it. |
| tree |
C1 clarity |
class |
The parameter looks like the cssClass of other macros, such as box, container or code, but it is named differently and does something different: the description says the classes are added, while they replace the default xtree class, so {{tree class="foo"}}* A ** B{{/tree}} renders a plain bulleted list instead of a tree, see tree_macros.vm. |
| tree |
C1 clarity |
openTo |
"The id of the node" is technical, and the description does not give the format of a node id nor how to give one to a node of a static tree. |
| wikis |
D2 summary |
|
The description "List all wikis" repeats the name. It is also inaccurate: the output only lists the wikis the current user can view, and adds a "Create a new wiki" link when the user may create one, as the documentation says: "It only lists the wikis that the user can access". It could say "Lists the wikis you can access, with a link to create a new one." |
Impact found on macro fluidity These 27 KOs come from the WYSIWYG usability audit of the macros, under the criteria C1 clarity, D2 summary, D3 category 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. |
|
