Project

General

Profile

Paste
Download (11.5 KB) Statistics
| Branch: | Revision:

root / drupal7 / modules / filter / filter.api.php @ 27e02aed

1
<?php
2

    
3
/**
4
 * @file
5
 * Hooks provided by the Filter module.
6
 */
7

    
8
/**
9
 * @addtogroup hooks
10
 * @{
11
 */
12

    
13
/**
14
 * Define content filters.
15
 *
16
 * User submitted content is passed through a group of filters before it is
17
 * output in HTML, in order to remove insecure or unwanted parts, correct or
18
 * enhance the formatting, transform special keywords, etc. A group of filters
19
 * is referred to as a "text format". Administrators can create as many text
20
 * formats as needed. Individual filters can be enabled and configured
21
 * differently for each text format.
22
 *
23
 * This hook is invoked by filter_get_filters() and allows modules to register
24
 * input filters they provide.
25
 *
26
 * Filtering is a two-step process. First, the content is 'prepared' by calling
27
 * the 'prepare callback' function for every filter. The purpose of the 'prepare
28
 * callback' is to escape HTML-like structures. For example, imagine a filter
29
 * which allows the user to paste entire chunks of programming code without
30
 * requiring manual escaping of special HTML characters like < or &. If the
31
 * programming code were left untouched, then other filters could think it was
32
 * HTML and change it. For many filters, the prepare step is not necessary.
33
 *
34
 * The second step is the actual processing step. The result from passing the
35
 * text through all the filters' prepare steps gets passed to all the filters
36
 * again, this time with the 'process callback' function. The process callbacks
37
 * should then actually change the content: transform URLs into hyperlinks,
38
 * convert smileys into images, etc.
39
 *
40
 * For performance reasons content is only filtered once; the result is stored
41
 * in the cache table and retrieved from the cache the next time the same piece
42
 * of content is displayed. If a filter's output is dynamic, it can override the
43
 * cache mechanism, but obviously this should be used with caution: having one
44
 * filter that does not support caching in a particular text format disables
45
 * caching for the entire format, not just for one filter.
46
 *
47
 * Beware of the filter cache when developing your module: it is advised to set
48
 * your filter to 'cache' => FALSE while developing, but be sure to remove that
49
 * setting if it's not needed, when you are no longer in development mode.
50
 *
51
 * @return
52
 *   An associative array of filters, whose keys are internal filter names,
53
 *   which should be unique and therefore prefixed with the name of the module.
54
 *   Each value is an associative array describing the filter, with the
55
 *   following elements (all are optional except as noted):
56
 *   - title: (required) An administrative summary of what the filter does.
57
 *   - description: Additional administrative information about the filter's
58
 *     behavior, if needed for clarification.
59
 *   - settings callback: The name of a function that returns configuration form
60
 *     elements for the filter. See callback_filter_settings() for details.
61
 *   - default settings: An associative array containing default settings for
62
 *     the filter, to be applied when the filter has not been configured yet.
63
 *   - prepare callback: The name of a function that escapes the content before
64
 *     the actual filtering happens. See callback_filter_prepare() for
65
 *     details.
66
 *   - process callback: (required) The name the function that performs the
67
 *     actual filtering. See callback_filter_process() for details.
68
 *   - cache (default TRUE): Specifies whether the filtered text can be cached.
69
 *     Note that setting this to FALSE makes the entire text format not
70
 *     cacheable, which may have an impact on the site's overall performance.
71
 *     See filter_format_allowcache() for details.
72
 *   - tips callback: The name of a function that returns end-user-facing filter
73
 *     usage guidelines for the filter. See callback_filter_tips() for
74
 *     details.
75
 *   - weight: A default weight for the filter in new text formats.
76
 *
77
 * @see filter_example.module
78
 * @see hook_filter_info_alter()
79
 */
80
function hook_filter_info() {
81
  $filters['filter_html'] = array(
82
    'title' => t('Limit allowed HTML tags'),
83
    '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.'),
84
    'process callback' => '_filter_html',
85
    'settings callback' => '_filter_html_settings',
86
    'default settings' => array(
87
      'allowed_html' => '<a> <em> <strong> <cite> <blockquote> <code> <ul> <ol> <li> <dl> <dt> <dd>',
88
      'filter_html_help' => 1,
89
      'filter_html_nofollow' => 0,
90
    ),
91
    'tips callback' => '_filter_html_tips',
92
  );
