Stable order for macro parameters

[surli]

Hi everyone,

I’m opening this proposal to discuss the order displayed in the UI when you add or edit a macro, so this UI:

Currently it’s not possible to predefine the order of the parameters, so the behaviour is the following by default:

1. Mandatory parameters are displayed first, but only a limited number of parameters
2. Advanced parameters are by default “hidden” inside the “More” section
3. Whenever a user sets a value for a parameter it stops being hidden

So, for example, my first screenshot was default values of the Page Tree macro, here’s what you have if I select values in the list of parameters present in the More section and I edit again the macro:

You can see that suddenly the UI is entirely different, I don’t see at all the same parameters displayed. I personally find such behaviour confusing, and I will soon work on providing the capability to order the parameters: IMO it would be much simpler to go towards a fixed and immutable order.

@mflorea performed a very good analysis of the questions to solve in Loading... so I’m taking it back here:

1. Should we display all the macro parameters all the time?
   Yes: then we use whatever order we get from the macro descriptor; problem fixed
   No: Some macros have lots of parameters, most of them optional, some advanced, some deprecated, etc. we display only a limited number of parameters first, with a More button / link

2. What’s the expected order between the macro parameters?
   A. Either rely only on the order in which the macro parameters are listed / defined in the macro descriptor (assuming that the macro descriptor respects the order in which the macro developer has defined the macro parameters in their code)
   B. Or group macro parameters by importance / priority (e.g. mandatory, optional, advanced, deprecated, etc.). Inside each group the macro descriptor order would be used. Open question: should the macro priority change (within its group) when its value is set?

3. Is it important for the user to see right away which macro parameters have a value set?
   No: then we keep hidden macro parameters with a value set hidden; problem solved
   Yes: Then we need to:
   A. either show those parameters with a value set that are hidden initially under More => the order between the macro parameters changes
   B. we could restore the macro descriptor order once the More button / link is clicked, i.e. when all parameters are shown
   C. or indicate somehow to the user that there are some hidden parameters with a value set

My personnal view on those questions is:

1. No: I think we cannot display at once all parameters. If I take back the example of Page Tree macro there’s a lot of parameters and it would be quite tedious for users to show them all

2. B. I honestly didn’t see it coming but I’ve the feeling it could be useful for the users as it’s also giving some info about how the macro works, what they’re allowed to omit or not. For me the order inside the group shouldn’t change when a value is set.

3. C. To be a bit more explicit: I would go for having an immediate visual clue that a value is modified by the user (it’s not default value anymore) in the macro UI (e.g. in my second screenshot it’s difficult to understand that the checkbox Show page title is actually displayed because I uncheked it…), and then I’d display an information about the number of parameters with a value set next to the “more” link. That would allow to keep a fixed order.

WDYT?

[CycleSEC]

Thanks for raising this issue. That would be a great improvement for us. We’ve developed around 60 macros—some are very simple, with no or just a few parameters.

For the more complex macros, there are numerous possible parameters. Some are useful for more experienced users, some only affect layout, and others are critical for the macro’s functionality. A few serve as mandatory pre-settings for specific use cases but are not relevant to content creators.

Therefore, I would highly appreciate having more options for showing or hiding parameters in the WYSIWYG view.

It would go a step further and would find it also be helpful to have a rights management system for certain parameters—so that they can only be modified by users with script or admin permissions. For example, one of my macros generates a chart using the chart macro and requires the class name and property name as parameters. These parameters are often confusing for content contributors who are mainly focused on visual aspects like chart colors or whether the chart should have a title. In this case ideally, parameters like class and property could be placed in some kind of admin section, or at least hidden from standard users.

My personal view on your questions above are as follows:

1. No.
2. B.
3. “Yes+” — My suggestion would be to introduce a “More” section, which could include an “Advanced Settings” area—if advanced parameters are available. Implementing rights management might be quite a bit of work, so this could be a simpler and more pragmatic solution.

[mflorea]

@surli

Mandatory parameters are displayed first, but only a limited number of parameters

Just to be clear: mandatory parameters are always displayed (so never folded under More). By “only a limited number of parameters” you must be referring to the macro parameters that are optional.

@surli

No: I think we cannot display at once all parameters. If I take back the example of Page Tree macro there’s a lot of parameters and it would be quite tedious for users to show them all

Same for me.

@surli

B. I honestly didn’t see it coming but I’ve the feeling it could be useful for the users as it’s also giving some info about how the macro works, what they’re allowed to omit or not. For me the order inside the group shouldn’t change when a value is set.

Same on my side. I don’t see a use case where a macro developer would want to display an optional parameter before a mandatory one.

@surli

C. To be a bit more explicit: I would go for having an immediate visual clue that a value is modified by the user (it’s not default value anymore) in the macro UI (e.g. in my second screenshot it’s difficult to understand that the checkbox Show page title is actually displayed because I uncheked it…), and then I’d display an information about the number of parameters with a value set next to the “more” link. That would allow to keep a fixed order.

Fine with me. Regarding the custom value indicator, the simplest is to use something around the macro parameter name, which is fully controlled by the Macro Editor. If you want to style the parameter field differently then it’s more complex because that is not controlled by the Macro Editor but by the displayer associated to the macro parameter (type). The Macro Editor could set a special CSS class on the HTML element that wraps the parameter, but the displayer would have to react to that (apply some styles to the HTML elements it generates).

Thanks,
Marius

[vmassol]

@surli

Currently it’s not possible to predefine the order of the parameters, so the behaviour is the following by default:

1. Mandatory parameters are displayed first, but only a limited number of parameters
2. Advanced parameters are by default “hidden” inside the “More” section
3. Whenever a user sets a value for a parameter it stops being hidden

Note that the full algorithm is documented under https://extensions.xwiki.org/xwiki/bin/view/Extension/CKEditor%20Integration/#HWikiMacros (specifically under “When on the Edit Macro step, these macro parameters are displayed following these rules:”).