text.module

<?php
/**
 * @file
 * Defines simple text field types.
 */

/**
 * Implements hook_field_info().
 *
 * Field settings:
 *   - max_length: the maximum length for a varchar field.
 * Instance settings:
 *   - text_processing: whether text input filters should be used.
 *   - allowed_formats: a list of text formats authors can select from.
 *   - display_summary: whether the summary field should be displayed.
 *     When empty and not displayed the summary will take its value from the
 *     trimmed value of the main text field.
 */
function text_field_info() {
  return array(
    'text' => array(
      'label' => t('Text (short)'),
      'description' => t('This field stores varchar text in the database.'),
      'settings' => array('max_length' => 255),
      'instance_settings' => array(
        'text_processing' => 0,
        'allowed_formats' => array(),
      ),
      'default_widget' => 'text_textfield',
      'default_formatter' => 'text_default',
      'default_token_formatter' => 'text_default',
    ),
    'text_long' => array(
      'label' => t('Text (long)'),
      'description' => t('This field stores long text in the database.'),
      'instance_settings' => array(
        'text_processing' => 0,
        'allowed_formats' => array(),
      ),
      'default_widget' => 'text_textarea',
      'default_formatter' => 'text_default',
      'default_token_formatter' => 'text_default',
    ),
    'text_with_summary' => array(
      'label' => t('Text (long with summary)'),
      'description' => t('This field stores long text in the database along with optional summary text.'),
      'instance_settings' => array(
        'text_processing' => 1,
        'allowed_formats' => array(),
        'display_summary' => 0,
      ),
      'default_widget' => 'text_textarea_with_summary',
      'default_formatter' => 'text_default',
      'default_token_formatter' => 'text_default',
    ),
  );
}

/**
 * Implements hook_field_settings_form().
 */
function text_field_settings_form($field, $instance, $has_data) {
  $settings = $field['settings'];

  $form = array();

  if ($field['type'] == 'text') {
    $form['max_length'] = array(
      '#type' => 'number',
      '#title' => t('Maximum length'),
      '#default_value' => $settings['max_length'],
      '#required' => TRUE,
      '#description' => t('The maximum length of the field in characters.'),
      '#min' => 1,
      '#max' => 1000000000,
      '#disabled' => $has_data,
    );
  }

  return $form;
}

/**
 * Implements hook_field_instance_settings_form().
 */
function text_field_instance_settings_form($field, $instance) {
  $settings = $instance['settings'];
  $fallback_format = filter_fallback_format();

  $format_options = array();
  foreach (filter_formats() as $format) {
    $format_options[$format->format] = $format->name;
  }
  $format_options[$fallback_format] .= ' ' . t('(fallback format)');

  $form['#element_validate'][] = 'text_field_instance_settings_form_validate';

  $form['text_processing'] = array(
    '#type' => 'radios',
    '#title' => t('Text processing'),
    '#default_value' => $settings['text_processing'],
    '#options' => array(
      t('Plain text'),
      t('Filtered text (user selects text format)'),
    ),
    '#weight' => -2,
  );

  // An empty array of formats indicates all formats are allowed.
  $allowed_formats = empty($settings['allowed_formats']) ?
    array_keys($format_options) : $settings['allowed_formats'];

  $form['allowed_formats'] = array(
    '#type' => 'checkboxes',
    '#title' => t('Allowed text formats'),
    '#default_value' => $allowed_formats,
    '#description' => t('Choose which <a href="@text_formats">text formats</a> should be available for authors. If an author does not have permission to a format on existing content, the field will be locked.', array('@text_formats' => url('admin/config/content/formats'))),
    '#options' => $format_options,
    '#states' => array(
      'visible' => array(
        'input[name="instance[settings][text_processing]"]' => array('value' => 1),
      ),
    ),
    '#weight' => -1,
  );

  // Display the fallback format as disabled but locked in the enabled state.
  $form['allowed_formats'][$fallback_format]['#value'] = 'plain_text';
  $form['allowed_formats'][$fallback_format]['#disabled'] = TRUE;

  if ($field['type'] == 'text_with_summary') {
    $form['display_summary'] = array(
      '#type' => 'checkbox',
      '#title' => t('Summary input'),
      '#default_value' => $settings['display_summary'],
      '#description' => t('This allows authors to input an explicit summary, to be displayed instead of the automatically trimmed text when using the "Summary or trimmed" display type.'),
      '#weight' => 0,
    );
  }

  return $form;
}

