ConfigurableClass refactoring

Hello everyone,

there is currently a limitation in ConfigurableClass that prevents displaying a configuration section in any space and in the wiki administration (see

This is an old limitation, but this is currently a problem because of a recent regression it’s causing with Like right (see to sum up we used to display the Like right in the standard right UI with a ugly hack, that we removed by introduced the Extension Rights. However, this new section is only displayed in the Wiki administration, because of the ConfigurableClass limitation.

So I worked on that limitation and came up with a solution being a new property scope replacing configureGlobally: I performed the changes as part of a PR (see: XWIKI-18723: Make ConfigurableClass support all space and wiki administration cases by surli · Pull Request #1663 · xwiki/xwiki-platform · GitHub), which worked and was applied.

However I had to revert my work because of a migration issue: I wrote two migrations mechanism to move configureGlobally property to scope, the first triggered at wiki startup (an hibernate migration), and the other one triggered when an extension is installed or upgraded so that old extension providing a ConfigurationClass would work properly.
But that cannot work because the current mechanism of ConfigurableClass is provided through XWiki documents in xwiki-platform-administration-ui module.

So the current mechanism is the following, we have:

  • XWiki.ConfigurableClass: an XWiki document providing both the XClass definition and a velocity script that defines the behaviour of the administration sections (this is what we see when we go to an administration page)
  • XWiki.ConfigurableClassMacros: defines some macros used by XWiki.ConfigurableClass and actually the macro using the old configureGlobally property.

And currently, xwiki-platform-administration-ui is only upgraded when the XWiki flavor is upgraded, so only when an admin is following the digital wizard steps. It means that my current hibernate migration is called way before that module is upgraded, and an administration could see the whole administration broken before he upgraded the flavor, since the documents would still use the old configureGlobally property while the migration would have removed it in favor of scope.

As I indicated, to avoid this I currently reverted my work, however we need to fix this limitation in ConfigurableClass, at the very least to fix the Like right regression without putting back an ugly hack.
I see three solutions for fixing this migration issue:

  1. we don’t migrate the configureGlobally property value and we keep supporting both configureGlobally and scope in XWiki.ConfigurableClassMacros. This is the easiest solution, it means developers would see a deprecated property when checking their old ConfigurableClass until they removed them manually to use scope. Note that in that case, we’d need to define the macro to always gives the priority to scope when both properties are available.

  2. we completely change the logic of Administration application to rely on a MandatoryDocumentInitializer for the ConfigurableClass xclass, and on velocity templates for the ConfigurableClassMacro and for the velocity script contained in ConfigurableClass. This is probably the cleanest solution, but that means a big refactoring, and probably a refactoring breaking the compatibility with previous versions. Now it would be probably cleaner since that’s a mechanism we want in any version of XWiki, so it should probably not be dependent on the flavor. Also this refactoring could allow us to rely on Java components instead of velocity scripts, which would allow to provide better testing.

  3. we keep same code that I committed, but we just change the way we trigger the migration to perform it when the flavor is upgraded first, and then when any extension is installed / upgraded. It probably involved some ad-hoc checks. That’s probably the quickest solution.

I’m personally not a big fan of solution 3, but it would allow to fix quickly the regression we have. IMO it cannot be a long term solution though.
I do prefer solution 2, but that’s something which will have a big impact, especially since Administration Application is an old one, so it can be used in many places, and have had many different customizations.
Solution 1 is probably the safest if we want something working and if we consider it’s not a big deal to have deprecated properties. Now on the long run, the problem will remain.


I would start with 1. and discuss in more details what we want for the admin section refactoring later.

IMO we should not touch anything to the current system and instead introduce a new system which look and behave exactly like we want it to look and behave, this is by far the simplest in terms of retro compatibility. And the first thing I would suggest for the new system would be to stop thinking about it in terms of configurable xobjects and instead introduce a new component to deal with those administrations sections and have the xobject being only the wiki bridged versions of those components (same as wiki ui extensions, wiki macros, etc.). This would finally make possible to properly insert administration sections for JAR extensions.

I agree.

What’s less simple is how to move ConfigurableClass to legacy once the new system is in place. I guess it would mean moving these pages into a new contrib extension and asking all the extensions still using ConfigurableClass to depend on it. Not easy to do consistently across the board. The alternative is to invent a new system in xwiki (based on FASTEN maybe) where we could automatically discover extensions using ConfigurableClass and auto-install the new contrib extension containing it.