Filter system

Last updated February 19, 2008. Created by Dries on May 30, 2005.
Edited by ax. Log in to edit this page.

• The various filter hooks ('filter', 'conf_filters') have been merged into one 'filter' hook. A module that provides filtering functionality should implement:
  
  <?php
function example_filter($op, $text = "") {
  switch ($op) {
    case "name":
      return t("Name of the filter");
    case "prepare":
      // Do preparing on $text
      return $text;
    case "process":
      // Do processing on $text
      return $text;
    case "settings":
      // Generate $output of settings
      return $output;
  }
}
?>
  • "name" is new, and should return a friendly name for the filter.

  • "prepare" is also new. This is an extra step that is performed before the default HTML processing, if HTML tags are allowed. It is meant to give filters the chance to escape HTML-like data before it can get stripped. This means, to convert meaningful HTML characters like < and > into entities such as &lt; and &gt;.

    Common examples include filtering pieces of PHP code, mathematical formulas, etc. It is not allowed to do anything other than escaping in the "prepare" step.

    If your filter currently performs such a step in the main "process" step, it should be moved into "prepare" instead. If you don't need any escaping, your filter should simply return $text without processing in this case.

  • "process" is the equivalent of the old "filter" hook. Normal filtering is performed here, and the changed $text is returned.
  • "settings" is the equivalent of the old "conf_filters" hook. If your filter provides configurable options, you should return them here (using the standard form_* functions).
• The filter handling code has been moved to a new required filter.module, and thus most of the filter function names changed, although none of those should have been called from modules. The check_output() function is still available with the same functionality.
• Node filtering is optimized with the node_prepare() function now, which only runs the body through the filters if the node view page is displayed. Otherwise, only the teaser is filtered.
• The _compose_tips hook (defined by the contrib compose_tips.module) is not supported anymore, but more advanced functionality exists in the core. You can emit extensive compose tips related to the filter you define via the _help hook with the 'filter#long-tip' section identifier. The compose_tips URL is thus changed to filter/tips. The form_allowed_tags_text() function is replaced with filter_tips_short(), which now supports short tips to be placed under textareas. Any module can inject short tips about the filter defined via the _help hook, with the 'filter#short-tip' section identifier.