Problem/Motivation
PluginFormInterface enables a plugin to be used as a part of a larger form.
It is best practice for the parent form to assign the plugin's sub-form into a single array key:
$form['some_key'] = $plugin->buildConfigurationForm(array(), $form_state);However, if the plugin form needs to use #parents, #states, or #limit_validation_errors, it does not know were it is located in the parent form.
Proposed resolution
Document the recommended solution for this problem, i.e., returning a single element with a #process callback from buildConfigurationForm() and constructing the real configuration form in that callback (where $element['#parents'] can be used to calculate the config form's position in the containing form).
Remaining tasks
N/A
User interface changes
N/A
API changes
N/A
Original report by @Sweetchuck
A number of plugins provide form elements to a parent form. These can't use #states or #limit_validation_errors because those need the whole #parents array and the child the form misses the beginning of it.
Suggested resolution:$form['data'] = $this->imageEffect->getForm();
change to$form['data'] = $this->imageEffect->getForm(array('data'));
While it's arguably the whole of $form and $form_state would be also useful to these, being context free is even more useful :)
Some of the actual usage actually put the returned elements in the root like BookManagerInterface::addFormElements do or add the whole thing together like $form += $this->blockForm($form, $form_state). These quite probably don't need an empty array for #parents, just comment that they will land in the root.