XWiki Macro categories configuration

Development
1

Hello all,

In the context of the support of multiple categories for the macros, I’d like to discuss the support for categories configuration.

Currently, overriding the category of a macro can be only done by updating xwiki.properties. For instance to set the “Demo” category to the toc macro:

rendering.transformation.macro.categories = toc:Demo

Note: While the services to read those properties exists, they are - to our knowledge - not used in the code based of XS.

From our initial discussion on #xwiki, we considered the following options

Option 1: Full override only

When overriding the categories of a macro, the admin must list exhaustively the new categories.

rendering.transformation.macro.categories = toc:Demo,Hidden

Option 2: Diff only

The admin starts from the list of default categories of the macro, and can either add or remove categories.

For instance, if the toc macro has the default categories = ['Navigation'], defining its categories to be ['Demo, ‘Hidden’]` can be done with:

rendering.transformation.macro.categories = toc:-Navigation,+Demo,+Hidden

Option 3: Diff optional initial values

The admin can choose to start from the list of default categories. When ^ is added as the first character of the list, the default categories are added, otherwise they are not.

Therefore, the two configurations below are equivalent if default categories = ['Navigation']

rendering.transformation.macro.categories = toc:Demo,Hidden
rendering.transformation.macro.categories = toc:^-Navigation,+Demo,Hidden

Once we agree on this, I’ll update this proposal with the corresponding Administration UI.

WDYT?

PS: Of course feel free to also suggest variations of the syntax.

2

I like option 2 but for me it works only if it’s easy to get the full list of categories for a given macro: if you don’t know it you might easily forget to remove a category for example.

If it’s not easy to know it option 1 is probably better since you have a better control over the categories.

3

Note that a Admin UI will also be provided, where the default categories will be displayed.

4

ok then option 2 is probably best IMO.

5

+1 for option 2, 3 is way too complex for the need IMO and I believe option 1 is not the most common use case

6

That’s strange to me, I’d have used ^ to indicate a “start of the line”, i.e. a full override, i.e. the opposite of what you mentioned.

But I think there’s another option:

rendering.transformation.macro.categories = toc:Demo,Hidden <-- full override
rendering.transformation.macro.categories = toc:-Navigation,+Demo,+Hidden <-- only additions and removals

If some entries don’t have + or - then consider that it’s a +. If not entries have + or - the consider it’s a full override. Alternatively consider it an error if only some categories have + or - and don’t use category override (and emit a warning in the logs).

But I agree with Thomas that we don’t need this and we can always add it later on if need be.

It’s more costly than option 1 to implement but a bit nicer for users (technical admin users who don’t use the UI that is!) who don’t need to find out the existing default categories.

It’s also hard to decide without knowing the cost of implementation.

Since you mentioned that there will be an Admin UI, I don’t think that we need option 2 and I would go for option 1.

So +1 for option 1, -0 for option 2 and 3.

7

I’m realizing I haven’t expressed my preferences.

I’m +1 for option 1 as long as an UI is also proposed to the admins (and even when configuring into xwiki.properties, one can still open a wiki to look at the categories)
+0 for option 2, -1 for option 3.

8

Indeed, if we have a UI then option 1 is probably good enough for now.