Give XClasses categories, and let the XClass picker filter on them

Context

The XClass picker (the classPicker Velocity macro of macros.vm) lists every XClass the current user can view, with nothing to distinguish a business XClass (a Meeting or a Recipe, created through AWM or by hand) from a purely technical one (rights, sheet bindings, and the like). It has exactly two callers today, both advanced editors: the object editor (editobject.vm) and the class editor (editclass.vm). This becomes an obstacle as soon as the picker is offered to non-technical users, for instance in a macro that lets them pick an XClass, choose the properties to display, and get a Live Data out of it (XWIKI-24831).

Proposal, option 5.2: https://forum.xwiki.org/t/improve-the-listing-of-xclass-in-the-xclass-picker/18766/7

Categories on XClasses

A category is a raw, capitalised string id (Internal, Deprecated, Development), and an XClass carries zero or more of them. This follows the conventions already used for macro categories, including the two special ids Internal and Deprecated.

Display labels resolve through the xclass.category.<Id> translation keys, falling back to the raw id when no translation exists, so a category created on a wiki is usable with no configuration.

Categories are stored as a categories meta-property of BaseClass, next to the existing validationScript and customMapping. In the XAR they are a single <categories> element holding a comma-separated list, which matches the flat-string shape of every other class meta-property. A comma is therefore not allowed in a category id.

They are set in the class editor, alongside the other class meta-properties.

Filtering in the picker

Which categories are hidden is decided by the caller of the picker, not by the advanced-user flag: the object and class editors are themselves advanced tools and must keep seeing everything. The classPicker macro takes a hiddenCategories exclusion parameter that defaults to empty, so both existing callers are unaffected, and a caller aimed at non-technical users passes Internal and Deprecated.

An XClass with no category is always shown. There is no way to exclude the uncategorised ones, because a wiki's own hand-made classes have no category either and hiding them would defeat the purpose.

Filtering happens in the picker's existing search field through a category: prefix, rather than through a second filtering field. The picker is a compact dropdown embedded in someone else's form, unlike the macro selector which is a full modal dialog with room for a multi-select:

• category:photography returns every XClass in the photography category
• meetings category:projectmanagement returns every XClass whose title matches meetings and that is in the projectmanagement category

Matching is case-insensitive and by prefix, against both the category id and its translated label. Several category: terms are combined with AND, as the macro picker does.

Displaying categories

The matching categories are displayed as badges on the dropdown rows, inside the existing per-space option groups, using the translated label. The space grouping is unchanged, and the selected item shows no badge.

Configuration

A single instance-wide property, xclass.categories in xwiki.properties, reassigns the categories of a given XClass, mirroring rendering.transformation.macro.categories:

xclass.categories = Blog.BlogPostClass = Blog,Content

This is what lets an administrator categorise an XClass shipped by an extension they do not control. There is deliberately no global hidden-categories property: hiding is the caller's decision, and a global setting would silently remove classes from the object editor.

Implementation notes

• the picker renders the full class list server-side from $xwiki.classList and filters it client-side through xwiki-selectize (Tom Select), so no query is involved and the meta-property needs no index
• the picker template already loads every class document to render its title, so reading the meta-property costs no additional document load
• the category: support is a classPicker-scoped override of the Tom Select search, not a change to the shared xwiki.selectize.js, which backs the user, page and attachment pickers as well

Scope

Categorised as part of this issue, to exercise the mechanism: XWiki.XWikiRights and XWiki.ClassSheetBinding as Internal, and Blog.BlogPostClass as Content.

Reviewing and categorising all the XClasses shipped by XWiki is a follow-up issue.