Add concept of hidden macros

[vmassol]

Hi devs,

I’d like to propose to introduce the concept of hidden macros.

Rationale and use cases:

• Some extensions introduce internal macros (that they use on several pages, usually as a way to reuse code). They are not supposed to be visible in the list of macros in the WYSIWYG editor.
• If you’re a wiki admin you may want to direct your users to use a specific macro for a purpose (say to make graphs) but you also want to use an extension that draws another macro to make graphs but you don’t want your users to use that one.

Proposal 1

• Add a “hidden” field to the Macro descriptor
• Similar to the macro descriptor category, allow users to override this field from the configuration

  #-# [Since 2.0M3]
  #-# Overrides default macro categories (Each macro has a default category already defined, for example
  #-# "presentation" for the Table of Contents Macro).
  #-#
  #-# Ex: To redefine the macro category for the TOC macro so that it'd be in the "My Category" category +
  #-# redefine the category for the Script Macro to be "My Other Category", you'd use:
  # rendering.macroCategories = toc:My Category
  # rendering.macroCategories = script:My Other Category
  

• Also provide an Admin UI to set this configuration
• Add a java ConfigurationSource to return the information (i.e. introduce a MacroDescriptorConfig wiki page to hold that info + fallback to xwiki.properties. Maybe also fallback to the main wiki’s MacroDescriptorConfig)
• Modify the WYSIWYG backend service to not return hidden macros
• Modify XWikiSyntaxMacrosList to not return hidden macros
• Option: show the hidden macros if the user is showing hidden pages in his profile

Proposal 2

• Deprecate getDefaultCategory() in the MacroDescriptor in favor of getDefaultCategories(), i.e. allow having several categories + change the xwiki.properties rendering.macroCategories config to support several categories
• Introduce a UI + java Configuration Source to configure the macro category override
• Introduce a “hidden” category
• Modify the WYSIWYG backend service to not return hidden macros
• Modify XWikiSyntaxMacrosList to not return hidden macros
• Option: show the hidden macros if the user is showing hidden pages in his profile

In short proposal 2 is the same as 1 but reusing the existing “category” concept (that is extended to support several categories), making the “hidden” category a special name/concept vs other categories.

Note: We could also introduce a new configuration in xwiki.properties (and possibly UI) to control whether hidden macros are never shown or shown depending on the user’s “show hidden pages”. I’d say that could be added later if need be.

WDYT?

My preference goes towards proposal 2 since:

• It can be made backward compatible IMO
• We kill 2 birds with one stone, i.e. we implement the concept of hidden macros while adding the new feature of being able to have several categories for macros.
• We improve configurability of categories override by providing a UI for it.

Thanks

[vmassol]

@vmassol

We kill 2 birds with one stone, i.e. we implement the concept of hidden macros while adding the new feature of being able to have several categories for macros.

Note that we would need to decide about the special Deprecated category. Basically it would mean that Hidden and Deprecated are special categories.

For Deprecated we would need to remove it from the list of categories in the WYSIWYG dialog and instead add a checkbox (false by default) to decide to display legacy macros or not.

For Hidden, this is the proposal above, i.e. not list them unless the user has configured the show of hidden pages in his profile for ex.

WDYT?

[tmortagne]

@vmassol

I’d like to propose to introduce the concept of hidden macros.

+1 in general and I agree that it can make sense to be able to define several categories for a macro

[mleduc]

I’m +1 for both options, but I think options 2 has more potential from an UX point of view.
For instance, by adding the possibility to filter using several categories.

This could be achieved by adding checkbox in the categories drop-down (where deprecated and hidden would be unchecked by default).

The only drawback I can find for option 2 is if some users already defined macros with the “Hidden” category (which is unlikely). In this case the macro would “disappear” from the list after the upgrade.

[vmassol]

@mleduc

This could be achieved by adding checkbox in the categories drop-down (where deprecated and hidden would be unchecked by default).

