filter_example.module

<?php
/**
 * @file
 * Hook implementations for the Filter Example module.
 */

/**
 * @defgroup filter_example Example: Filter
 * @ingroup examples
 * @{
 * This example demonstrates how filters are created.
 *
 * This is an example outlining how a module can define a filter that runs on
 * user-submitted content before it is output on the browser.
 *
 * To show all the capabilities of the filter system, we will define two filters
 * in this module. One will substitute the string "foo" with an
 * administratively-defined replacement string; the other one will replace a XML
 * tag, <time />, with the current time.
 *
 * Foo filter
 *
 * Backdrop has several content formats (they are not filters). In our example
 * the foo replacement can be configured for each one of them, allowing a HTML
 * or PHP replacement. The module includes a settings callback, with options
 * to configure that replacements. A tips callback will show the current
 * replacement for the node that is edited.
 *
 * Time filter.
 *
 * This filter is a little trickier to implement than the previous one. Since
 * the input involves special HTML characters (< and >), we have to run the
 * filter before the HTML markup is escaped/stripped by other filters. We want
 * to use HTML in our result as well; if we run this filter first, our
 * replacement string could be escaped or stripped. The solution is to use the
 * "prepare" operation to escape the special characters, and to later replace
 * our escaped version in the "process" step.
 */

/**
 * Implements hook_menu().
 */
function filter_example_menu() {
  $items['examples/filter_example'] = array(
    'title' => 'Filter Example',
    'page callback' => '_filter_example_information',
    'access callback' => TRUE,
  );
  return $items;
}

/**
 * Simply returns a little bit of information about the example.
 */
function _filter_example_information() {
  return t("<p>This example provides two filters.</p><p>Foo Filter replaces
    'foo' with a configurable replacement.</p><p>Time Tag replaces the string
    '&lt;time /&gt;' with the current time.</p><p>To use these filters, go to !link and
    configure an input format, or create a new one.</p>",
    array('!link' => l(t('admin/config/content/formats'), 'admin/config/content/formats'))
  );
}

/**
 * Implements hook_filter_info().
 *
 * We define the different filters provided by the module. For this example,
 * time_filter is a very static and simple replacement, but it requires
 * preparing the string because of the < and > characters. foo_filter is more
 * complex.
 */
function filter_example_filter_info() {
  $filters['filter_foo'] = array(
    'title' => t('Foo Filter (example)'),
    'description' => t('Every instance of "foo" in the input text will be replaced with a preconfigured replacement.'),
    'process callback'  => '_filter_example_filter_foo_process',
    'default settings' => array(
      'filter_example_foo' => 'bar',
    ),
    'settings callback' => '_filter_example_filter_foo_settings',
    'tips callback' => '_filter_example_filter_foo_tips',
  );
  $filters['filter_time'] = array(
    'title' => t('Time Tag (example)'),
    'description' => t("Every instance of the special &lt;time /&gt; tag will be replaced with the current date and time in the user's specified time zone."),
    'prepare callback' => '_filter_example_filter_time_prepare',
    'process callback' => '_filter_example_filter_time_process',
    'tips callback' => '_filter_example_filter_time_tips',
  );
  return $filters;
}

/*
 * Foo filter
 *
 * Backdrop has several text formats (they are not filters), and in our example
 * the foo replacement can be configured for each of them, so the module
 * includes a settings callback, with options to configure those replacements.
 * A tips callback will help showing the current replacement for the content
 * type being edited.
 */

/**
 * Settings callback for foo filter.
 *
 * Make use of $format to have different replacements for every input format.
 * Since we allow the administrator to define the string that gets substituted
 * when "foo" is encountered, we need to provide an interface for this kind of
 * customization. The object format is also an argument of the callback.
 *
 * The settings defined in this form are stored in database by the Filter module
 * and they will be available in the $filter parameter.
 */
function _filter_example_filter_foo_settings($form, $form_state, $filter, $format) {
  $settings['filter_example_foo'] = array(
    '#type' => 'textfield',
    '#title' => t('Substitution string'),
    '#default_value' => $filter->settings['filter_example_foo'],
    '#description' => t('The string to substitute for "foo" everywhere in the text.'),
  );
  return $settings;
}

/**
 * Foo filter process callback.
 *
 * The actual filtering is performed here. The supplied text should be returned,
 * once any necessary substitutions have taken place. The example just replaces
 * foo with our custom defined string in the settings page.
 */
function _filter_example_filter_foo_process($text, $filter, $format) {
  $replacement = isset($filter->settings['filter_example_foo']) ? $filter->settings['filter_example_foo'] : 'bar';
  return str_replace('foo', $replacement, $text);
}


/**
 * Filter tips callback for foo filter.
 *
 * The tips callback allows filters to provide help text to users during the
 * content editing process. Short tips (optional) are provided on the content
 * editing screen, while long tips (highly recommended) are provided on a
 * separate linked page.
 */
function _filter_example_filter_foo_tips($filter, $format, $long = FALSE) {
  $replacement = isset($filter->settings['filter_example_foo']) ? $filter->settings['filter_example_foo'] : 'bar';
  if (!$long) {
    // This string will be shown in the content add/edit form.
    return t('<em>foo</em> replaced with %replacement.', array('%replacement' => $replacement));
  }
  else {
    return t('Every instance of "foo" in the input text will be replaced with a configurable value. You can configure this value and put whatever you want there. The replacement value is "%replacement".', array('%replacement' => $replacement));
  }
}

/**
 * Time filter prepare callback.
 *
 * We'll use [filter-example-time] as a replacement for the time tag. Note that,
 * in a more complicated filter, a closing tag may also be required.
 */
function _filter_example_filter_time_prepare($text, $filter) {
  return preg_replace('!<time ?/>!', '[filter-example-time]', $text);
}

/**
 * Time filter process callback.
 *
 * In the process step, we'll search for our escaped time tags and do the real
 * filtering by replacing <time /> with the current time.
 */
function _filter_example_filter_time_process($text, $filter) {
  return str_replace('[filter-example-time]', '<em>' . format_date(time(), 'medium', '', 'Europe/London') . '</em>', $text);
}

/**
 * Filter tips callback for time filter.
 *
 * The tips callback allows filters to provide help text to users during the
 * content editing process. Short tips (optional) are provided on the content
 * editing screen, while long tips (highly recommended) are provided on a
 * separate linked page.
 */
function _filter_example_filter_time_tips($filter, $format, $long = FALSE) {
  return t('<em>&lt;time /&gt;</em> is replaced with the current time.');
}

/**
 * @} End of "defgroup filter_example".
 */