Refactoring of Menus

Development
#1

Hi everyone,

as part of my work for adding a UIXP for the Viewers’ part of “Other action” menu, I started to check how to properly refactor the menus to use UIX and I now have several questions.

Usage of “shortcuts” terminology for viewers Menu

It’s apparently something historical that I don’t really understand but the “viewers” part of the menu is currently defined in shortcuts.vm and we are checking that $displayShortcuts is true for displaying them. Here I’m just wondering if we want to keep that terminology in the future, or if we want to put everything in menus_content.vm.

Just to be clear when I’m talking about the “viewer” part of the menu I’m talking about this: image

Partial usage of hardcoded items or full usage of UIX in menus

Right now the different menus we have (namely the Edit menu, the Manage menu, the More actions menu, and the Viewers menu) are all using a mix of hardcoded items and items coming from UIXP.

I’d like to know what direction we want to take and how we want to do that, between keeping this mix of hardcoded items and UIX or using UIX everywhere.
The advantage of having hardcoded items is that you’re currently sure that those menu will be displayed whenever the template is available (so basically with a minimal wiki).
Now the advantage of having UIX everywhere is the flexibility to order them, chose them, customize them etc.

I personally think it would be better to go for using UIX for all items of the menu, now it would mean that someone creating an empty wiki wouldn’t have some menu options such as Copy/Remove/Delete (part of Manage menu). We could also decide that those specifically are too important to be UIXP and that they need to remain hardcoded. But then we need to be clear of what can remain hardcoded and what cannot.

Now here I was talking only about the items of the Menus, but the Menus themselves could be displayed as UIX, we also have hardcoded Menus and some dynamic ones with the org.xwiki.plaftorm.menu.content UIXP. I wouldn’t change that right now personally, but it can be considered to discuss the global direction we want to take.

So to sum up:

  1. Are you ok if we stop using “shortcuts” for talking about viewers, and to discard the shortcuts.vm unless we keep using it only for handling keyboard shortcuts?
  2. Are you ok if we’re going to a solution with all menu items defined as UIX, meaning that an empty wiki wouldn’t have them?
#2

I think the idea was that it was shortcut link to the extradoc tabs. The shortcuts.vm file says:

## Build the list of documents extras to display, if it does not exist (default).
## List format : ["ExtraAnchor",  "ExtraTabText", numberOfItems]

Note that shortcuts.vm is used by 6-7 other templates (without using menus_content.vm), so it seems there’s a need for something more fine-grained than menus_content.vm.

Second note: Removing a vm is like breaking an API. Anyone who had a custom skin overriding it will get broken.

For 1:

  • I don’t think we can remove it but we could introduce a new vm and have shortcuts.vm call it.
  • Indeed this template also defines the keyboard shortcuts which probably need to stay there or be moved to a keyboard_shortcuts.vm file.

For 2:

  • I agree it would be nice to only have UIXPs and UIXs.
  • We need XWiki to be usable for its basic features in the minimal distribution. If we have the docextra in the minimal distribution then the menu links to them should also be there IMO.
  • One idea is to have UIXs which are implemented as templates (they can currently be implemented as wiki page or java components).
  • Another idea is to introduce a feature we discussed in the past which is to have a special directory in xwiki (under WEB-INF probably) and if there are extensions there (in the form of XIP files probably), then XWiki would install them at first run. This would mean bundling minimal App extensions (extensions contributing wiki pages) in the minimal distribution.
#3

You are only taking into account wiki page based UIX here but we could also provide the most standard menu entries as java components (so it would be available even on an empty wiki and yet be UIX).

+1 for full UIX but I don’t agree with the consequence (so not use only wiki page UIX)

#4

So indeed I haven’t considered this. So it would be some specific components to be put in a module of the minimal wiki to instantiate our needed UIX.

#5

I don’t think it would be a dedicated module but more components spread in each domain related modules. For example the refactoring module would provide stuff like rename, delete, etc.

#6

I’m not sure it’s that great to have UIX in java in general. I feel it’s not that good because UIX are by definition visual things (and thus front end) and java is backend (and we shouldn’t put UI logic in Java as much as possible) and much harder to modify by non developers.

It might be better to be able to register vm files as UIXes, using a special format. Or to have mandatory pages (that we can count on being there at runtime). This is why I said:

#7

Isn’t this what rendering macros do? And we have plenty of Java-based rendering macros. I don’t see a problem with having UIX defined in Java provided the amount of HTML generated is minimal or even none at all. Moreover, the menu UIX could have only parameters and no code to execute. The UIX should just specify the link label, link target and an icon.

#8

Yes it’s true but it depends on the macros. Some macros are better written in java such as the cache macro or the content macro. Some others, which are more front end are better written as wiki macros.

Yes I agree with this. It’s about the amount of HTML/CSS/JS in the macro. But it’s also about the need to perform changes to them (when they’re in java they’re essentially immutable for the end user).

Good point. The link label is actually a translation key so that’s changeable by the user in the wiki. The link target is not supposed to be changed (unless the app is moved to another location but we don’t support that well ATM anyway). There’s just the icon which the user/admin could want to change I guess. That could be implemented by using a config parameter (a translation key wouldn’t be the right way) but I find that overkill. Worse come worse, it’s possible for the user to override the whole menu by replacing the part of the vm that implements the UIXP.

So I agree that it’s acceptable in this case probably, even though I still find it not normal to have UI code (menus are essentially UI logic) in Java. So while it’s acceptable here, I don’t think this is the perfect solution and I don’t find it a good generic solution for this need. For me, we need a “client-side” solution closer to the user.

So I’m +0 for the menus as java UIX (I think we loose something from before - we also gain something else thanks to the UIX). More generally I’m against writing UIX in Java as I think it contradicts what UIX are (UI code logic, and Java is not the best technology for UI code logic).

WDYT?

Thanks

#9

I don’t understand this idea: what would be the difference with having a dependency in the minimal distrib to a XAR module? We could decide to put that minimal menu items in a dedicated XAR module and to have a reference to it in the minimal distrib no?

So I will start with that, anyway those components will be internal: even if we change later the implementation we should still use the same UI extension point IDs so we shouldn’t break any backward compatiblity.

#10

Here are 2 use cases:

  • Anyone can choose to use an empty flavor and in this case there are no pages loaded.
  • Anyone can install the WAR (it’s a valid packaging and used by 23% of our users) and in this case it doesn’t matter if other packagings have a dependency on some XARs or not.

So the idea is to ensure that some pages always exist in your wiki. This is similar to the concept of mandatory class initializers in java which create wiki pages that are required, except that it would take its data from a XAR (i.e. from XML content).