/**
 * Element validate handler for text_field_instance_settings_form().
 */
function text_field_instance_settings_form_validate($element, &$form_state, $complete_form) {
  $all_formats = array_keys($element['allowed_formats']['#options']);
  $enabled_formats = array_keys(array_filter($element['allowed_formats']['#value']));
  $enabled_formats[] = filter_fallback_format();
  // If all formats are enabled, save as an empty array, which implies no
  // restrictions on this field's formats.
  if ($all_formats == $enabled_formats) {
    $enabled_formats = array();
  }
  form_set_value($element['allowed_formats'], $enabled_formats, $form_state);
}

/**
 * Implements hook_field_validate().
 *
 * Possible error codes:
 * - 'text_value_max_length': The value exceeds the maximum length.
 * - 'text_summary_max_length': The summary exceeds the maximum length.
 */
function text_field_validate($entity_type, $entity, $field, $instance, $langcode, $items, &$errors) {
  foreach ($items as $delta => $item) {
    // @todo The maximum length can be exceeded because length is counted
    // separately for summary and value.
    foreach (array('value', 'summary') as $column) {
      if (!empty($item[$column])) {
        if (!empty($field['settings']['max_length']) && backdrop_strlen($item[$column]) > $field['settings']['max_length']) {
          switch ($column) {
            case 'value':
              $message = t('%name: the text may not be longer than %max characters.', array('%name' => $instance['label'], '%max' => $field['settings']['max_length']));
              break;

            case 'summary':
              $message = t('%name: the summary may not be longer than %max characters.', array('%name' => $instance['label'], '%max' => $field['settings']['max_length']));
              break;
          }
          $errors[$field['field_name']][$langcode][$delta][] = array(
            'error' => "text_{$column}_length",
            'message' => $message,
          );
        }
      }
    }
  }
}

/**
 * Implements hook_field_load().
 *
 * Where possible, generate the sanitized version of each field early so that
 * it is cached in the field cache. This avoids looking up from the filter cache
 * separately.
 *
 * @see text_field_formatter_view()
 */
function text_field_load($entity_type, $entities, $field, $instances, $langcode, &$items) {
  foreach ($entities as $id => $entity) {
    foreach ($items[$id] as $delta => $item) {
      // Only process items with a cacheable format, the rest will be handled
      // by formatters if needed.
      if (empty($instances[$id]['settings']['text_processing']) || ($item['format'] && filter_format_allowcache($item['format']))) {
        $items[$id][$delta]['safe_value'] = isset($item['value']) ? _text_sanitize($instances[$id], $langcode, $item, 'value') : '';
        if ($field['type'] == 'text_with_summary') {
          $items[$id][$delta]['safe_summary'] = isset($item['summary']) ? _text_sanitize($instances[$id], $langcode, $item, 'summary') : '';
        }
      }
    }
  }
}

/**
 * Implements hook_field_is_empty().
 */
function text_field_is_empty($item, $field, $instance = NULL) {
  if (!isset($item['value']) || $item['value'] === '') {
    if (isset($item['format']) && $item['format'] !== '' && !_text_field_uses_default_format($item, $instance)) {
      // If this text field has a text format setting, save it regardless of
      // empty value to keep the format. Unless it's the default format.
      return FALSE;
    }
    elseif (!isset($item['summary']) || $item['summary'] === '') {
      // Neither value nor summary nor format are set,
      // no need to save to database.
      return TRUE;
    }
  }
  return FALSE;
}

