What is the correct way to save checkboxes values on form submission?

Question

The FAPI documentation gives the following instruction and example:

checkboxes

Description: Format a set of checkboxes. #options is an associative array, where the key is the #return_value of the checkbox and the value is displayed. The #options array cannot have a 0 key, as it would not be possible to discern checked and unchecked states.

$form['high_school']['tests_taken'] = array(
  '#type' => 'checkboxes',
  '#options' => drupal_map_assoc(array(t('SAT'), t('ACT'))),
  '#title' => t('What standardized tests did you take?'),
  ...
),

I have the following element in my form constructor:

'audio_options' => array(
  '#type' => 'checkboxes',
  '#title' => t('Options'),
  '#options' => drupal_map_assoc(array(
    t('Controls'),
    t('Autoplay'),
    t('Loop'),
    t('Buffer'),
  )),
  '#attributes' => array('class' => array('container-inline')),
),

and the following in my submit handler:

$node->field_audio_options[LANGUAGE_NONE] = $form_state['values']['audio_options'];

On submission the error thrown is:

PDOException: SQLSTATE[HY000]: General error: 1366 Incorrect integer value: 'Controls' for column 'delta' at row 1

Why does the documentation say that you can use a string as the options key, when presumably it is saved in the delta column of the field's table, which requires an integer?

What is the correct way to save checkboxes values on form submission?

Thanks.

Answer 1

The arrays aren't of compatible formats, you need to prepare them yourself:

foreach (array_filter($form_state['values']['audio_options']) as $selection) {
  $node->field_audio_options[LANGUAGE_NONE][]['value'] = $selection;
}