Page MenuHomePhabricator

create a mediawiki core API that is a wrapper for HTMLForm
Open, Needs TriagePublicFeature

Description

Suggested by @Tgr in T155567#11112922

Why

  • improved developer experience for user scripts and gadgets
  • HTMLForm in PHP takes a data array of things on a form you want to create, and outputs HTML in ooui or codex

What

  • create a MediaWiki core API called "htmlform" or similar, that will just call HTMLForm::factory() in PHP
  • inputs will need to be...
    • $displayFormat - ooui, codex, etc.
    • $formItems - a data array containing all the form elements
    • $submitTextMessage - to mimic $form->setSubmitTextMsg()
  • output will be HTML
  • HTMLForm supports PHP callbacks. we'd need to strip those out or ignore those, since an API that just takes data and returns HTML can't use PHP callbacks
  • $context - is a required param for HTMLForm::factory(). probably need to investigate exactly what parts of context HTMLForm uses, then collect that info or set it to reasonable defaults, then mock a Context object
  • HTMLForm really likes using keys from the Messages API. will want to make sure to support raw text strings too, in addition to Messages API keys

Notes

  • there's no MediaWiki-API tag on Phab? interesting
  • example HTMLForm PHP code:
		$questionFields['options'] = [
			'label-message' => 'securepoll-create-label-questions-option',
			'type' => 'cloner',
			'required' => true,
			'create-button-message' => 'securepoll-create-label-options-add',
			'fields' => $optionFields,
			'disabled' => $isRunning,
		];

		$formItems['questions'] = [
			'label-message' => 'securepoll-create-label-questions',
			'type' => 'cloner',
			'row-legend' => 'securepoll-create-questions-row-legend',
			'create-button-message' => 'securepoll-create-label-questions-add',
			'fields' => $questionFields,
			'disabled' => $isRunning,
		];

		$form = HTMLForm::factory(
			'ooui',
			$formItems,
			$this->specialPage->getContext(),
			$this->election ? 'securepoll-edit' : 'securepoll-create'
		);

		$form->setSubmitTextMsg(
			$this->election ? 'securepoll-edit-action' : 'securepoll-create-action'
		);
		$form->prepareForm();

		$form->displayForm( $result );

Event Timeline

HTMLForm is quite terrible but still probably the best we have, and declarative form generation would be super useful IMO. (Ideally there would be a way to generate not just forms but various interactive things like popups or multistep forms declaratively, but that would have to be written from scratch.)

Community Configuration also has a somewhat generic form builder (T332849: [Spike] Investigate form generation options for community configuration / T356622: Community configuration 2.0 editing form MVP) which is Codex-based and client-side-only so maybe there would be a way to use that instead? Or we could adopt a third-party library like Vueform or Formkit and make it work with Codex.

But a HTMLForm API can be implemented with minimal effort, and it's guaranteed to mostly keep working when we switch frameworks the next time.