Introduce FormElementStatesBuilder for #states key of form element render array

Created on 5 November 2018, almost 6 years ago
Updated 3 March 2023, over 1 year ago

Problem/Motivation

Current #states DX is the same as it is with Renderable array - developer should remember all states and conditions, nesting of the arrays, or every time refers to the documentation how to build #states array.

Proposed resolution

Create FormElementStateBuilder class that would be easy to convert into the correct array.
Multiple states and conditions also should be covered with new functionality.
Document states and conditions in the code as interfaces. It should improve DX in creating #states for the form elements.

So instead of:

  '#states' => [
    'visible' => [
      ':input[name="remote_checkbox"]' => ['checked' => TRUE],
    ],
  ],

we can use:


use Drupal\Core\Form\States\FormElementStateBuilder;

// ...
$states = new FormElementStateBuilder();
// ...
'#states' => $states->addStates(
  $states->state()->setVisible(
    $states->watch(':input[name="remote_checkbox"]')->isChecked(),
  )
),

and use all benefits of auto-completion and documenting of the constants.

Remaining tasks

Implement API.
Add states and conditions documentation #3022838: Document states and conditions in the code .
Add tests.
Update documentation to refer to the new API.

User interface changes

none

API changes

New class FormElementStatesBuilder - states container and components provider.
New class FormElementState - represent a single state which can contain multiple remote conditions
New class FormElementWatcher - container of the specific selector and expected remote condition to react.
New class FormElementWatcherConditionGroup - wrapper for Watcher instances which must be a part of AND, OR, or XOR logic.

Data model changes

none

Feature request
Status

Needs work

Version

10.1

Component
Form 

Last updated about 11 hours ago

Created by

🇺🇦Ukraine voleger Ukraine, Rivne

Live updates comments and jobs are added and updated live.
  • Needs change record

    A change record needs to be drafted before an issue is committed. Note: Change records used to be called change notifications.

Sign in to follow issues

Comments & Activities

Not all content is available!

It's likely this issue predates Contrib.social: some issue and comment data are missing.

Production build 0.71.5 2024