Macro Visibility Control

Last modified by Raphaël Jakse on 2024/06/14 10:06



The goal of this feature is to allow administrators and macro developers to limit  the use of some macros by hiding them in the UI. Note that the goal is not to strictly disallow their use, and this is not a security feature. Knowledgeable user will still be capable to use any hidden macro by writing in xwiki syntax for instance.

The two targeted use cases are:

  1. Hiding deprecated macros that still need to be installed for some pages to work, but that shouldn't be used further
  2. Hiding duplicate macro to promote the use of a main one. For instance is macro A and B provide the same feature, an administrator can decide to hide macro B in order to incentivize users to prefer the use of macro A

Use Cases

  • UC1: Macros can be attached to several categories
  • UC2: Macro with category hidden are not visible by default, unless the user has activated a property to show hidden macros by defaultIn a first time we'll reuse the "show hidden pages" property
  • UC3: Hidden macros should not be listed in the CKEditor macro dialog by default
  • UC4: Admins should be able to update the list of categories of a macro
  • UC5: Admins should be able to update the list of hidden macro categories
  • UC6: Users should be able to configure if they wish to see hidden macro by default


User Interface

Available Macros

Current UI


New UI

  • Category column replaced by Categories
  • The hidden macro are not listed, unless the current user has a property activated to show hidden macros (see UC2).


Future idea: replace the static table with a dynamic Live Data. Note: This requires a custom Live Data source as macro metadata needs to be loaded for each entry before display (for instance, the list of categories can be customized by admin, from properties outside of the XObjects).

CKEditor Macro dialog

Current UI


New UI

The second field is a xwiki-selectize field, with an autosuggest of the existing categories.


The macros are filtered according to the following parameters:

  • hiddenCategories: a list of categories hidden by default
  • selectedCategories: the list of categories selected by the user
  1. All the macros containing a category which is part of hiddenCategories
  2. if selectedCategories is not empty, all the macros that does not have all the selected categories

Macros Administration

rendering.transformation.macro.categories = toc = My Category\,Deprecated
rendering.transformation.macro.categories = script = My Other Category
rendering.transformation.macro.hiddenCategories = Development,Internal,Deprecated

See for this last part.

Administration UI

  • Choose location in the admin menu
  • Decide of content (note that we also need to decide of the configuration source as macro categories should be overridable from the properties as well as from the UI)

Under Content > Macros.

  • A first field "Hidden Macros", a selectize field, allow to select the default categories. If the list is empty, the value from is used
    • multiple values can be selected
    • they are saved in TBD
    • existing macro categories are auto-suggested
    • free values can be defined (i.e., admins can define categories as hidden even though no macro are assigned to it yet)
  • An action should be proposed to redefine the categories of a macro, a field is available to type the macro id, if the macro already has an override, the modal is opened with the override configuration, otherwise, if the macro is known the user can create the override, otherwise an error message is displayed and the create action is disabled
    • the modal displays the id of the macro, the list of default categories, and the field to override the categories
    • if the macro don't have an override yet, prefill the override selectize field with the default values
    • if the macro has override, efill the override selectize with the override
    • NOTE: what to do when a macro is not available anymore? Proposal: just show a warning to say that we are currently unable to display the macro + allow to delete the definition
    • NOTE: where to save the override, one XObject per override?

Idea: Do all of that using Vuejs 2.x latest and make it easy to migrate to Vue 3 using the retro-compatibility APIs.

Macros User Preferences

Option 1

Reuse the show hidden page configuration, which is convenient but not very accurate Since 14.6RC1, this is the implemented option.

Option 2

Introduce a new "show hidden macros" user configuration, allowing users to configure if the want to see hidden macro independently of hidden pages

TODO: List the impact in the UI (user preferences, default value in the administration?...)


Get Connected