Yes I would use some type of toggles, line by line (e.g. https://www.bootstraptoggle.com/).

Re deprecated, it would be listed, but off by default.

But the “hidden” category wouldn’t be listed at all by default (except when the user has selected “display hidden pages” in his/her profile). BTW we may want to either rename this property or introduce a new one. Any preference?

@mleduc

The only drawback I can find for option 2 is if some users already defined macros with the “Hidden” category (which is unlikely). In this case the macro would “disappear” from the list after the upgrade.

OTOH if they named it “hidden” it probably means they want it hidden

[MichaelHamann]

While I think most parts of option 2 are good, I’m not really a fan of introducing these “magic” category values. Could we maybe make the list of categories to hide by default/hide for non-advanced users configurable? We would still use the “Hidden”/“Deprecated” category names, just with a configuration to select them and to control which categories have that special status (which might include more categories in some wikis).

@vmassol

Yes I would use some type of toggles, line by line (e.g. https://www.bootstraptoggle.com/).

Wouldn’t it be better to use a multi-select and let selectize enhance that?

[tmortagne]

@MichaelHamann

Could we maybe make the list of categories to hide by default/hide for non-advanced users configurable? We would still use the “Hidden”/“Deprecated” category names, just with a configuration to select them and to control which categories have that special status (which might include more categories in some wikis).

+1

[vmassol]

@MichaelHamann

Could we maybe make the list of categories to hide by default/hide for non-advanced users configurable? We would still use the “Hidden”/“Deprecated” category names, just with a configuration to select them and to control which categories have that special status (which might include more categories in some wikis).

Sure that’s possible. It’s just more work. What I was suggesting was to have this fixed FTM as I don’t think there’s a strong need to have it configurable (I haven’t seen the need expressed at all TBH, so for me it’s YAGNI ATM and it’s possible to add in the future if it’s needed). Also it wouldn’t change much since we’d still need to define what the defaults are (and if the suggestion is to show hidden macros by default, then I wouldn’t quite agree).

PS: the proposal is not for advanced/simple users but for users with “show hidden pages” or not.

[vmassol]

Also note that if for example, admins didn’t want to show deprecated macros, they could add the “hidden” category to them in the Admin UI.

Also the behavior is different for the 2 special categories:

• “deprecated”: not selected by default when searching but user can toggle it
• “hidden”: displayed depending on whether the user is “showing hidden pages” or not

[mflorea]

It’s not clear for me why we need multiple categories for a macro. Why isn’t enough to put the macro in the Hidden category if you want to hide it. And if you want to hide it then it means it’s only for internal usage (used only by the extension that provides it) so it doesn’t need another category than Hidden. Categories are useful for the end user to be able to find / filter the macros, but if a macro is not intended to be used by end users then it doesn’t need a category, so having just the Hidden category is enough.

I also don’t understand the relation between hidden macros and hidden pages. Why should a user that wants to see hidden pages be able to see hidden (internal) macros that may be written in Java.

Moreover, if there is indeed a need for multiple categories for macros (personally I’m not sure) then these become tags.

Finally, can you list some macros from XS that would benefit from these multiple categories?

Thanks,
Marius

[mleduc]

@mflorea

It’s not clear for me why we need multiple categories for a macro. Why isn’t enough to put the macro in the Hidden category if you want to hide it. And if you want to hide it then it means it’s only for internal usage (used only by the extension that provides it) so it doesn’t need another category than Hidden. Categories are useful for the end user to be able to find / filter the macros, but if a macro is not intended to be used by end users then it doesn’t need a category, so having just the Hidden category is enough.

I don’t agree, a macro that become hidden, or deprecated (or both) does not loose its existing categories.
Then, once the hidden category is checked, one might want to search for the macro by filtering on another category.
For instance, the spaceindex macro was moved from category Navigation to Deprecated but imo, while deprecated, this is still a macro from the Navigation category too (and the same goes for the spaces and workspaces macros).

@mflorea

I also don’t understand the relation between hidden macros and hidden pages. Why should a user that wants to see hidden pages be able to see hidden (internal) macros that may be written in Java.

That’s a point that has been raised before in the discussion indeed. I’d be +1 to have a separate setting for hidden macros (even though I’d be fine to reuse the “display hidden page” setting as a facility for a first version).

@mflorea

Moreover, if there is indeed a need for multiple categories for macros (personally I’m not sure) then these become tags.

I’m fine with using the term categories. Also, I feel like tags also it too general. labels could be a option. In summary I’m +1 for categories, +0 for labels and -0 for tags.

@mflorea

Finally, can you list some macros from XS that would benefit from these multiple categories?

Really depend on how we think this will be used. If admins add the hidden category in addition to the other category(ies) of the macro to hidden them, then potentially any macro can have several categories.

[vmassol]

@mflorea

Finally, can you list some macros from XS that would benefit from these multiple categories?

Examples: macros that generate content but that are about graphs could be in the content and graph categories.

Globally I agree that categories are actually tags in the proposal but then it becomes just a terminology. Categories used to represent the domain(s) of the macro. But with hidden and notinstalled, they really become tags. I think using categories as tags is acceptable from a terminology POV and that users would find it nicer to talk about Macro Categories than Macro Tags (it’s less generic/complex to understand probably).

I agree with the rest from @mleduc 's answers.

[vmassol]

Implemented in [XWIKI-19750] Allow macros to have several categories - XWiki.org JIRA and co.