Change #1311915 had a related patch set uploaded (by Michael Große; author: Michael Große):

[mediawiki/extensions/CommunityConfiguration@master] [PoC] Add optional UI schema for form layout

https://gerrit.wikimedia.org/r/1311915

Proposal for introducing a UISchema to CommunityConfiguration with supporting custom controls as the first step

Both from the Abstract Wikipedia team and from the Reader Experience team, there have been recent requests to be able to use custom form controls for some use-case or other.

CommunityConfiguration is closely inspired in its architecture by JSON Froms (https://jsonforms.io/). The approach that JSON Forms uses for such customization is a UISchema (https://jsonforms.io/docs/uischema/). CommunityConfiguration is using/creating a very simple UISchema internally in the frontend part of the code, which essentially only is "Render a control for all fields in the data schema, one after the other."

The proper way to allow consumers of CommunityConfiguration to gain more control over how the form is rendered is to allow them to provide their own UISchema.

To unblock the teams asking for custom controls, the first iteration of UISchema in CommunityConfiguration should be built to allow extensions exactly that.

The proposed implementation should have the following properties:

• backwards compatibility: existing schemas without an associated UISchema continue behaving in exactly the same way
• graceful degradation: if a control defined by a UISchema is not available, CommunityConfiguration uses its internal logic to pick a suitable control
• separation of concerns: the new UISchema should be exclusively for presentational aspects, everything around validation must continue to live in the data-schema

Specifically, building on the example of T424097:

We want to get to a state where existing data-schema would have an optional reference to the associated UISchema, like so:

class SuggestedFunctionsSchema extends JsonSchema {

	public const UI_SCHEMA = SuggestedFunctionsUISchema::class;

	public const SuggestedFunctionsEnabled = [
		self::TYPE => self::TYPE_BOOLEAN,
		self::DEFAULT => false,
	];

	public const SuggestedFunctions = [
		self::TYPE => self::TYPE_ARRAY,
		self::ITEMS => [
			self::TYPE => self::TYPE_STRING,
			self::PATTERN => '^Z[1-9]\\d*$',
		],
		self::MAX_ITEMS => 5,
		self::DEFAULT => [ 'Z20756', 'Z18428' ],
	];

	public const Example_String = [
		self::TYPE => self::TYPE_STRING,
		self::DEFAULT => '',
		self::MAX_LENGTH => 50,
	];
}

With the referenced UISchema looking something like this:

class SuggestedFunctionsUISchema extends UISchema {

      public const ROOT = [
          self::ELEMENTS => [
              '#/properties/SuggestedFunctionsEnabled', 
              [
                  self::TYPE => self::TYPE_CONTROL,
                  self::SCOPE => '#/properties/SuggestedFunctions',
                  self::CONTROL => 'WikiLambda.FunctionSelector',
                  self::OPTIONS => [
                      // presentation-only knobs the control understands,
                      // e.g. 'showZidChips' => true
                  ],
                  self:MESSAGES => [
                      // the (extra?) message keys needed for this control
                  ],
              ],
              '#/properties/Example_String',
          ],
      ];
  }

Note that self::CONTROL should usually be a plain string and not a PHP FQDN. A PHP FQDN seems to mix abstractions and has details like namespaces leak.

The control itself would be registered as an attribute, similar to what is sketched out in T424097.

CommunityConfiguration needs to be extended so that likely GenericFormEditorCapability understands and scans the associated UISchemas and adds the requested js modules (and i18n messages, probably those should also live in the extension.json section).

The client-side registry needs to load the custom controls. This is probably the least well-defined part. Currently, this is a closed system that just loads all the handlers CommmunityConfiguration has defined and that needs to change. TBD on how exactly that would look, whether via mw.communityConfiguration.registerControl( name, renderer, tester ) or mw.hook( 'CommunityConfiguration_loading_controls') or some other approach. All of that then needs to be wired up.

Open Questions

• Should the UISchema have to contain all elements, or just the ones it wants to modify?
• If the UISchema is also defining the order of elements, which makes sense for later iterations that focus on allowing grouping, adding headlines, etc., then it makes sense for an UISchema to typically require all elements. Missing elements would then be just appended at the end of the form, regardless of their position in the data-schema.
• How specifically would the js code be loaded? This is the issue described above. We need to decide this once, it will be hard to change later.

Notes

• Especially the first extensions making use of the UISchema will need excellent testing and a mutual CI-dependency with CommunityConfiguration to make sure that future work on CommunityConfigration+UISchema does not silently change how their forms look.

Let's put the proposal under docs/decisions in CommunityConfiguration repo, so it is available for every developer. https://github.com/wikimedia/mediawiki-extensions-CommunityConfiguration/tree/master/docs/decisions

In T370534#12179328, @Urbanecm_WMF wrote:

Let's put the proposal under docs/decisions in CommunityConfiguration repo, so it is available for every developer. https://github.com/wikimedia/mediawiki-extensions-CommunityConfiguration/tree/master/docs/decisions

👍

Change #1320200 had a related patch set uploaded (by Michael Große; author: Michael Große):

[mediawiki/extensions/CommunityConfiguration@master] docs: Add ADR about how to introduce a customizable UI Schema

https://gerrit.wikimedia.org/r/1320200

@Michael I see the patch is WIP, so moving to Doing. Happy to CR once finished.

Change #1320200 merged by jenkins-bot:

[mediawiki/extensions/CommunityConfiguration@master] docs: Add ADR about how to introduce a customizable UI Schema

https://gerrit.wikimedia.org/r/1320200