93
  $filters['filter_autop'] = array(
94
    'title' => t('Convert line breaks'),
95
    'description' => t('Converts line breaks into HTML (i.e. &lt;br&gt; and &lt;p&gt;) tags.'),
96
    'process callback' => '_filter_autop',
97
    'tips callback' => '_filter_autop_tips',
98
  );
99
  return $filters;
100
}
101

    
102
/**
103
 * Perform alterations on filter definitions.
104
 *
105
 * @param $info
106
 *   Array of information on filters exposed by hook_filter_info()
107
 *   implementations.
108
 */
109
function hook_filter_info_alter(&$info) {
110
  // Replace the PHP evaluator process callback with an improved
111
  // PHP evaluator provided by a module.
112
  $info['php_code']['process callback'] = 'my_module_php_evaluator';
113

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

    
120
/**
121
 * @} End of "addtogroup hooks".
122
 */
123

    
124
/**
125
 * Provide a settings form for filter settings.
126
 *
127
 * Callback for hook_filter_info().
128
 *
129
 * This callback function is used to provide a settings form for filter
130
 * settings, for filters that need settings on a per-text-format basis. This
131
 * function should return the form elements for the settings; the filter
132
 * module will take care of saving the settings in the database.
133
 *
134
 * If the filter's behavior depends on an extensive list and/or external data
135
 * (e.g. a list of smileys, a list of glossary terms), then the filter module
136
 * can choose to provide a separate, global configuration page rather than
137
 * per-text-format settings. In that case, the settings callback function
138
 * should provide a link to the separate settings page.
139
 *
140
 * @param $form
141
 *   The prepopulated form array of the filter administration form.
142
 * @param $form_state
143
 *   The state of the (entire) configuration form.
144
 * @param $filter
145
 *   The filter object containing the current settings for the given format,
146
 *   in $filter->settings.
147
 * @param $format
148
 *   The format object being configured.
149
 * @param $defaults
150
 *   The default settings for the filter, as defined in 'default settings' in
151
 *   hook_filter_info(). These should be combined with $filter->settings to
152
 *   define the form element defaults.
153
 * @param $filters
154
 *   The complete list of filter objects that are enabled for the given format.
155
 *
156
 * @return
157
 *   An array of form elements defining settings for the filter. Array keys
158
 *   should match the array keys in $filter->settings and $defaults.
159
 *
160
 * @ingroup callbacks
161
 */
162
function callback_filter_settings($form, &$form_state, $filter, $format, $defaults, $filters) {
163
  $filter->settings += $defaults;
164

    
165
  $elements = array();
166
  $elements['nofollow'] = array(
167
    '#type' => 'checkbox',
168
    '#title' => t('Add rel="nofollow" to all links'),
169
    '#default_value' => $filter->settings['nofollow'],
170
  );
171
  return $elements;
172
}
173

    
174
/**
175
 * Provide prepared text with special characters escaped.
176
 *
177
 * Callback for hook_filter_info().
178
 *
179
 * See hook_filter_info() for a description of the filtering process. Filters
180
 * should not use the 'prepare callback' step for anything other than escaping,
181
 * because that would short-circuit the control the user has over the order in
182
 * which filters are applied.
183
 *
184
 * @param $text
185
 *   The text string to be filtered.
186
 * @param $filter
187
 *   The filter object containing settings for the given format.
188
 * @param $format
189
 *   The text format object assigned to the text to be filtered.
190
 * @param $langcode
191
 *   The language code of the text to be filtered.
192
 * @param $cache
193
 *   A Boolean indicating whether the filtered text is going to be cached in
194
 *   {cache_filter}.
195
 * @param $cache_id
196
 *   The ID of the filtered text in {cache_filter}, if $cache is TRUE.
197
 *
198
 * @return
199
 *   The prepared, escaped text.
200
 *
201
 * @ingroup callbacks
202
 */
203
function callback_filter_prepare($text, $filter, $format, $langcode, $cache, $cache_id) {
204
  // Escape <code> and </code> tags.
205
  $text = preg_replace('|<code>(.+?)</code>|se', "[codefilter_code]$1[/codefilter_code]", $text);
206
  return $text;
207
}
208

    
209
/**
210
 * Provide text filtered to conform to the supplied format.
211
 *
212
 * Callback for hook_filter_info().
213
 *
214
 * See hook_filter_info() for a description of the filtering process. This step
215
 * is where the filter actually transforms the text.
216
 *
217
 * @param $text
218
 *   The text string to be filtered.
219
 * @param $filter
220
 *   The filter object containing settings for the given format.
221
 * @param $format
222
 *   The text format object assigned to the text to be filtered.
223
 * @param $langcode
224
 *   The language code of the text to be filtered.
225
 * @param $cache
226
 *   A Boolean indicating whether the filtered text is going to be cached in
227
 *   {cache_filter}.
228
 * @param $cache_id
229
 *   The ID of the filtered text in {cache_filter}, if $cache is TRUE.
230
 *
231
 * @return
232
 *   The filtered text.
233
 *
234
 * @ingroup callbacks
235
 */
236
function callback_filter_process($text, $filter, $format, $langcode, $cache, $cache_id) {
237
  $text = preg_replace('|\[codefilter_code\](.+?)\[/codefilter_code\]|se', "<pre>$1</pre>", $text);
238

    
239
  return $text;
240
}
241

    
242
/**
243
 * Return help text for a filter.
244
 *
245
 * Callback for hook_filter_info().
246
 *
247
 * A filter's tips should be informative and to the point. Short tips are
248
 * preferably one-liners.
249
 *
250
 * @param $filter
251
 *   An object representing the filter.
252
 * @param $format
253
 *   An object representing the text format the filter is contained in.
254
 * @param $long
255
 *   Whether this callback should return a short tip to display in a form
256
 *   (FALSE), or whether a more elaborate filter tips should be returned for
257
 *   theme_filter_tips() (TRUE).
258
 *
259
 * @return
260
 *   Translated text to display as a tip.
261
 *
262
 * @ingroup callbacks
263
 */
264
function callback_filter_tips($filter, $format, $long) {
265
 if ($long) {
266
    return t('Lines and paragraphs are automatically recognized. The &lt;br /&gt; line break, &lt;p&gt; paragraph and &lt;/p&gt; close paragraph tags are inserted automatically. If paragraphs are not recognized simply add a couple blank lines.');
267
  }
268
  else {
269
    return t('Lines and paragraphs break automatically.');
270
  }
271
}
272

    
273
/**
274
 * @addtogroup hooks
275
 * @{
276
 */
277

    
278
/**
279
 * Perform actions when a new text format has been created.
280
 *
281
 * @param $format
282
 *   The format object of the format being updated.
283
 *
284
 * @see hook_filter_format_update()
285
 * @see hook_filter_format_disable()
286
 */
287
function hook_filter_format_insert($format) {
288
  mymodule_cache_rebuild();
289
}
290

    
291
/**
292
 * Perform actions when a text format has been updated.
293
 *
294
 * This hook allows modules to act when a text format has been updated in any
295
 * way. For example, when filters have been reconfigured, disabled, or
296
 * re-arranged in the text format.
297
 *
298
 * @param $format
299
 *   The format object of the format being updated.
300
 *
301
 * @see hook_filter_format_insert()
302
 * @see hook_filter_format_disable()
303
 */
304
function hook_filter_format_update($format) {
305
  mymodule_cache_rebuild();
306
}
307

    
308
/**
309
 * Perform actions when a text format has been disabled.
310
 *
311
 * @param $format
312
 *   The format object of the format being disabled.
313
 *
314
 * @see hook_filter_format_insert()
315
 * @see hook_filter_format_update()
316
 */
317
function hook_filter_format_disable($format) {
318
  mymodule_cache_rebuild();
319
}
320

    
321
/**
322
 * @} End of "addtogroup hooks".
323
 */