I’d like to propose that we change the behavior of the {{children/}} macro to not display attachments and translations by default . See also Loading...
The rationale is simple: the children macro’s main use case is to display children pages. Wanting to display attachments and translations is an edge case and thus shouldn’t be the default.
So yes, it’s a breaking change (hence the proposal) but hopefully for the best.
WDYT?
An alternative is to introduce 2 new macros (and deprecate the {{children}} macro, which is badly named in the end since it could as well display children docs in a table and not as a tree):
{{childrenTree}}: display a tree of children documents
{{childrenTable}}: display a LD of children documents. Right now the {{documents}} macro is not meant to display children docs, and using the location param is awkward at best (and more complex than it should be).
Did you identify how we ended up displaying them in the first place? Was this done with intent or was it a side effect of another change that we didn’t really discuss?
This would probably be too much of a breaking change, but we could also consider just changing the default value of the documentTree showAttachments and showTranslations parameters to false.
+1 from me, technically and semantically, attachments and translations are not children so I think it makes sense to remove them from the child macro display.
-0. If we have some needs expressed by users, sure, it sounds sensible. If we do not have explicit needs, I don’t think it’s worth to implement both of these macros for now. It will take time to implement, time to maintain, and make our UX a bit more complex (IMO it’s already not the easiest for new users to know when to use documents, documentTree, children, tree).
We do have explicit needs and it’s been asked several times on the forum and in JIRA. Actually if you try to write docs for something you’ll soon end up wanting to display children pages (since XWiki supports nested pages) and right now we don’t provide any satisfactory solution:
If you want a tree, you’ll try to use the {{children}} macro with the issue of listing attachments and translations. And again, the name of the macro is misleading since you may not want a tree but a table.
If you want a table, you’ll try to use the {{documents}} macro with the proble of listing only children pages. You’ll try to use the location parameter, to find that the current page is also listed (and you don’t want it). Again the name of the macro is not perfect since nothing says that it’ll display a table and not a tree (for ex).
See:
Hence the idea I’m also proposing above to fix all this and in addition to avoid breaking backward compatbility for the {{children}} macro by introducing 2 macros: {{childrenTree}} and {{childrenTable}}.
Note that this won’t lead to deprecating the {{documents}} macro which is still useful if you want to list some docs (but not necessarily children docs).
So for me, even if we’re ok to change the behavior of the {{children}} macro, we’ll eventually still need to work on a {{childrenTable}} macro.
Small note that I didn’t propose a single {{childrenDocuments}} macro with a layout/type parameter that would be either tree or table, because the other parameters require depend too much on the layout chose (defining the columns to display only make sense for a table and not for a tree, etc).
I think I prefer the option to indeed provide new dedicated macros with specific layouts than breaking the behaviour of current children macro. I don’t know how much the macro is used in existing user instances, but I’m a bit afraid that if people are using it a lot, they’d need some scripts to fix their usage of the children macro.
And as you said if anyway we need to work on providing different layout then it seems better to start right away with those new macro having the behaviour we now want.
+1, I agree with you that most of the users want to see only the child pages. For the few cases where the attachments / translations are expected it’s easy to modify the macro call.
+0, sounds good but more work, depends if anyone is available to work on this.
