This task serves to define how should the Editing form component of Community configuration 2.0 project work like. For a high-level technical overview of Community configuration 2.0 (including description of other components), please see T341884: Community configuration: Define architecture of the system. This task assumes high-level familiarity with other components the feature is consisted of.

Description

To ensure admins who are not tech-savvy can use the Community configuration, we should have an editing form (similar to Special:EditGrowthConfig). Usage of the configuration form needs to be optional; any configuration user needs to be able to introduce their own editing interface should be able to do so. If possible (T332849: [Spike] Investigate form generation options for community configuration is research spike), the configuration form should auto-generate itself based on the schema (T342575).

Editing form concepts

Renderer: responsible for generating the HTML markup for an editing form based on a given schema. Determining the best renderer or renderers is upon discussion per research in T332849. Regardless of the pick up for form generation the extension will use, it is desirable to allow to plug different renderers. Examples: could be OOUI HTMLForm or Codex.
Controls: responsible for the user interaction for a given configuration. Also responsible of producing valid data for each configuration value. These could be HTMLFormField or Codex components.
Layout: responsible for the generated form layout, can offer different display formats, field grouping or categorization. Currently HTMLForm supports some layout customisations. ($availableDisplayFormats, collapsible form).
Rules: responsible for effects during form interaction. Some forms require hiding or showing elements based on the form state. Not necessarily an MVP feature but a nice to have. A form definition could include a set of rules to be applied to a given form.
Validation: responsible for ensuring submitted data is valid. Aside from the schema validation that will happen on the backend after form data is submitted the auto-generated form should have client validation that helps users fill in the form. Form validity is expected before sending data to the server (and possibly schema validity). Ideally the UI should be capable of showing validation errors in real-time, when the user fills in a field.
Localization: users expect the form to be on their wiki or preferred language. All labels and informational content in the form should be localized. Also validation errors. Regardless of the renderer pick up it is desired that uses the existing MW i18n message system.
Data submission: a form POST action is generally used in other MW forms. At the time of writing it seems an acceptable mechanism. If we find different needs in T351545 we might want to add other submission mechanisms. Ideally form data will be preserved upon re-authentication. Standard security practices are expected (authentication, protection against CSRF, etc.)
Customisation: potential consumers of CC2.0 should not be locked-in into the form generation system the extension will provide. It should be possible for a consumer to create its own ad-hoc form for a given provider. That could be a standard MW special page (FormSpecialPage) or a different implementation (eg: client side with Vue).

Proposal: UI Form Schema

In order to allow form description decoupled from the data schema and a particular rendering technology a "uischema" definition file would be used. The concept is borrowed from jsonforms/uischema and consists of a JSON definition file which describes the controls, layout and rules of a form. A new "form" key is added to a registered CC2.0 provider:

{
    "CommunityConfigurationProviders": {
        "example": {
            "storage": {
                "type": "wikipage",
                "args": [
                    "MediaWiki:Example.json"
                ]
            },
           "validator": {
                "type": "jsonschema",
                "args": [
                    "relative/path/to/json/schema.json"
                ]
            },
           "form": {
                "type": "htmlform",
                "args": [
                    "relative/path/to/json/uischema.json"
                ]
            }
        }
    }
}

Different types of form can be supported allowing different renderers. The renderer can then use the given data and ui schemas to build a form with needed settings. Here's 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.

The proposal does not intend to introduce a generic form generation tool for MW (although it could align with that objective). The primary intent is to provide a declarative mechanism for form description that can work with existing and future form renders and requires minimal developer effort to integrate CC2.0 with their features.

Open questions

• Do we need to support Javascript-less experience? No, at least there aren't strong objections so far T332849#9435510, although there are challenges of using client side technology, T332849#9467501
• Which JSON data types should the MVP support? string, number, boolean, object and maybe array
• When and how should data be validated? Ideally while users interact with the form. Before submission. Before backend storage.
• What UI library should we use? Codex, starting with its client modules. Adding support for no-JS experience via CodexHTMLForm in a latter iteration
• How to allow for custom form registering? Through the "provider" configuration in its "form" definition. Allowing to register FormSpecial subclasses.

Latest designs

Figma designs

Timebox: two days