function filter_process_format

1 filter.module 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.

The resulting value for the element will be an array holding the value and the format. For example, the value for the body element will be:

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

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 name to preselect. If NULL or not set, the default format for the current user will be used.
#allowed_formats: (optional) An array of format names that should be available options. If none are specified, all available formats for the current user are displayed.

Return value

array: The expanded element.

1 string reference to 'filter_process_format'

filter_element_info in core/modules/filter/filter.module: Implements hook_element_info().

File

core/modules/filter/filter.module, line 1272: Framework for handling the filtering of content.

Code

function filter_process_format($element) {
  global $user;

  // Ensure that children appear as subkeys of this element.
  $element['#tree'] = TRUE;
  $denylist = array(
    // Make form_builder() regenerate child properties.
    '#parents',
    '#id',
    '#name',
    // Do not copy this #process function to prevent form_builder() from
    // recursing infinitely.
    '#process',
    // Ensure proper ordering of children.
    '#weight',
    // Properties already processed for the parent element.
    '#prefix',
    '#suffix',
    '#attached',
    '#processed',
    '#theme_wrappers',
  );

  // If the #description is set to be placed after the element (which is the
  // default), let theme_text_format_wrapper() handle it. Otherwise, if the
  // #description is set to be placed before the element, or set to invisible,
  // then it would be rendered between the text-format-enabled area and the
  // "Formatting options" fieldset.
  if ($element['#description_display'] == 'after') {
    $denylist[] = '#description';
  }

  // Move this element into sub-element 'value'.
  unset($element['value']);
  foreach (element_properties($element) as $key) {
    if (!in_array($key, $denylist)) {
      $element['value'][$key] = $element[$key];
    }
  }

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

  // Get a list of allowed formats to which the current user has access.
  $formats = filter_formats($user);
  $fallback_format = filter_fallback_format();

  // Turn original element into a text format wrapper. Settings for all
  // available formats are added to make them available for all fields.
  if (isset($element['#attached'])) {
    $element['#attached'] = array_merge_recursive($element['#attached'], filter_get_attached($formats));
  }
  else {
    $element['#attached'] = filter_get_attached($formats);
  }

  // Reduce the list if a list of allowed formats was provided.
  if (!empty($element['#allowed_formats'])) {
    foreach ($formats as $format) {
      if ($format->format !== $fallback_format && 
        !in_array($format->format, $element['#allowed_formats'])) {
        unset($formats[$format->format]);
      }
    }
  }

  // Specify if uploads are allowed by using a data attribute.
  $element['value']['#attributes']['data-editor-uploads'] = empty($element['#editor_uploads']) ? 'false' : 'true';

  // Use the default format for this user if none was selected.
  if (!isset($element['#format'])) {
    $element['#format'] = filter_default_format($user);
  }

  // Remove the Plain text format if not set and other options are available.
  if (($element['#format'] != $fallback_format) && (count($formats) > 1) && array_key_exists($fallback_format, $formats)) {
    unset($formats[$fallback_format]);
  }

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

  // Prepare text format guidelines.
  $element['format']['guidelines'] = array(
    '#type' => 'container',
    '#attributes' => array('class' => array('filter-guidelines')),
    '#weight' => 20,
  );
  $options = array();
  foreach ($formats as $format) {
    $options[$format->format] = check_plain($format->name);
    $element['format']['guidelines'][$format->format] = array(
      '#theme' => 'filter_guidelines',
      '#format' => $format,
    );
  }

  // If there are multiple options OR if the current text format is no longer
  // available to the current user, then show as a select.
  if (count($options) > 1 || !array_key_exists($element['#format'], $options)) {
    $element['format']['format'] = array(
      '#type' => 'select',
      '#title' => t('Editor'),
      '#options' => $options,
      '#default_value' => $element['#format'],
      '#weight' => 10,
      '#attributes' => array('class' => array('filter-list')),
      '#parents' => array_merge($element['#parents'], array('format')),
    );
  }
  // If there's only a single text format available to the current user, then
  // render it as a hidden form element.
  else {
    $element['format']['format'] = array(
      '#type' => 'hidden',
      '#value' => $element['#format'],
      '#default_value' => $element['#format'],
      '#attributes' => array(
        'class' => array('filter-list'),
        // Add the human-readable name of the text format, so it can be used as
        // the fieldset summary.
        'data-text-format-name' => check_plain($options[$element['#format']]),
      ),
      '#parents' => array_merge($element['#parents'], array('format')),
    );
  }

  $all_formats = filter_formats();
  $format_exists = isset($all_formats[$element['#format']]);
  $user_has_access = isset($formats[$element['#format']]);
  $user_is_admin = user_access('administer filters');

  // If the stored format does not exist, administrators have to assign a new
  // format.
  if (!$format_exists && $user_is_admin) {
    $element['format']['format']['#required'] = TRUE;
    $element['format']['format']['#default_value'] = NULL;
    // Force access to the format selector (it may have been denied above if the
    // user only has access to a single format).
    $element['format']['format']['#access'] = TRUE;
  }
  // Disable this widget, if the user is not allowed to use the stored format,
  // or if the stored format does not exist, and only if the field is not empty.
  // The 'administer filters' permission only grants access to the filter
  // administration, not to all formats.
  elseif (!$user_has_access || !$format_exists) {
    if (!empty($element['#default_value'])) {
      // Overload default values into #value to make them unalterable.
      $element['value']['#value'] = $element['value']['#default_value'];
      $element['format']['format']['#value'] = $element['format']['format']['#default_value'];

      // Prepend #pre_render callback to replace field value with user notice
      // prior to rendering.
      $element['value'] += array('#pre_render' => array());
      array_unshift($element['value']['#pre_render'], 'filter_form_access_denied');

      // Cosmetic adjustments.
      if (isset($element['value']['#rows'])) {
        $element['value']['#rows'] = 3;
      }
      $element['value']['#disabled'] = TRUE;
      $element['value']['#resizable'] = 'none';

      // Hide the text format selector and any other child element (such as text
      // field's summary).
      foreach (element_children($element) as $key) {
        if ($key != 'value') {
          $element[$key]['#access'] = FALSE;
        }
      }
    }
  }

  return $element;
}