modules/filter/filter.api.php

<?php
// $Id: filter.api.php,v 1.14 2009/09/18 00:12:46 webchick Exp $

/**
 * @file
 * Hooks provided by the Filter module.
 */

/**
 * @addtogroup hooks
 * @{
 */

/**
 * Define content filters.
 *
 * Content in Drupal is passed through a group of filters before it is output.
 * This lets a module modify content to the site administrator's liking.
 *
 * This hook allows modules to declare input filters they provide. A module can
 * contain as many filters as it wants.
 *
 * The overall, logical flow is as follows:
 * - hook_filter_info() is invoked to retrieve one or more filter definitions.
 * - The site administrator enables and configures the filter, where the
 *   following properties may be used:
 *   - 'title': The filter's title.
 *   - 'description': The filter's short-description.
 *   Additionally, if a filter is configurable:
 *   - 'settings callback': A form builder function name providing a settings
 *     form for the filter.
 *   - 'default settings': An array containing default settings for the filter.
 * - When a form containing a text format-enabled text widget/textarea is
 *   rendered, the following property are checked:
 *   - 'tips callback': A function name providing filter guidelines to be
 *      displayed in the text format widget.
 * - When a content using a text format is rendered, the following properties
 *   may be used:
 *   - 'prepare callback': A name of a function that escapes the to be filtered
 *     content before the actual filtering happens.
 *   - 'process callback': The name the function that performs the actual
 *     filtering.
 *
 * Filtering is a two-step process. First, the content is 'prepared' by calling
 * the 'prepare callback' function for every filter. The purpose of the 'prepare
 * callback' is to escape HTML-like structures. For example, imagine a filter
 * which allows the user to paste entire chunks of programming code without
 * requiring manual escaping of special HTML characters like @< or @&. If the
 * programming code were left untouched, then other filters could think it was
 * HTML and change it. For most filters however, the prepare-step is not
 * necessary, and they can just return the input without changes.
 *
 * Filters should not use the 'prepare callback' step for anything other than
 * escaping, because that would short-circuit the control the user has over the
 * order in which filters are applied.
 *
 * The second step is the actual processing step. The result from the prepare
 * step gets passed to all the filters again, this time with the 'process
 * callback' function. It's here where filters should perform actual changing of
 * the content: transforming URLs into hyperlinks, converting smileys into
 * images, etc.
 *
 * An important aspect of the filtering system is 'text formats'. Every text
 * format is an entire filter setup: which filters to enable, in what order
 * and with what settings.
 *
 * Filters that require settings should provide the form controls to configure
 * the settings in a form builder function, specified in 'settings callback'.
 * The filter system stores the settings in the database per text format.
 *
 * If the filter's behavior depends on an extensive list and/or external data
 * (e.g. a list of smileys, a list of glossary terms) then filters are allowed
 * to provide a separate, global configuration page rather than provide settings
 * per format. In that case, there should be a link from the format-specific
 * settings to the separate settings page.
 *
 * The $filter object with the current settings is passed to the 'settings
 * callback' function. If 'default settings' were defined in hook_filter_info(),
 * those are passed as second argument to the 'settings callback'. Each filter
 * should apply either the default settings or the configured settings contained
 * in $filter->settings.
 *
 * 'settings callback' is invoked with the following arguments (most filter
 * implementations will only need the first 3):
 * - &$form_state: The form state of the (entire) configuration form.
 * - $filter: The filter object containing settings for the given format.
 * - $defaults: The default settings for the filter, as defined in 'default
 *   settings' in hook_filter_info().
 * - $format: The format object being configured.
 * - $filters: Complete list of filter objects that are enabled for the given
 *   format.
 *
 * @code
 *   function mymodule_filter_settings($form, &$form_state, $filter, $defaults) {
 *     $form['mymodule_url_length'] = array(
 *       '#type' => 'textfield',
 *       '#title' => t('Maximum link text length'),
 *       '#default_value' => isset($filter->settings['mymodule_url_length']) ? $filter->settings['mymodule_url_length'] : $defaults['mymodule_url_length'],
 *     );
 *     return $form;
 *   }
 * @endcode
 *
 * 'prepare callback' and 'process callback' are invoked with the following
 * arguments:
 * - $text: The text to be filtered.
 * - $filter: The filter object containing settings for the given format.
 * - $format: The format object of the text to be filtered.
 * - $langcode: (optional) The language code of the text to be filtered.
 * - $cache: Boolean whether check_markup() will cache the filtered $text in
 *   {cache_filter}.
 * - $cache_id: The cache ID used for $text in {cache_filter} when $cache is
 *   TRUE.
 *
 * @see check_markup()
 *
 * 'prepare callback' and 'process callback' functions may access the filter
 * settings in $filter->settings['mymodule_url_length'].
 *
 * 'tips callback' is invoked with the following parameters:
 * - $filter: The filter object containing settings for the given format.
 * - $format: The format object of the text to be filtered.
 * - $long: Boolean whether to return long or short filter guidelines.
 *
 * For performance reasons content is only filtered once; the result is stored
 * in the cache table and retrieved from the cache the next time the same piece
 * of content is displayed. If a filter's output is dynamic, it can override the
 * cache mechanism, but obviously this should be used with caution: having one
 * filter that does not support caching in a particular text format disables
 * caching for the entire format, not just for one filter.
 *
 * Beware of the filter cache when developing your module: it is advised to set
 * your filter to 'cache' => FALSE while developing, but be sure to remove it
 * again if it's not needed. You can clear the cache by running the SQL query
 * 'DELETE * FROM cache_filter';
 *
 * @return
 *   An array of filter items. Each filter item has a unique name, prefixed
 *   with the name of the module that provides it. The item is an associative
 *   array that may contain the following key-value pairs:
 *   - 'title': (required) The administrative title of the filter.
 *   - 'description': A short, administrative description of what this filter
 *     does.
 *   - 'prepare callback': A callback function to call in the 'prepare' step
 *     of the filtering.
 *   - 'process callback': (required) The callback function to call in the
 *     'process' step of the filtering.
 *   - 'settings callback': A callback function that provides form controls
 *     for the filter's settings. Each filter should apply either the default
 *     settings or the configured settings contained in $filter->settings. The
 *     user submitted values are stored in the database.
 *   - 'default settings': An array containing default settings for a filter to
 *     be applied when the filter has not been configured yet.
 *   - 'tips callback': A callback function that provides tips for using the
 *     filter. A module's tips should be informative and to the point. Short
 *     tips are preferably one-liners.
 *   - 'cache': Specifies whether the filtered text can be cached. TRUE by
 *     default. Note that defining FALSE makes the entire text format not
 *     cacheable, which may have an impact on the site's overall performance.
 *
 * For a detailed usage example, see filter_example.module. For an example of
 * using multiple filters in one module, see filter_filter_info().
 */
