Parameter change for the Documents macro (_actions, _likes)

[vmassol]

Hi devs,

I’d like to fix Loading... (i.e. ability to not display the Likes column).

There are 2 options.

Option 1: Add a likes parameter

• (+) Consistent with the existing actions parameter. See https://extensions.xwiki.org/xwiki/bin/view/Extension/Documents%20Macro#HParameterdefinitions
• (-) Not consistent with the columns parameter which is supposed to support all valid coulmn values from the LT documentation (thus including _likes and _actions

Option 2: Deprecate the actions parameter

• (+) This means supporting the _likes and _actions values in the columns parameter (already supported)
• Deprecate the actions parameter (see below for a detailed proposal of the deprecation)

In addition to these 2 options, we need to decide on the default behavior. Right now, the actions and likes column are displayed by default.

I’m proposing to break this behavior since I don’t believe users need/want the like column everywhere. I also believe it’s the same for the _actions column and it shouldn’t be displayed by default (not all places where we display docs want to have the copy, rename, rights delete actions displayed).

Overall proposal

1. Deprecate the actions parameter (and add support for specifying it in the columns parameter), i.e. the columns parameter takes precedence. Specifically:
   • If the _actions value is set explicitly in the columns parameter then display the actions column, even if the actions parameter is set to false.
   • If the columns parameter is not set by the user (i.e. default is used), then display the actions column if the actions parameter is set to true.
2. Don’t display Likes by default (and add support for specifying it in the columns parameter).
3. Document this change of behavior in the RN.

WDYT?

Thanks

[mleduc]

+1 for option 2 with the proposed deprecation steps.

[CharpentierLucas]

-1 for option 1. It adds unneeded complexity to the macro parameters. The documents macro function is detailed in a few words on its documentation. Simple description should mean simple configuration. We have more powerful macros that can do pretty much the same thing with more parameters and a finer grain of control on the output (e.g. liveData macro).

+1 for option 2.

@vmassol

I’m proposing to break this behavior since I don’t believe users need/want the like column everywhere. I also believe it’s the same for the _actions column and it shouldn’t be displayed by default (not all places where we display docs want to have the copy, rename, rights delete actions displayed).

I don’t agree: I think a few users could rely on this macro to have an easy access to actions on a lot of documents. Technically it’s not the best way to do things, but it was easy to setup and worked by default, so I believe some users could have relied on this default behaviour more than they should have or what we expect. But as long as the change is documented properly in the RN and with a Since note on the macro documentation, I think it’s fair to change this. The name of the macro and its description do not say anything about these actions being here, it’s not the primary use intended

Thanks for starting this proposal!
Lucas C.