/**
 * Utility to determine whether the default format is in use.
 *
 * @param array $item
 *   Values from text field.
 * @param array|null $instance
 *   Field API instance definition.
 *
 * @return bool
 */
function _text_field_uses_default_format($item, $instance) {
  if (isset($item['format'])) {
    // The global default value for current account.
    if ($item['format'] == filter_default_format()) {
      return TRUE;
    }
    if (!empty($instance)) {
      // Instance default value setting.
      if (!empty($instance['default_value']) && $instance['default_value'][0]['format'] == $item['format']) {
        return TRUE;
      }
      // There's a format restriction and this is the first, possibly only
      // available format for this field instance.
      if (!empty($instance['settings']['allowed_formats']) && $instance['settings']['allowed_formats'][0] == $item['format']) {
        return TRUE;
      }
    }
  }
  return FALSE;
}

/**
 * Implements hook_field_formatter_info().
 */
function text_field_formatter_info() {
  return array(
    'text_default' => array(
      'label' => t('Default'),
      'field types' => array('text', 'text_long', 'text_with_summary'),
    ),
    'text_plain' => array(
      'label' => t('Plain text'),
      'field types' => array('text', 'text_long', 'text_with_summary'),
    ),

    // The text_trimmed formatter displays the trimmed version of the
    // full element of the field. It is intended to be used with text
    // and text_long fields. It also works with text_with_summary
    // fields though the text_summary_or_trimmed formatter makes more
    // sense for that field type.
    'text_trimmed' => array(
      'label' => t('Trimmed'),
      'field types' => array('text', 'text_long', 'text_with_summary'),
      'settings' => array('trim_length' => 600),
    ),

    // The 'summary or trimmed' field formatter for text_with_summary
    // fields displays returns the summary element of the field or, if
    // the summary is empty, the trimmed version of the full element
    // of the field.
    'text_summary_or_trimmed' => array(
      'label' => t('Summary or trimmed'),
      'field types' => array('text_with_summary'),
      'settings' => array('trim_length' => 600),
    ),
  );
}

/**
 * Implements hook_field_formatter_settings_form().
 */
function text_field_formatter_settings_form($field, $instance, $view_mode, $form, &$form_state) {
  $display = $instance['display'][$view_mode];
  $settings = $display['settings'];

  $element = array();

  if (strpos($display['type'], '_trimmed') !== FALSE) {
    $element['trim_length'] = array(
      '#title' => t('Trimmed limit'),
      '#type' => 'number',
      '#max' => 1000000,
      '#field_suffix' => t('characters'),
      '#default_value' => $settings['trim_length'],
      '#min' => 1,
      '#required' => TRUE,
      '#description' => t('If the summary is not set, the trimmed %label field will be shorter than this character limit.', array('%label' => $instance['label'])),
    );
  }

  if ($display['type'] == 'text_trimmed') {
    $element['trim_length']['#description'] = t('The trimmed %label field will be shorter than this character limit.', array('%label' => $instance['label']));
  }

  return $element;
}

/**
 * Implements hook_field_formatter_settings_summary().
 */
function text_field_formatter_settings_summary($field, $instance, $view_mode) {
  $display = $instance['display'][$view_mode];
  $settings = $display['settings'];

  $summary = '';

  if (strpos($display['type'], '_trimmed') !== FALSE) {
    $summary = t('Trimmed limit: @trim_length characters', array('@trim_length' => $settings['trim_length']));
  }

  return $summary;
}

/**
 * Implements hook_field_formatter_view().
 */