function hook_filter_info() {
  $filters['filter_html'] = array(
    'title' => t('Limit allowed HTML tags'),
    'description' => t('Allows you to restrict the HTML tags the user can use. It will also remove harmful content such as JavaScript events, JavaScript URLs and CSS styles from those tags that are not removed.'),
    'process callback' => '_filter_html',
    'settings callback' => '_filter_html_settings',
    'default settings' => array(
      'allowed_html' => '<a> <em> <strong> <cite> <blockquote> <code> <ul> <ol> <li> <dl> <dt> <dd>',
      'filter_html_help' => 1,
      'filter_html_nofollow' => 0,
    ),
    'tips callback' => '_filter_html_tips',
  );
  $filters['filter_autop'] = array(
    'title' => t('Convert line breaks'),
    'description' => t('Converts line breaks into HTML (i.e. &lt;br&gt; and &lt;p&gt;) tags.'),
    'process callback' => '_filter_autop',
    'tips callback' => '_filter_autop_tips',
  );
  return $filters;
}

/**
 * Perform alterations on filter definitions.
 *
 * @param $info
 *   Array of information on filters exposed by hook_filter_info()
 *   implementations.
 */
function hook_filter_info_alter(&$info) {
  // Replace the PHP evaluator process callback with an improved
  // PHP evaluator provided by a module.
  $info['php_code']['process callback'] = 'my_module_php_evaluator';

  // Alter the default settings of the URL filter provided by core.
  $info['filter_url']['default settings'] = array(
    'filter_url_length' => 100,
  );
}

