Form API option `#tree_skip` for skipping tree structure levels in forms

[quicksketch]

Description of the need

Sometimes when creating a form, it's useful to group fields together in an invisible wrapper using #type = container. This happens commonly when using #ajax to update a section of a form.

The problem with nesting form elements however is that it affects the values within $form_state['values']. Usually the structure of the form and the structure of $form_state['values'] are directly mapped to each other (with the #tree property controlling the nesting behavior.

The $form_state['values'] mapping directly to the form causes problems in a lot of situations where the form values are saved automatically for you, examples include:

• hook_field_widget_settings_form()
• hook_field_settings_form
• system_settings_form()
• Probably many others

Proposed solution

Introduce a companion Form API property: #tree_skip

This new property would make it so that elements nested under a container would not have their values automatically nested within $form_state['values'].

Without #tree_skip:

$form['#tree'] = TRUE;
$form['container'] = array(
  '#type' => 'container',
);
$form['container']['foo'] = array(
  '#type' => 'textfield',
  '#title' => t('Example'),
  '#default_value' = 'hello',
);

// Results in the following:
$form_state['values']['container']['foo']; // hello

With #tree_skip:

$form['#tree'] = TRUE;
$form['container'] = array(
  '#type' => 'container',
  '#tree_skip' => TRUE,
);
$form['container']['foo'] = array(
  '#type' => 'textfield',
  '#title' => t('Example'),
  '#default_value' = 'hello',
);

// Results in the following:
$form_state['values']['foo']; // hello

This would allow the creation of visual-only wrappers such as fieldsets, details, and containers without affecting the submitted values, making creating forms much easier in some situations.

Alternatives that have been considered

In situations where this occurs currently, developers have used the #parents property to override the automatic form values mapping. There is a good blog article on using #parents in Drupal here, which the same concept applies for Backdrop.

Draft of feature description for Press Release (1 paragraph at most)

Backdrop now includes a new Form API property #tree_skip that allows developers to create visual-only wrappers within forms. This makes writing forms that utilize AJAX callbacks or nest elements for display purposes much easier.

[argiepiano]

I'm not sure I understand why we can't use '#tree' => FALSE in the container to avoid the grouping in the $form_state?

[quicksketch]

I'm not sure I understand why we can't use '#tree' => FALSE in the container to avoid the grouping in the $form_state?

I think if we did not have the existing behavior, then that would work well, but right now setting '#tree' => FALSE removes all nesting, rather than just the nesting at the current level.

$form['#tree'] = TRUE;
$form['container1'] = array(
  '#type' => 'container',
);
$form['container1'][['container2'] = array(
  '#type' => 'container',
  '#tree' => FALSE,
);
$form['container1']['container2']['foo'] = array(
  '#type' => 'textfield',
  '#title' => t('Example'),
  '#default_value' = 'hello',
);

// Results in the following, BOTH parents were removed:
$form_state['values']['foo']; // hello

But what I want is:

$form['#tree'] = TRUE;
$form['container1'] = array(
  '#type' => 'container',
);
$form['container1'][['container2'] = array(
  '#type' => 'container',
  '#tree_skip' => TRUE,
);
$form['container1']['container2']['foo'] = array(
  '#type' => 'textfield',
  '#title' => t('Example'),
  '#default_value' = 'hello',
);

// Results in the following, only the skipped parent is removed:
$form_state['values']['container1']['foo']; // hello

This "all or nothing" behavior of #tree, regardless of the depth of the form, makes using it hooks or Views configuration where you're only building a portion of the entire form impractical, because by the time the entire form is assembled, your form element might have any number of parents that weren't there when the smaller part of the form was defined in your hook.

[argiepiano]

I see. That makes sense, and sounds like a good feature. Thanks for the additional explanation.

[argiepiano]

One of the challenges to make this work is how forms are built in form_builder(). This is a recursive function that goes deeper into the form array, and sets #tree and #parents based on the parent settings for those two attributes. The new #tree_skip attribute would imply somehow preserving or passing the whole chain of #tree and #parent settings, since a #tree_skip in level 2 of a form array implies that level 3 would need to somehow access the settings for level 1. Currently, only the previous level is accessible (see loop here). Currently form_builder() is recursed by sending to itself the next array level here. #parent is not so much of an issue, since the parent preserves the whole chain up to that point, but #tree_skip presents the issue of not knowing whether level 1 had '#tree' => TRUE or FALSE when setting level 3 after skipping level 2.

[quicksketch]

Thanks for taking a look! I haven't actually taken a look to see how difficult this would be.

Taking your references, I think this might not be too bad at first review. We have code kind of like this:

function form_builder($form_id, &$element, &$form_state) {
    // ...

    if (!isset($element[$key]['#parents'])) {
      // Set the child element #parents before recursive call to form_builder():
      $element[$key]['#parents'] = $element[$key]['#tree'] && $element['#tree'] ? array_merge($element['#parents'], array($key)) : array($key);
    }

    // ...

    // Below is the recursive call to form_builder():
    $element[$key] = form_builder($form_id, $element[$key], $form_state);

    // ...
}

So if I'm reading this right, that means that #parents is set before recursing into form_builder() for the child $element[$key] variable. So I wonder if it's as simple as changing this one line:

      $element[$key]['#parents'] = $element[$key]['#tree'] && $element['#tree'] ? array_merge($element['#parents'], array($key)) : array($key);

To the slightly more complicated:

      if ($element[$key]['#tree'] && $element['#tree']) {
          $element[$key]['#parents'] = !empty($element[$key]['#tree_skip']) ? $element['#parents'] : array_merge($element['#parents'], array($key))
      }
      else {
         $element[$key]['#parents'] = array($key);
      }

It's probably not quite that simple. Thank you for investigating @argiepiano!