Update documentation for group feature in webform_hooks.php

here's a patch. i changed "field" to "component" in the comments on each feature. i added a section about components with multiple fields, and made another minor change to the wording of the features documentation,

quicksketch, thanks for your feeback!

i agree that _webform_submit_component() hook is a good place for this paragraph.

but i don't think that date, time, grid, or file demonstrate what i'm talking about, they do have some flattening in their submit hooks, but it's a different kind of flattening.

of these four components, only file has render hook that returns an array of fields, instead of just a single form field. i'm trying to explain how to handle custom components that contain deep arrays of form fields, as opposed to single fields or a single array of fields.

let me try to explain it better, at the risk of being waaaaay too verbose.

let's say you have a simple custom component that provides a single form field. its render function returns an element like:

$element = array(
  '#type' => 'textfield',
  '#title' => t('simple text field'),
  ...

if you submit a form with this component it will generate one row in webform_submitted_data. grid, date, and time are all like this - they render a single field. for date and time, the value gets expanded into an array, and then re-flattened into a single value.

now let's say you have a more complex custom component that renders an array of form fields:

$element['more_complex_textarea] = array('...');
$element['more_complex_select'] = array('...');

there's no need to flatten this element. if you submit a form with this component, you'll get one row in webform_submitted_data for each field in the $element array. if for some reason you wanted a single row instead of multiple rows, you could flattening $values in the submit hook, like the file component does.

finally, let's say you have a component that is deeply nested. i don't have a great use case for this besides my need to provide a component with multiple fieldsets. it probably is an obscure use case, but i spent enough time debugging webform to figure out why it was throwing away my data, that i'd like to save someone else the time if i can :)

$element['deep_fieldset'] = array(
  '#type' = 'fieldset',
  '#title' = t('First fieldset'),
  'nested_field' => array('#type' => 'textfield', ...'),
  'another_nested_field' => array('...')
);
$element['second_fieldset'] = array('...');

so now we have an array with 3 levels coming out of the render element. when you submit a form with this component, you have a data structure like (iirc) $form_state['values']['submitted'][$form_key]['deep_fieldset']['nested_field']. when _webform_client_form_submit_flatten() recurses through this array it confused, and you end up losing data.

for components like this, assuming you want to save each of the nested field values to the database (that's my use case), you have to flatten the array in the submit handler or set #parents for each nested field to e.g. array('submitted', 'form_key', 'nested_field') to avoid losing the data.

here's a reroll of the patch with the paragraph in question moved to _webform_component_submit() and lightly edited