/**
 * Perform actions when a new text format has been created.
 *
 * @param $format
 *   The format object of the format being updated.
 *
 * @see hook_filter_format_update().
 * @see hook_filter_format_delete().
 */
function hook_filter_format_insert($format) {
  mymodule_cache_rebuild();
}

/**
 * Perform actions when a text format has been updated.
 *
 * This hook allows modules to act when a text format has been updated in any
 * way. For example, when filters have been reconfigured, disabled, or
 * re-arranged in the text format.
 *
 * @param $format
 *   The format object of the format being updated.
 *
 * @see hook_filter_format_insert().
 * @see hook_filter_format_delete().
 */
function hook_filter_format_update($format) {
  mymodule_cache_rebuild();
}

/**
 * Perform actions when a text format has been deleted.
 *
 * It is recommended for modules to implement this hook, when they store
 * references to text formats to replace existing references to the deleted
 * text format with the fallback format.
 *
 * @param $format
 *   The format object of the format being deleted.
 * @param $fallback
 *   The format object of the site's fallback format, which is always available
 *   to all users.
 *
 * @see hook_filter_format_update().
 * @see hook_filter_format_delete().
 */
function hook_filter_format_delete($format, $fallback) {
  // Replace the deleted format with the fallback format.
  db_update('my_module_table')
    ->fields(array('format' => $fallback->format))
    ->condition('format', $format->format)
    ->execute();
}

/**
 * @} End of "addtogroup hooks".
 */
