filter_process_format

Versions

mediamosa-21

filter_process_format($element)

Expands an element into a base element with text format selector attached.

The form element will be expanded into two separate form elements, one holding the original element, and the other holding the text format selector:

• value: Holds the original element, having its #type changed to the value of #base_type or 'textarea' by default.
• format: Holds the text format fieldset and the text format selection, using the text format id specified in #format or the user's default format by default, if NULL.

Since most modules expect the value of the new 'format' element *next* to the original element, filter_process_format() utilizes an #after_build to move the values of the children of the 'text_format' element so as to let the submitted form values appear as if they were located on the same level. For example, considering the input values:

<?php

$form_state['input']['body']['value'] = 'foo';
$form_state['input']['body']['format'] = 'foo';

?>

The #after_build will process them into:

<?php

$form_state['values']['body'] = 'foo';
$form_state['values']['format'] = 'foo';

?>

If multiple text format-enabled elements are required on the same level of the form structure, modules can set custom #parents on the original element. Alternatively, the #after_build may be unset through a subsequent #process callback. If the default #after_build is not invoked and no custom processing occurs, then the submitted form values will appear like in the $form_state['input'] array above.

See also

filter_form_after_build()

Parameters

$element The form element to process. Properties used:

• #base_type: The form element #type to use for the 'value' element. 'textarea' by default.
• #format: (optional) The text format id to preselect. If 0, NULL, or not set, the default format for the current user will be used.

Return value

The expanded element.

Code

modules/filter/filter.module, line 764

<?php
function filter_process_format($element) {
  global $user;

  // Ensure that children appear as subkeys of this element.
  $element['#tree'] = TRUE;
  $blacklist = array(
    // Make form_builder() regenerate child properties.
    '#parents',
    '#id',
    '#name',
    // Do not copy this #process function to prevent form_builder() from
    // recursing infinitely.
    '#process',
    // Description is handled by theme_text_format_wrapper().
    '#description',
    // Ensure proper ordering of children.
    '#weight',
    // Properties already processed for the parent element.
    '#prefix',
    '#suffix',
    '#attached',
    '#processed',
    '#theme_wrappers',
  );
  // Move this element into sub-element 'value'.
  unset($element['value']);
  foreach (element_properties($element) as $key) {
    if (!in_array($key, $blacklist)) {
      $element['value'][$key] = $element[$key];
    }
  }

  $element['value']['#type'] = $element['#base_type'];
  $element['value'] += element_info($element['#base_type']);

  // Turn original element into a text format wrapper.
  $path = drupal_get_path('module', 'filter');
  $element['#attached']['js'][] = $path . '/filter.js';
  $element['#attached']['css'][] = $path . '/filter.css';

  // Apply default #after_build behavior.
  $element['#after_build'][] = 'filter_form_after_build';

  // Setup child container for the text format widget.
  $element['format'] = array(
    '#type' => 'fieldset',
    '#attributes' => array('class' => array('filter-wrapper')),
  );

  // Prepare text format guidelines.
  $element['format']['guidelines'] = array(
    '#type' => 'container',
    '#attributes' => array('class' => array('filter-guidelines')),
    '#weight' => 20,
  );
  // Get a list of formats that the current user has access to.
  $formats = filter_formats($user);
  foreach ($formats as $format) {
    $options[$format->format] = $format->name;
    $element['format']['guidelines'][$format->format] = array(
      '#theme' => 'filter_guidelines',
      '#format' => $format,
    );
  }

  // Use the default format for this user if none was selected.
  if (empty($element['#format'])) {
    $element['#format'] = filter_default_format($user);
  }
  $element['format']['format'] = array(
    '#type' => 'select',
    '#title' => t('Text format'),
    '#options' => $options,
    '#default_value' => $element['#format'],
    '#access' => count($formats) > 1,
    '#weight' => 10,
    '#attributes' => array('class' => array('filter-list')),
    '#parents' => array_merge($element['#parents'], array('format')),
  );

  $element['format']['help'] = array(
    '#type' => 'container',
    '#theme' => 'filter_tips_more_info',
    '#attributes' => array('class' => array('filter-help')),
    '#weight' => 0,
  );

  return $element;
}
?>