function text_field_formatter_view($entity_type, $entity, $field, $instance, $langcode, $items, $display) {
  $element = array();

  switch ($display['type']) {
    case 'text_default':
    case 'text_trimmed':
      foreach ($items as $delta => $item) {
        if (empty($item['value'])) {
          continue;
        }
        $output = _text_sanitize($instance, $langcode, $item, 'value');
        if ($display['type'] == 'text_trimmed') {
          $output = text_summary($output, $instance['settings']['text_processing'] ? $item['format'] : NULL, $display['settings']['trim_length']);
        }
        $element[$delta] = array('#markup' => $output);
      }
      break;

    case 'text_summary_or_trimmed':
      foreach ($items as $delta => $item) {
        if (empty($item['summary']) && empty($item['value'])) {
          continue;
        }
        if (!empty($item['summary'])) {
          $output = _text_sanitize($instance, $langcode, $item, 'summary');
        }
        else {
          $output = _text_sanitize($instance, $langcode, $item, 'value');
          $output = text_summary($output, $instance['settings']['text_processing'] ? $item['format'] : NULL, $display['settings']['trim_length']);
        }
        $element[$delta] = array('#markup' => $output);
      }
      break;

    case 'text_plain':
      foreach ($items as $delta => $item) {
        $element[$delta] = array('#markup' => strip_tags($item['value']));
      }
      break;
  }

  return $element;
}

/**
 * Sanitizes the 'value' or 'summary' data of a text value.
 *
 * Depending on whether the field instance uses text processing, data is run
 * through check_plain() or check_markup().
 *
 * @param $instance
 *   The instance definition.
 * @param $langcode
 *  The language associated to $item.
 * @param $item
 *   The field value to sanitize.
 * @param $column
 *   The column to sanitize (either 'value' or 'summary').
 *
 * @return
 *  The sanitized string.
 */
function _text_sanitize($instance, $langcode, $item, $column) {
  // If the value uses a cacheable text format, text_field_load() pre-computes
  // the sanitized string.
  if (isset($item["safe_$column"])) {
    return $item["safe_$column"];
  }
  return $instance['settings']['text_processing'] ? check_markup($item[$column], $item['format'], $langcode) : check_plain($item[$column]);
}

/**
 * Generate a trimmed, formatted version of a text field value.
 *
 * If the end of the summary is not indicated using the <!--break--> delimiter
 * then we generate the summary automatically, trying to end it at a sensible
 * place such as the end of a paragraph, a line break, or the end of a
 * sentence (in that order of preference).
 *
 * @param $text
 *   The content for which a summary will be generated.
 * @param $format_id
 *   The format of the content.
 *   If the PHP filter is present and $text contains PHP code, we do not
 *   split it up to prevent parse errors.
 *   If the line break filter is present then we treat newlines embedded in
 *   $text as line breaks.
 *   If the htmlcorrector filter is present, it will be run on the generated
 *   summary (if different from the incoming $text).
 * @param $size
 *   The desired character length of the summary. If omitted, the default
 *   value will be used. Ignored if the special delimiter is present
 *   in $text.
 * @return
 *   The generated summary.
 */
