Naming convention for User Interface Extension Points

This topic is a proposal for a naming convention for the identifiers of the User Interface Extension Points (UIXP).

The proposal below is based on existing conversations (here, here, and here) as well as the actual naming of existing UIXP and UIX ( <extensionPointId>.+</extensionPointId> in xml files of the platform).

UIXP naming convention

A UIXP id should be <groupId>.<moduleName>.<uixpQualifier>.

<groupId> must be in the form [a-z]+(\.[a-z]+)* and match the groupId of the module in witch it is first used.

<moduleName> must be in the form [a-z]+ and match the module name, for instance panels for an UIXP declared in xwiki-platform-panels or user.directory for xwiki-platform-user-directory.

<uixpQualifier> must be in the form [a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)* and be descriptive of the intent of the UIXP, especially if a module declared multiple UIXP.

UIX naming convention

Having a strong convention for UIXP ids is critical as they cannot be modified once introduced in a release. Having a naming convention of UIX is not as critical but is still interesting to discuss.

Looking at their use in existing code, the implicit norm tend to follow <groupId>.<moduleName>.<uixQualifier>.

The use of <groupId> and <moduleName> is similar to UIXP.

<uixQualifier> must also be in form [a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)* and be descriptive of the contribution that the UIX does in regard to the UIXP.

WDYT?

Once we reach an agreement, I will report the final naming convention in XWiki’s development documetation.

+1

Example: org.xwiki.platform

Pros:

  • Provides a namespace (e.g. between xwiki github org and xwiki-contrib extensions).

Cons:

  • Makes it harder to move modules around (from xwiki-contrib to xwiki or the opposite). In practice we’ll only be able to make the move if we also introduce the concept of alias.

+1

IMO this leave too much way for interpretation.

I’m proposing to use the following:

  • Single word and with camel case

Rationale:

  • We’re talking about UIXP and thus we don’t need a big naming space with dots
  • Let’s keep dots to separate parts of the id and not put them in each part (note that we have an exception for the full module name that we use).
  • It makes it simpler and we won’t risk devs naming the id differently with one dev using “xxx.menu” and the other “xxxMenu”. We could also decide to not use camel case and use dots. Personally I prefer not dots since it makes it more clear what is the prefix and what is the short UIX id name.

Example:

  • [org.xwiki.platform].[user.profile].menu since we have a single menu but imagine we had 2 menus, we would use: [org.xwiki.platform].[user.profile].xxxMenu and [org.xwiki.platform].[user.profile].yyyMenu.

WDYT?

I’d propose the same the following:

<groupId>.<moduleName>.<short uixp id>.[<qualifier>], with the qualifier being there only if there’s more than 1 UIX for this module for the target UIXP. For example: [org.xwiki.platform].[dashboard].[menu] if we add only 1 entry to the user profile menu. If the dashboard module was adding 2 then it would be [org.xwiki.platform].[dashboard].[menu].[qualifier1] and [org.xwiki.platform].[dashboard].[menu].[qualifier2].

WDYT?

+1 for the short camel case uixpQualifier in UIXP ids.

+1 if by <short uixp id> you mean <uixpQualifier>.

I’m guessing the UIX optional <qualifier> is also a single camel case word?

So according to your example I guess you meant [a-z]+(\.[a-z]+)* since you accept dot in the names.
Trying to take an example: https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/ExtensionPoint/DrawerItem

would became:
org.xwiki.platform.skin.flamingo.resources.drawerMenu

is that correct?
Why not:
org.xwiki.platform.skin-flamingo-resources.drawerMenu?

Besides that I’m +1 with groupId and camel case uixpQualifier.

Now, re UIX:

you mean that it should be the same groupId/moduleName or, they should be chosen the same way?

I don’t a strong opinion in between both alternatives. Using dash removes some ambiguity. In the other hand if find the use of dots nicer, but it’s definitely a question of personal taste.

By that I meant that the use of <groupId> and <moduleName> should always be used relatively to the module in which the id is declared and should conform to the same naming convention (regardless of if it’s an UIX or UIXP).

ok, just to clarify I’m +1 with both solutions, was just wondering :slight_smile:

ok, I was wondering yesterday if it could be helpful to have a common part in the UIX id and its UIXP id but I don’t think so anymore since we need to declare the UIXP we use anyway.

I’ll do a short non-formal summary, mostly for me but I hope it would be useful for others.

UIXP

<groupId>.<moduleName>.<uixpQualifier>

  • <groupId>: reuse maven’s groupId in which the UIXP is declared. lower case, dot separated.
  • <moduleName>: reuse maven’s module in which the UIXP is declared. lower case, dot separated.
  • <uixpQualifier>: descriptive name of the UIXP. Single camel case identifier.

Example: org.xwiki.platform.user.profile.menu

UIX

<groupId>.<moduleName>.<uixpQualifier>(.<uixQualifier>)

  • <groupId>: reuse maven’s groupId in which the UIX is declared. lower case, dot separated.
  • <moduleName>: reuse maven’s module in which the UIX is declared. lower case, dot separated.
  • <uixpQualifier>: reuse the uixpQualifier of the UIXP where the UIX contributes.
  • <uixQualifier>: optional, used only in case of ambiguity, for instance if the UIX is declared in the same module as the UIXP, or if several UIX are declared in the same module. Single camel case identifier.

Examples:
org.xwiki.platform.notifications.menu
org.xwiki.platform.user.profile.menu.userMembership
org.xwiki.platform.user.profile.menu.userNetwork

Small detail: we should always write “xwiki” and not “xWiki”.

EDIT: and in this case we can simply drop the “xwiki” prefix, it doesn’t bring much value… (otherwise we’d also need to write “…xwikiProfile.xwikiMenu.xwikiUserNetwork”… Everything is about xwiki in xwiki land :wink:

+1. I’ve updated the examples in my previous post. Do you agree with my summary after this update?