Wiki source code of Macro Visibility Control

Last modified by Vincent Massol on 2024/02/26 17:57

Show last authors
1 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.
2
3 The two targeted use cases are:
4
5 1. Hiding deprecated macros that still need to be installed for some pages to work, but that shouldn't be used further
6 1. 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
7
8 {{toc start="2"/}}
9
10 == Use Cases ==
11
12 * UC1: Macros can be attached to several categories
13 * UC2: Macro with category hidden are not visible by default, unless the user has activated a property to show hidden macros by default{{warning}}In a first time we'll reuse the "show hidden pages" property{{/warning}}
14 * UC3: Hidden macros should not be listed in the CKEditor macro dialog by default
15 * UC4: Admins should be able to update the list of categories of a macro
16 * UC5: Admins should be able to update the list of hidden macro categories
17 * UC6: Users should be able to configure if they wish to see hidden macro by default
18
19 == Requirements ==
20
21 == User Interface ==
22
23 === Available Macros ===
24
25 ==== Current UI ====
26
27 [[image:image-20220523115039-1.png||height="328" width="650"]]
28
29 ==== New UI ====
30
31 * Category column replaced by Categories
32 * The hidden macro are not listed, unless the current user has a property activated to show hidden macros (see UC2).
33
34 [[image:image-20220523115418-1.png||height="235" width="630"]]
35
36 {{warning}}
37 **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).
38 {{/warning}}
39
40 === CKEditor Macro dialog ===
41
42 ==== Current UI ====
43
44 [[image:image-20220523113750-1.png||height="288" width="350"]]
45
46 ==== New UI ====
47
48 The second field is a ##xwiki-selectize## field, with an autosuggest of the existing categories.
49
50 [[image:https://forum.xwiki.org/uploads/default/original/2X/4/490f83b52d500cd9eaf1a7b8965e26a56da8ebdc.png||alt="image" height="438" width="684"]]
51
52 The macros are filtered according to the following parameters:
53
54 * ##hiddenCategories##: a list of categories hidden by default
55 * ##selectedCategories##: the list of categories selected by the user
56
57 1. All the macros containing a category which is part of ##hiddenCategories##
58 1. if ##selectedCategories## is not empty, all the macros that does not have all the selected categories
59
60 === Macros Administration ===
61
62 ==== xwiki.properties ====
63
64 {{code language="properties"}}
65 rendering.transformation.macro.categories = toc = My Category\,Deprecated
66 rendering.transformation.macro.categories = script = My Other Category
67 # TODO: needs to be proposed to the community
68 rendering.transformation.macro.hiddenCategories = Development,Internal,Deprecated
69 {{/code}}
70
71 ==== Administration UI ====
72
73 {{warning}}
74 * Choose location in the admin menu
75 * 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)
76 {{/warning}}
77
78 (% class="wikigeneratedid" %)
79 Under ##Content > Macros##.
80
81 * A first field "Hidden Macros", a selectize field, allow to select the default categories. If the list is empty, the value from xwiki.properties is used
82 ** multiple values can be selected
83 ** they are saved in **TBD**
84 ** existing macro categories are auto-suggested
85 ** free values can be defined (i.e., admins can define categories as hidden even though no macro are assigned to it yet)
86 * 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
87 ** the modal displays the id of the macro, the list of default categories, and the field to override the categories
88 ** if the macro don't have an override yet, prefill the override selectize field with the default values
89 ** if the macro has override, efill the override selectize with the override
90 ** **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
91 ** **NOTE:** where to save the override, one XObject per override?
92
93 (% class="box successmessage" %)
94 (((
95 **Idea:** Do all of that using Vuejs 2.x latest and make it easy to migrate to Vue 3 using the retro-compatibility APIs.
96 )))
97
98 === Macros User Preferences ===
99
100 ==== Option 1 ====
101
102 Reuse the show hidden page configuration, which is convenient but not very accurate {{warning}}Since 14.6RC1, this is the implemented option.{{/warning}}
103
104 ==== Option 2 ====
105
106 Introduce a new "show hidden macros" user configuration, allowing users to configure if the want to see hidden macro independently of hidden pages
107
108 {{warning}}
109 TODO: List the impact in the UI (user preferences, default value in the administration?...)
110 {{/warning}}
111
112

Get Connected