function text_summary($text, $format_id = NULL, $size = 600) {
  // Find where the delimiter is in the body
  $delimiter = strpos($text, '<!--break-->');

  // If the size is zero, and there is no delimiter, the entire body is the summary.
  if ($size == 0 && $delimiter === FALSE) {
    return $text;
  }

  // If a valid delimiter has been specified, use it to chop off the summary.
  if ($delimiter !== FALSE) {
    return substr($text, 0, $delimiter);
  }

  // Only attempt to load a format, if $format_id is not NULL, anyway.
  $format = FALSE;
  if ($format_id) {
    $format = filter_format_load($format_id);
  }

  // If we have a short body, the entire body is the summary.
  if (backdrop_strlen($text) <= $size) {
    return $text;
  }

  // If the delimiter has not been specified, try to split at paragraph or
  // sentence boundaries.

  // The summary may not be longer than maximum length specified. Initial slice.
  $summary = truncate_utf8($text, $size);

  // Store the actual length of the UTF8 string -- which might not be the same
  // as $size.
  $max_rpos = strlen($summary);

  // How much to cut off the end of the summary so that it doesn't end in the
  // middle of a paragraph, sentence, or word.
  // Initialize it to maximum in order to find the minimum.
  $min_rpos = $max_rpos;

  // Store the reverse of the summary. We use strpos on the reversed needle and
  // haystack for speed and convenience.
  $reversed = strrev($summary);

  // Build an array of arrays of break points grouped by preference.
  $break_points = array();

  // A paragraph near the end of sliced summary is most preferable.
  $break_points[] = array('</p>' => 0);

  // If no complete paragraph then treat line breaks as paragraphs.
  $line_breaks = array('<br />' => 6, '<br>' => 4);
  // Newline only indicates a line break if line break converter
  // filter is enabled.
  if ($format && isset($format->filters['filter_autop']) && $format->filters['filter_autop']->status) {
    $line_breaks["\n"] = 1;
  }
  $break_points[] = $line_breaks;

  // If the first paragraph is too long, split at the end of a sentence.
  // Typing a number after the ؟ character (Arabic question mark) causes text to
  // be reversed mid-line. That's the reason why the last element in this array
  // may seem odd. It actually produces valid code.
  // See https://github.com/backdrop/backdrop-issues/issues/4546
  $break_points[] = array('. ' => 1, '! ' => 1, '? ' => 1, '。' => 0, '؟ ' => 1);

  // Iterate over the groups of break points until a break point is found.
  foreach ($break_points as $points) {
    // Look for each break point, starting at the end of the summary.
    foreach ($points as $point => $offset) {
      // The summary is already reversed, but the break point isn't.
      $rpos = strpos($reversed, strrev($point));
      if ($rpos !== FALSE) {
        $min_rpos = min($rpos + $offset, $min_rpos);
      }
    }

    // If a break point was found in this group, slice and stop searching.
    if ($min_rpos !== $max_rpos) {
      // Don't slice with length 0. Length must be <0 to slice from RHS.
      $summary = ($min_rpos === 0) ? $summary : substr($summary, 0, 0 - $min_rpos);
      break;
    }
  }

  // Trim opening tag fragment like previous versions of libxml did.
  $summary = rtrim($summary, '<');

  // Clean up any invalid HTML.
  if (function_exists('_filter_htmlcorrector')) {
    $summary = _filter_htmlcorrector($summary);
  }

  return $summary;
}

/**
 * Implements hook_field_widget_info().
 */
function text_field_widget_info() {
  return array(
    'text_textfield' => array(
      'label' => t('Text field'),
      'field types' => array('text_long', 'text'),
      'settings' => array('size' => 60),
    ),
    'text_textarea' => array(
      'label' => t('Text area (multiple rows)'),
      'field types' => array('text', 'text_long'),
      'settings' => array('rows' => 5),
    ),
    'text_textarea_with_summary' => array(
      'label' => t('Text area with a summary'),
      'field types' => array('text_with_summary'),
      'settings' => array('rows' => 10, 'summary_rows' => 5),
    ),
  );
}

/**
 * Implements hook_field_widget_settings_form().
 */
function text_field_widget_settings_form($field, $instance) {
  $widget = $instance['widget'];
  $settings = $widget['settings'];

  if ($widget['type'] == 'text_textfield') {
    $form['size'] = array(
      '#type' => 'number',
      '#title' => t('Size of textfield'),
      '#default_value' => $settings['size'],
      '#required' => TRUE,
      '#min' => 1,
    );
  }
  else {
    $form['rows'] = array(
      '#type' => 'number',
      '#title' => t('Rows'),
      '#description' => t('The number of visible lines in the text area.'),
      '#default_value' => $settings['rows'],
      '#required' => TRUE,
      '#min' => 1,
    );
  }

  return $form;
}

