Background
CommunityConfiguration client library "json-form" generates a generic form based on json-schemadefinitions. On the high level it renders a Codex field for each property found in the given schema. In some situations there's a need to do some visual customisation of the form in a particular provider. For instance hiding a particular property, displaying a property with a non-standard control, customize the form layout or grouping properties.
In order to meet the initial release of the extension deadlines some visualization customisations have been introduce in the extension ad-hoc, mixing validation and presenation concerns. An example of this mixing of concerns is the "control" keyword used for rendering MediaWiki specific controls via references, (T357718).
The parent form specification task had a proposal to avoid this problem: using a UI Schema. However the definition was quite vague:
The concept is borrowed from jsonforms/uischema and consists of a JSON definition file which describes the controls, layout and rules of a form.
As an example:
{ "$schema": "https://json-schema.org/draft-04/schema#", "$id": "http://example.com/communityconfiguration/help-panel/1.0.0", "type": "object", "properties": { "GEHelpPanelAskMentor": { "type": "boolean", "description": "When using the help panel's question-asking functionality, post on the mentor's talk page instead of on the help desk page.", "default": true }, "GEHelpPanelHelpDeskPostOnTop": { "type": "boolean", "description": "Whether to post new questions on the top of the help desk. Default is to post on the bottom (like section=new does). Only affects wikitext pages.", "default": true }, "GEHelpPanelExcludedNamespaces": { "type": "array", "items": { "type": "number" } }, "GEHelpPanelReadingModeNamespaces": { "type": "array", "items": { "type": "number" } }, "GEHelpPanelSearchNamespaces": { "type": "array", "items": { "type": "number" } } }, "required": [ "GEHelpPanelAskMentor", "GEHelpPanelHelpDeskPostOnTop", "GEHelpPanelExcludedNamespaces", "GEHelpPanelReadingModeNamespaces", "GEHelpPanelSearchNamespaces" ], "additionalProperties": false }
{ "type": "VerticalLayout", "elements": [ { "type": "Group", "label": "Simple group", "elements": [ { "type": "Control", "scope": "#/properties/GEHelpPanelAskMentor" }, { "type": "Control", "scope": "#/properties/GEHelpPanelHelpDeskPostOnTop" } ] }, { "type": "Group", "label": "Complex group", "elements": [ { "type": "Control", "scope": "#/properties/GEHelpPanelExcludedNamespaces" } ] } ] }
The UI schema does not need to be necessarily defined in JSON it could also be done in PHP. If no UI schema is provided CC2.0 can fallback to a "vanilla" set of controls and some default settings for form displaying.
Possible use cases of UI schema
- T358221: Add support for displaying grouped configurations
- T356857: Allow providers to add custom fields
- T358663: Allow consumers to customize the default editor UI representation for an option
- T367494: Community configuration: Add support for parametrised controls which in turn unlocks more functionality:
- Allowing conditional fields, that is fields that display based on the state of other fields
- Optional bypass MW i18n system