developer/examples/filter_example.module

<?php
// $Id: filter_example.module,v 1.9 2008/10/12 08:52:36 davereid Exp $

/**
 * @file
 * This is an example outlining how a module can be used to define a filter
 * to be run on user-submitted content before it is output to 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 will find a custom XML tag, <time />, and
 * replace it by the current time.
 */

/**
 * Implementation of hook_filter_tips().
 *
 * This hook allows filters to provide help text to users during the content
 * editing process. Short tips are provided on the content editing screen, while
 * long tips are provided on a separate linked page. Short tips are optional,
 * but long tips are highly recommended.
 */
function filter_example_filter_tips($delta, $format, $long = FALSE) {
  switch ($delta) {
    case 0:
      if ($long) {
        return t('Every instance of "foo" in the input text will be replaced with "%replacement".', array('%replacement' => variable_get('filter_example_foo_' . $format, 'bar')));
      }
      break;

    case 1:
      if ($long) {
        return 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.');
      }
      else {
        return t('Use &lt;time /&gt; to display the current date/time.');
      }
      break;
  }
}

/**
 * Implementation of hook_filter().
 *
 * The bulk of filtering work is done here. This hook is quite complicated, so
 * we'll discuss each operation it defines.
 */
function filter_example_filter($op, $delta = 0, $format = -1, $text = '') {
  // The "list" operation provides the module an opportunity to declare both how
  // many filters it defines and a human-readable name for each filter. Note that
  // the returned name should be passed through t() for translation.
  if ($op == 'list') {
    return array(
      0 => t('Substitute "foo"'),
      1 => t('Current time'));
  }

  // All operations besides "list" provide a $delta argument so we know which
  // filter they refer to. We'll switch on that argument now so that we can
  // discuss each filter in turn.
  switch ($delta) {

    // First we define the simple string substitution filter.
    case 0:

      switch ($op) {
        // This description is shown in the administrative interface, unlike the
        // filter tips which are shown in the content editing interface.
        case 'description':
          return t('Substitutes a custom string for the string "foo" in the text.');

        // We don't need the "prepare" operation for this filter, but it's required
        // to at least return the input text as-is.
        case 'prepare':
          return $text;

        // The actual filtering is performed here. The supplied text should be
        // returned, once any necessary substitutions have taken place.
        case 'process':
          return str_replace('foo', variable_get("filter_example_foo_$format", 'bar'), $text);

        // Since we allow the administrator to define the string that gets
        // substituted when "foo" is encountered, we need to provide an
        // interface for this customization. Note that the value of $format
        // needs to be provided as part of the form name, so that different
        // customization can be done for this filter in each of the different
        // input formats that may use it.
        case 'settings':
          $form['filter_example'] = array(
            '#type' => 'fieldset',
            '#title' => t('Foo filter'),
            '#collapsible' => TRUE,
            '#collapsed' => TRUE,
          );
          $form['filter_example']["filter_example_foo_$format"] = array(
            '#type' => 'textfield',
            '#title' => t('Substitution string'),
            '#default_value' => variable_get("filter_example_foo_$format", 'bar'),
            '#description' => t('The string to substitute for "foo" everywhere in the text.')
          );
          return $form;
      }
      break;

    // Next is our "time tag" filter.
    case 1:

      switch ($op) {
        // This description is shown in the administrative interface, unlike the
        // filter tips which are shown in the content editing interface.
        case 'description':
          return t('Inserts the current time in the place of a &lt;time /&gt; tags.');

        // Since this filter will return a different result on each page load, we
        // need to return TRUE for "no cache" to ensure that the filter is run
        // every time the text is requested.
        case 'no cache':
          return TRUE;

        // 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 HTML is escaped/stripped by other filters. But
        // we want to use HTML in our result as well, and so 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.
        //
        // We'll use the bytes 0xFE and 0xFF to replace < and > here. These bytes
        // are not valid in UTF-8 data and thus unlikely to cause problems.
        case 'prepare':
          return preg_replace('!<time ?/>!', '\xFEtime /\xFF', $text);

        // Now, in the "process" step, we'll search for our escaped time tags and
        // to the real filtering.
        case 'process':
          return str_replace('\xFEtime /\xFF', '<em>' . format_date(REQUEST_TIME) . '</em>', $text);
      }
      break;
  }
}
1	<?php
2	// $Id: filter_example.module,v 1.9 2008/10/12 08:52:36 davereid Exp $
3
4	/**
5	* @file
6	* This is an example outlining how a module can be used to define a filter
7	* to be run on user-submitted content before it is output to the browser.
8	*
9	* To show all the capabilities of the filter system, we will define two filters
10	* in this module. One will substitute the string "foo" with an administratively-
11	* defined replacement string. The other will find a custom XML tag, <time />, and
12	* replace it by the current time.
13	*/
14
15	/**
16	* Implementation of hook_filter_tips().
17	*
18	* This hook allows filters to provide help text to users during the content
19	* editing process. Short tips are provided on the content editing screen, while
20	* long tips are provided on a separate linked page. Short tips are optional,
21	* but long tips are highly recommended.
22	*/
23	function filter_example_filter_tips($delta, $format, $long = FALSE) {
24	switch ($delta) {
25	case 0:
26	if ($long) {
27	return t('Every instance of "foo" in the input text will be replaced with "%replacement".', array('%replacement' => variable_get('filter_example_foo_' . $format, 'bar')));
28	}
29	break;
30
31	case 1:
32	if ($long) {
33	return t('Every instance of the special <time /> tag will be replaced with the current date and time in the user\'s specified time zone.');
34	}
35	else {
36	return t('Use <time /> to display the current date/time.');
37	}
38	break;
39	}
40	}
41
42	/**
43	* Implementation of hook_filter().
44	*
45	* The bulk of filtering work is done here. This hook is quite complicated, so
46	* we'll discuss each operation it defines.
47	*/
48	function filter_example_filter($op, $delta = 0, $format = -1, $text = '') {
49	// The "list" operation provides the module an opportunity to declare both how
50	// many filters it defines and a human-readable name for each filter. Note that
51	// the returned name should be passed through t() for translation.
52	if ($op == 'list') {
53	return array(
54	0 => t('Substitute "foo"'),
55	1 => t('Current time'));
56	}
57
58	// All operations besides "list" provide a $delta argument so we know which
59	// filter they refer to. We'll switch on that argument now so that we can
60	// discuss each filter in turn.
61	switch ($delta) {
62
63	// First we define the simple string substitution filter.
64	case 0:
65
66	switch ($op) {
67	// This description is shown in the administrative interface, unlike the
68	// filter tips which are shown in the content editing interface.
69	case 'description':
70	return t('Substitutes a custom string for the string "foo" in the text.');
71
72	// We don't need the "prepare" operation for this filter, but it's required
73	// to at least return the input text as-is.
74	case 'prepare':
75	return $text;
76
77	// The actual filtering is performed here. The supplied text should be
78	// returned, once any necessary substitutions have taken place.
79	case 'process':
80	return str_replace('foo', variable_get("filter_example_foo_$format", 'bar'), $text);
81
82	// Since we allow the administrator to define the string that gets
83	// substituted when "foo" is encountered, we need to provide an
84	// interface for this customization. Note that the value of $format
85	// needs to be provided as part of the form name, so that different
86	// customization can be done for this filter in each of the different
87	// input formats that may use it.
88	case 'settings':
89	$form['filter_example'] = array(
90	'#type' => 'fieldset',
91	'#title' => t('Foo filter'),
92	'#collapsible' => TRUE,
93	'#collapsed' => TRUE,
94	);
95	$form['filter_example']["filter_example_foo_$format"] = array(
96	'#type' => 'textfield',
97	'#title' => t('Substitution string'),
98	'#default_value' => variable_get("filter_example_foo_$format", 'bar'),
99	'#description' => t('The string to substitute for "foo" everywhere in the text.')
100	);
101	return $form;
102	}
103	break;
104
105	// Next is our "time tag" filter.
106	case 1:
107
108	switch ($op) {
109	// This description is shown in the administrative interface, unlike the
110	// filter tips which are shown in the content editing interface.
111	case 'description':
112	return t('Inserts the current time in the place of a <time /> tags.');
113
114	// Since this filter will return a different result on each page load, we
115	// need to return TRUE for "no cache" to ensure that the filter is run
116	// every time the text is requested.
117	case 'no cache':
118	return TRUE;
119
120	// This filter is a little trickier to implement than the previous one.
121	// Since the input involves special HTML characters (< and >) we have to
122	// run the filter before HTML is escaped/stripped by other filters. But
123	// we want to use HTML in our result as well, and so if we run this filter
124	// first our replacement string could be escaped or stripped. The solution
125	// is to use the "prepare" operation to escape the special characters, and
126	// to later replace our escaped version in the "process" step.
127	//
128	// We'll use the bytes 0xFE and 0xFF to replace < and > here. These bytes
129	// are not valid in UTF-8 data and thus unlikely to cause problems.
130	case 'prepare':
131	return preg_replace('!<time ?/>!', '\xFEtime /\xFF', $text);
132
133	// Now, in the "process" step, we'll search for our escaped time tags and
134	// to the real filtering.
135	case 'process':
136	return str_replace('\xFEtime /\xFF', '<em>' . format_date(REQUEST_TIME) . '</em>', $text);
137	}
138	break;
139	}
140	}