/**
 * Implements hook_field_widget_form().
 */
function text_field_widget_form(&$form, &$form_state, $field, $instance, $langcode, $items, $delta, $element) {
  $summary_widget = array();
  $main_widget = array();

  switch ($instance['widget']['type']) {
    case 'text_textfield':
      $main_widget = $element + array(
        '#type' => 'textfield',
        '#default_value' => isset($items[$delta]['value']) ? $items[$delta]['value'] : NULL,
        '#size' => $instance['widget']['settings']['size'],
        '#attributes' => array('class' => array('text-full')),
      );
      // If the field itself has a maxlength include that on the widget.
      if (isset($field['settings']['max_length'])) {
        $main_widget['#maxlength'] = $field['settings']['max_length'];
      }
      break;

    case 'text_textarea_with_summary':
      $display = !empty($items[$delta]['summary']) || !empty($instance['settings']['display_summary']);
      $summary_widget = array(
        '#type' => $display ? 'textarea' : 'value',
        '#default_value' => isset($items[$delta]['summary']) ? $items[$delta]['summary'] : NULL,
        '#title' => t('Summary'),
        '#rows' => $instance['widget']['settings']['summary_rows'],
        '#description' => t('Leave blank to use trimmed value of full text as the summary.'),
        '#attached' => array(
          'js' => array(backdrop_get_path('module', 'text') . '/js/text.js'),
        ),
        '#attributes' => array('class' => array('text-summary')),
        '#prefix' => '<div class="text-summary-wrapper">',
        '#suffix' => '</div>',
        '#weight' => -10,
      );
      // Fall through to the next case.

    case 'text_textarea':
      $main_widget = $element + array(
        '#type' => 'textarea',
        '#default_value' => isset($items[$delta]['value']) ? $items[$delta]['value'] : NULL,
        '#rows' => $instance['widget']['settings']['rows'],
        '#attributes' => array('class' => array('text-full')),
      );
      break;
  }

  if ($main_widget) {
    // Conditionally alter the form element's type if text processing is enabled.
    if ($instance['settings']['text_processing']) {
      $element = $main_widget;
      $element['#type'] = 'text_format';
      $element['#format'] = isset($items[$delta]['format']) ? $items[$delta]['format'] : NULL;
      $element['#allowed_formats'] = $instance['settings']['allowed_formats'];
      $element['#editor_uploads'] = TRUE;
      $element['#base_type'] = $main_widget['#type'];
    }
    else {
      $element['value'] = $main_widget;
    }
  }
  if ($summary_widget) {
    $element['summary'] = $summary_widget;
  }

  return $element;
}

/**
 * Implements hook_field_widget_error().
 */
function text_field_widget_error($element, $error, $form, &$form_state) {
  switch ($error['error']) {
    case 'text_summary_max_length':
      $error_element = $element[$element['#columns'][1]];
      break;

    default:
      $error_element = $element[$element['#columns'][0]];
      break;
  }

  form_error($error_element, $error['message']);
}

/**
 * Implements hook_field_prepare_translation().
 */
function text_field_prepare_translation($entity_type, $entity, $field, $instance, $langcode, &$items, $source_entity, $source_langcode) {
  // If the translating user is not permitted to use the assigned text format,
  // we must not expose the source values.
  $field_name = $field['field_name'];
  if (!empty($source_entity->{$field_name}[$source_langcode])) {
    $formats = filter_formats();
    foreach ($source_entity->{$field_name}[$source_langcode] as $delta => $item) {
      $format_id = $item['format'];
      if (!empty($format_id) && !filter_access($formats[$format_id])) {
        unset($items[$delta]);
      }
    }
  }
}

/**
 * Implements hook_filter_format_update().
 */
function text_filter_format_update($format) {
  field_cache_clear();
}

/**
 * Implements hook_filter_format_disable().
 */
function text_filter_format_disable($format) {
  field_cache_clear();
}