Drupal API

hook_filter

  • Drupal 5
  • Drupal 6
Тебя еще не убедили эти надписи? Присоединяйся к нам, вместе мы все здесь переведем!

developer/hooks/core.php, строка 597

Версии
5
hook_filter($op, $delta = 0, $format = -1, $text = '')
6
hook_filter($op, $delta = 0, $format = -1, $text = '', $cache_id = 0)

Определяет фильтры пользовательского ввода.

Контент в Друпале проходит через все включенные фильтры перед выводом. Это позволяет модулям изменять контент так, как необходимо администрации сайта.

Этот хук содержит все необходимое для того, чтобы модуль смог предоставить возможность функциональности фильтрации.

В зависимости от значения переменной $op выполняются различные действия.

Модуль может содержать столько фильтров, сколько необходимо. Операция 'list' объявляет системе фильтрации какие фильтры предоставляет модуль. Каждый фильтр имеет номер 'delta', по которому к нему можно обратиться в любой операции.

Процесс фильтрации состоит из двух шагов. Сперва, контент проходит стадию 'prepare' (подготовки), когда вызывается операция 'prepare' для каждого фильтра. Цель операции 'prepare' - добавить эскейпы в HTML-подобные структуры. К примеру, представьте фильтр, позволяющий пользователю вставить целые куски кода, без требования вручную экранировать HTML спец-символы, типа @< или @&. Если оставить этот кусок кода нетронутым, тогда другие фильтры могут подумать, что это HTML и поменять его. Тем не менее, для большинства фильтров, шаг подготовки ('prepare') необязателен, и они могут просто вернуть элемент ввода без изменений.

Фильтры не должны использовать шаг 'prepare' для чего либо ещё, кроме экранирования символов, иначе это может "закоротить" контроль пользователя над порядком, в котором применяются фильтры.

Второй шаг - это сама обработка. Результат подготовительного ('prepare') шага проходит опять через все фильтры, на этот раз - операцию 'process'. Именно здесь фильтры должны делать изменения в контенте: заменять URL-ы на линки, смайлики - на соответсвующие изображения, и т.д.

Важным аспектом системы фильтрации являются 'input formats' (форматы ввода). Каждый формат ввода - это целая настройка фильтра: какие фильтры включить, в каком порядке и с какими настройками. Фильтры, которые предоставляют возможность настройки, должны обычно сохранять эти настройки для каждого формата в отдельности.

Если поведение фильтра зависит от большого списка и/или внешних данных (например, списка смайлов или глоссария терминов) фильтрам разрешено предоставлять отдельную, глобальную страницу конфигурации вместо краткого списка настроек для формата. В таком случае, в настройках формата должна быть ссылка на отдельную страницу настроек.

Из соображений производительности контент фильтруется один раз; результат сохраняется в таблице кеша и получается из базы каждый раз когда данный контент отображается. Если вывод фильтра должен быть динамическим, он может перегрузить механизм кеша, но эту возможность следует использовать с осторожностью: один некешируемый фильтр в формате отключает кеширование для всего формата, не только для этого фильтра.

При разработке своего модуля нужно иметь в виду механизм работы фильтра: рекомендуется обозначать фильтр как 'не кешируемый' при разработке, но включать кеширование когда оно нужно. Кеш можно очистить выполнив SQL запрос 'DELETE FROM cache_filter';

Для детальных примеров использования, см. filter_example.module. Для примеров использования нескольких фильтров в одном модуле, см. filter_filter() и filter_filter_tips().

Параметры

$op Производимая операция. Возможные значения:

  • 'list': список доступных фильтров. Возвращает ассоциативный массив названий фильтров с их номерными ключами. Эти ключи используются для последующих операций и передаются через параметр $delta.
  • 'no cache': Возвращает true если кеширование должно быть отключено для этого фильтра.
  • 'description': Возвращает краткое описание того, что делает данный фильтр.
  • 'prepare': Возвращает подготовленный к обработке контент в переменной $text.
  • 'process': Возвращает обработанный контент в переменной $text.
  • 'settings': Возвращает HTML формы настроек фильтра. Эти настройки сохраняются с помощью variable_set() после отправки формы. Помните о необходимости использовать идентификатор $format в переменных и именах полей форм в настройках формата (например 'mymodule_setting_$format').
$delta Который фильтр из предоставленных модулем использовать (применимо к любой операции кроме 'list'). Модули, содержащие только один фильтр, могут проигнорировать этот параметр.

$format В каком формате используется фильтр (применимо к 'prepare', 'process' и 'settings').

$text Контент для фильтрации (применимо к 'prepare' и 'process').

$cache_id ID кэша контента.

Возвращаемое значение

Возвращаемое значение зависит от значения переменной $op. Хук фильтра разработан таким образом что модуль может вернуть $text для операций которые им не используются.

Связанные темы

Код

<?php
function hook_filter($op, $delta = 0, $format = -1, $text = '', $cache_id = 0) {
  switch ($op) {
    case 'list':
      return array(0 => t('Code filter'));
    case 'description':
      return t('Allows users to post code verbatim using <code> and <?php ?> tags.');
    case 'prepare':
      // Note: we use the bytes 0xFE and 0xFF to replace < > during the
      // filtering process. These bytes are not valid in UTF-8 data and thus
      // least likely to cause problems.
      $text = preg_replace('@<code>(.+?)</code>@se', "'\xFEcode\xFF'. codefilter_escape('\\1') .'\xFE/code\xFF'", $text);
      $text = preg_replace('@<(\?(php)?|%)(.+?)(\?|%)>@se', "'\xFEphp\xFF'. codefilter_escape('\\3') .'\xFE/php\xFF'", $text);
      return $text;
    case "process":
      $text = preg_replace('@\xFEcode\xFF(.+?)\xFE/code\xFF@se', "codefilter_process_code('$1')", $text);
      $text = preg_replace('@\xFEphp\xFF(.+?)\xFE/php\xFF@se', "codefilter_process_php('$1')", $text);
      return $text;
    default:
      return $text;
  }
}
?>
Войдите или зарегистрируйтесь, чтобы получить возможность отправлять комментарии

Вход в систему

Что такое OpenID?
  • Регистрация
  • Забыли пароль?

Документация

  • Drupal 6
  • Константы
  • Файлы
  • Функции
  • Глобальные переменные
  • Разделы