1	<?php
2	// $Id: filter.api.php,v 1.14 2009/09/18 00:12:46 webchick Exp $
3
4	/**
5	* @file
6	* Hooks provided by the Filter module.
7	*/
8
9	/**
10	* @addtogroup hooks
11	* @{
12	*/
13
14	/**
15	* Define content filters.
16	*
17	* Content in Drupal is passed through a group of filters before it is output.
18	* This lets a module modify content to the site administrator's liking.
19	*
20	* This hook allows modules to declare input filters they provide. A module can
21	* contain as many filters as it wants.
22	*
23	* The overall, logical flow is as follows:
24	* - hook_filter_info() is invoked to retrieve one or more filter definitions.
25	* - The site administrator enables and configures the filter, where the
26	* following properties may be used:
27	* - 'title': The filter's title.
28	* - 'description': The filter's short-description.
29	* Additionally, if a filter is configurable:
30	* - 'settings callback': A form builder function name providing a settings
31	* form for the filter.
32	* - 'default settings': An array containing default settings for the filter.
33	* - When a form containing a text format-enabled text widget/textarea is
34	* rendered, the following property are checked:
35	* - 'tips callback': A function name providing filter guidelines to be
36	* displayed in the text format widget.
37	* - When a content using a text format is rendered, the following properties
38	* may be used:
39	* - 'prepare callback': A name of a function that escapes the to be filtered
40	* content before the actual filtering happens.
41	* - 'process callback': The name the function that performs the actual
42	* filtering.
43	*
44	* Filtering is a two-step process. First, the content is 'prepared' by calling
45	* the 'prepare callback' function for every filter. The purpose of the 'prepare
46	* callback' is to escape HTML-like structures. For example, imagine a filter
47	* which allows the user to paste entire chunks of programming code without
48	* requiring manual escaping of special HTML characters like @< or @&. If the
49	* programming code were left untouched, then other filters could think it was
50	* HTML and change it. For most filters however, the prepare-step is not
51	* necessary, and they can just return the input without changes.
52	*
53	* Filters should not use the 'prepare callback' step for anything other than
54	* escaping, because that would short-circuit the control the user has over the
55	* order in which filters are applied.
56	*
57	* The second step is the actual processing step. The result from the prepare
58	* step gets passed to all the filters again, this time with the 'process
59	* callback' function. It's here where filters should perform actual changing of
60	* the content: transforming URLs into hyperlinks, converting smileys into
61	* images, etc.
62	*
63	* An important aspect of the filtering system is 'text formats'. Every text
64	* format is an entire filter setup: which filters to enable, in what order
65	* and with what settings.
66	*
67	* Filters that require settings should provide the form controls to configure
68	* the settings in a form builder function, specified in 'settings callback'.
69	* The filter system stores the settings in the database per text format.
70	*
71	* If the filter's behavior depends on an extensive list and/or external data
72	* (e.g. a list of smileys, a list of glossary terms) then filters are allowed
73	* to provide a separate, global configuration page rather than provide settings
74	* per format. In that case, there should be a link from the format-specific
75	* settings to the separate settings page.
76	*
77	* The $filter object with the current settings is passed to the 'settings
78	* callback' function. If 'default settings' were defined in hook_filter_info(),
79	* those are passed as second argument to the 'settings callback'. Each filter
80	* should apply either the default settings or the configured settings contained
81	* in $filter->settings.
82	*
83	* 'settings callback' is invoked with the following arguments (most filter
84	* implementations will only need the first 3):
85	* - &$form_state: The form state of the (entire) configuration form.
86	* - $filter: The filter object containing settings for the given format.
87	* - $defaults: The default settings for the filter, as defined in 'default
88	* settings' in hook_filter_info().
89	* - $format: The format object being configured.
90	* - $filters: Complete list of filter objects that are enabled for the given
91	* format.
92	*
93	* @code
94	* function mymodule_filter_settings($form, &$form_state, $filter, $defaults) {
95	* $form['mymodule_url_length'] = array(
96	* '#type' => 'textfield',
97	* '#title' => t('Maximum link text length'),
98	* '#default_value' => isset($filter->settings['mymodule_url_length']) ? $filter->settings['mymodule_url_length'] : $defaults['mymodule_url_length'],
99	* );
100	* return $form;
101	* }
102	* @endcode
103	*
104	* 'prepare callback' and 'process callback' are invoked with the following
105	* arguments:
106	* - $text: The text to be filtered.
107	* - $filter: The filter object containing settings for the given format.
108	* - $format: The format object of the text to be filtered.
109	* - $langcode: (optional) The language code of the text to be filtered.
110	* - $cache: Boolean whether check_markup() will cache the filtered $text in
111	* {cache_filter}.
112	* - $cache_id: The cache ID used for $text in {cache_filter} when $cache is
113	* TRUE.
114	*
115	* @see check_markup()
116	*
117	* 'prepare callback' and 'process callback' functions may access the filter
118	* settings in $filter->settings['mymodule_url_length'].
119	*
120	* 'tips callback' is invoked with the following parameters:
121	* - $filter: The filter object containing settings for the given format.
122	* - $format: The format object of the text to be filtered.
123	* - $long: Boolean whether to return long or short filter guidelines.
124	*
125	* For performance reasons content is only filtered once; the result is stored
126	* in the cache table and retrieved from the cache the next time the same piece
127	* of content is displayed. If a filter's output is dynamic, it can override the
128	* cache mechanism, but obviously this should be used with caution: having one
129	* filter that does not support caching in a particular text format disables
130	* caching for the entire format, not just for one filter.
131	*
132	* Beware of the filter cache when developing your module: it is advised to set
133	* your filter to 'cache' => FALSE while developing, but be sure to remove it
134	* again if it's not needed. You can clear the cache by running the SQL query
135	* 'DELETE * FROM cache_filter';
136	*
137	* @return
138	* An array of filter items. Each filter item has a unique name, prefixed
139	* with the name of the module that provides it. The item is an associative
140	* array that may contain the following key-value pairs:
141	* - 'title': (required) The administrative title of the filter.
142	* - 'description': A short, administrative description of what this filter
143	* does.
144	* - 'prepare callback': A callback function to call in the 'prepare' step
145	* of the filtering.
146	* - 'process callback': (required) The callback function to call in the
147	* 'process' step of the filtering.
148	* - 'settings callback': A callback function that provides form controls
149	* for the filter's settings. Each filter should apply either the default
150	* settings or the configured settings contained in $filter->settings. The
151	* user submitted values are stored in the database.
152	* - 'default settings': An array containing default settings for a filter to
153	* be applied when the filter has not been configured yet.
154	* - 'tips callback': A callback function that provides tips for using the
155	* filter. A module's tips should be informative and to the point. Short
156	* tips are preferably one-liners.
157	* - 'cache': Specifies whether the filtered text can be cached. TRUE by
158	* default. Note that defining FALSE makes the entire text format not
159	* cacheable, which may have an impact on the site's overall performance.
160	*
161	* For a detailed usage example, see filter_example.module. For an example of
162	* using multiple filters in one module, see filter_filter_info().
163	*/
164	function hook_filter_info() {
165	$filters['filter_html'] = array(
166	'title' => t('Limit allowed HTML tags'),
167	'description' => t('Allows you to restrict the HTML tags the user can use. It will also remove harmful content such as JavaScript events, JavaScript URLs and CSS styles from those tags that are not removed.'),
168	'process callback' => '_filter_html',
169	'settings callback' => '_filter_html_settings',
170	'default settings' => array(
171	'allowed_html' => '<a> <em> <strong> <cite> <blockquote> <code> <ul> <ol> <li> <dl> <dt> <dd>',
172	'filter_html_help' => 1,
173	'filter_html_nofollow' => 0,
174	),
175	'tips callback' => '_filter_html_tips',
176	);
177	$filters['filter_autop'] = array(
178	'title' => t('Convert line breaks'),
179	'description' => t('Converts line breaks into HTML (i.e. <br> and <p>) tags.'),
180	'process callback' => '_filter_autop',
181	'tips callback' => '_filter_autop_tips',
182	);
183	return $filters;
184	}
185
186	/**
187	* Perform alterations on filter definitions.
188	*
189	* @param $info
190	* Array of information on filters exposed by hook_filter_info()
191	* implementations.
192	*/
193	function hook_filter_info_alter(&$info) {
194	// Replace the PHP evaluator process callback with an improved
195	// PHP evaluator provided by a module.
196	$info['php_code']['process callback'] = 'my_module_php_evaluator';
197
198	// Alter the default settings of the URL filter provided by core.
199	$info['filter_url']['default settings'] = array(
200	'filter_url_length' => 100,
201	);
202	}
203
204	/**
205	* Perform actions when a new text format has been created.
206	*
207	* @param $format
208	* The format object of the format being updated.
209	*
210	* @see hook_filter_format_update().
211	* @see hook_filter_format_delete().
212	*/
213	function hook_filter_format_insert($format) {
214	mymodule_cache_rebuild();
215	}
216
217	/**
218	* Perform actions when a text format has been updated.
219	*
220	* This hook allows modules to act when a text format has been updated in any
221	* way. For example, when filters have been reconfigured, disabled, or
222	* re-arranged in the text format.
223	*
224	* @param $format
225	* The format object of the format being updated.
226	*
227	* @see hook_filter_format_insert().
228	* @see hook_filter_format_delete().
229	*/
230	function hook_filter_format_update($format) {
231	mymodule_cache_rebuild();
232	}
233
234	/**
235	* Perform actions when a text format has been deleted.
236	*
237	* It is recommended for modules to implement this hook, when they store
238	* references to text formats to replace existing references to the deleted
239	* text format with the fallback format.
240	*
241	* @param $format
242	* The format object of the format being deleted.
243	* @param $fallback
244	* The format object of the site's fallback format, which is always available
245	* to all users.
246	*
247	* @see hook_filter_format_update().
248	* @see hook_filter_format_delete().
249	*/
250	function hook_filter_format_delete($format, $fallback) {
251	// Replace the deleted format with the fallback format.
252	db_update('my_module_table')
253	->fields(array('format' => $fallback->format))
254	->condition('format', $format->format)
255	->execute();
256	}
257
258	/**
259	* @} End of "addtogroup hooks".
260	*/