filter.api.php

Hooks provided by the Filter module.

File

drupal/modules/filter/filter.api.php
View source
  1. <?php
  2. /**
  3. * @file
  4. * Hooks provided by the Filter module.
  5. */
  6. /**
  7. * @addtogroup hooks
  8. * @{
  9. */
  10. /**
  11. * Define content filters.
  12. *
  13. * User submitted content is passed through a group of filters before it is
  14. * output in HTML, in order to remove insecure or unwanted parts, correct or
  15. * enhance the formatting, transform special keywords, etc. A group of filters
  16. * is referred to as a "text format". Administrators can create as many text
  17. * formats as needed. Individual filters can be enabled and configured
  18. * differently for each text format.
  19. *
  20. * This hook is invoked by filter_get_filters() and allows modules to register
  21. * input filters they provide.
  22. *
  23. * Filtering is a two-step process. First, the content is 'prepared' by calling
  24. * the 'prepare callback' function for every filter. The purpose of the 'prepare
  25. * callback' is to escape HTML-like structures. For example, imagine a filter
  26. * which allows the user to paste entire chunks of programming code without
  27. * requiring manual escaping of special HTML characters like < or &. If the
  28. * programming code were left untouched, then other filters could think it was
  29. * HTML and change it. For many filters, the prepare step is not necessary.
  30. *
  31. * The second step is the actual processing step. The result from passing the
  32. * text through all the filters' prepare steps gets passed to all the filters
  33. * again, this time with the 'process callback' function. The process callbacks
  34. * should then actually change the content: transform URLs into hyperlinks,
  35. * convert smileys into images, etc.
  36. *
  37. * For performance reasons content is only filtered once; the result is stored
  38. * in the cache table and retrieved from the cache the next time the same piece
  39. * of content is displayed. If a filter's output is dynamic, it can override the
  40. * cache mechanism, but obviously this should be used with caution: having one
  41. * filter that does not support caching in a particular text format disables
  42. * caching for the entire format, not just for one filter.
  43. *
  44. * Beware of the filter cache when developing your module: it is advised to set
  45. * your filter to 'cache' => FALSE while developing, but be sure to remove that
  46. * setting if it's not needed, when you are no longer in development mode.
  47. *
  48. * @return
  49. * An associative array of filters, whose keys are internal filter names,
  50. * which should be unique and therefore prefixed with the name of the module.
  51. * Each value is an associative array describing the filter, with the
  52. * following elements (all are optional except as noted):
  53. * - title: (required) An administrative summary of what the filter does.
  54. * - description: Additional administrative information about the filter's
  55. * behavior, if needed for clarification.
  56. * - settings callback: The name of a function that returns configuration form
  57. * elements for the filter. See hook_filter_FILTER_settings() for details.
  58. * - default settings: An associative array containing default settings for
  59. * the filter, to be applied when the filter has not been configured yet.
  60. * - prepare callback: The name of a function that escapes the content before
  61. * the actual filtering happens. See hook_filter_FILTER_prepare() for
  62. * details.
  63. * - process callback: (required) The name the function that performs the
  64. * actual filtering. See hook_filter_FILTER_process() for details.
  65. * - cache (default TRUE): Specifies whether the filtered text can be cached.
  66. * Note that setting this to FALSE makes the entire text format not
  67. * cacheable, which may have an impact on the site's overall performance.
  68. * See filter_format_allowcache() for details.
  69. * - tips callback: The name of a function that returns end-user-facing filter
  70. * usage guidelines for the filter. See hook_filter_FILTER_tips() for
  71. * details.
  72. * - weight: A default weight for the filter in new text formats.
  73. *
  74. * @see filter_example.module
  75. * @see hook_filter_info_alter()
  76. */
  77. function hook_filter_info() {
  78. $filters['filter_html'] = array(
  79. 'title' => t('Limit allowed HTML tags'),
  80. '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.'),
  81. 'process callback' => '_filter_html',
  82. 'settings callback' => '_filter_html_settings',
  83. 'default settings' => array(
  84. 'allowed_html' => '<a> <em> <strong> <cite> <blockquote> <code> <ul> <ol> <li> <dl> <dt> <dd>',
  85. 'filter_html_help' => 1,
  86. 'filter_html_nofollow' => 0,
  87. ),
  88. 'tips callback' => '_filter_html_tips',
  89. );
  90. $filters['filter_autop'] = array(
  91. 'title' => t('Convert line breaks'),
  92. 'description' => t('Converts line breaks into HTML (i.e. &lt;br&gt; and &lt;p&gt;) tags.'),
  93. 'process callback' => '_filter_autop',
  94. 'tips callback' => '_filter_autop_tips',
  95. );
  96. return $filters;
  97. }
  98. /**
  99. * Perform alterations on filter definitions.
  100. *
  101. * @param $info
  102. * Array of information on filters exposed by hook_filter_info()
  103. * implementations.
  104. */
  105. function hook_filter_info_alter(&$info) {
  106. // Replace the PHP evaluator process callback with an improved
  107. // PHP evaluator provided by a module.
  108. $info['php_code']['process callback'] = 'my_module_php_evaluator';
  109. // Alter the default settings of the URL filter provided by core.
  110. $info['filter_url']['default settings'] = array(
  111. 'filter_url_length' => 100,
  112. );
  113. }
  114. /**
  115. * @} End of "addtogroup hooks".
  116. */
  117. /**
  118. * Settings callback for hook_filter_info().
  119. *
  120. * Note: This is not really a hook. The function name is manually specified via
  121. * 'settings callback' in hook_filter_info(), with this recommended callback
  122. * name pattern. It is called from filter_admin_format_form().
  123. *
  124. * This callback function is used to provide a settings form for filter
  125. * settings, for filters that need settings on a per-text-format basis. This
  126. * function should return the form elements for the settings; the filter
  127. * module will take care of saving the settings in the database.
  128. *
  129. * If the filter's behavior depends on an extensive list and/or external data
  130. * (e.g. a list of smileys, a list of glossary terms), then the filter module
  131. * can choose to provide a separate, global configuration page rather than
  132. * per-text-format settings. In that case, the settings callback function
  133. * should provide a link to the separate settings page.
  134. *
  135. * @param $form
  136. * The prepopulated form array of the filter administration form.
  137. * @param $form_state
  138. * The state of the (entire) configuration form.
  139. * @param $filter
  140. * The filter object containing the current settings for the given format,
  141. * in $filter->settings.
  142. * @param $format
  143. * The format object being configured.
  144. * @param $defaults
  145. * The default settings for the filter, as defined in 'default settings' in
  146. * hook_filter_info(). These should be combined with $filter->settings to
  147. * define the form element defaults.
  148. * @param $filters
  149. * The complete list of filter objects that are enabled for the given format.
  150. *
  151. * @return
  152. * An array of form elements defining settings for the filter. Array keys
  153. * should match the array keys in $filter->settings and $defaults.
  154. */
  155. function hook_filter_FILTER_settings($form, &$form_state, $filter, $format, $defaults, $filters) {
  156. $filter->settings += $defaults;
  157. $elements = array();
  158. $elements['nofollow'] = array(
  159. '#type' => 'checkbox',
  160. '#title' => t('Add rel="nofollow" to all links'),
  161. '#default_value' => $filter->settings['nofollow'],
  162. );
  163. return $elements;
  164. }
  165. /**
  166. * Prepare callback for hook_filter_info().
  167. *
  168. * Note: This is not really a hook. The function name is manually specified via
  169. * 'prepare callback' in hook_filter_info(), with this recommended callback
  170. * name pattern. It is called from check_markup().
  171. *
  172. * See hook_filter_info() for a description of the filtering process. Filters
  173. * should not use the 'prepare callback' step for anything other than escaping,
  174. * because that would short-circuit the control the user has over the order in
  175. * which filters are applied.
  176. *
  177. * @param $text
  178. * The text string to be filtered.
  179. * @param $filter
  180. * The filter object containing settings for the given format.
  181. * @param $format
  182. * The text format object assigned to the text to be filtered.
  183. * @param $langcode
  184. * The language code of the text to be filtered.
  185. * @param $cache
  186. * A Boolean indicating whether the filtered text is going to be cached in
  187. * {cache_filter}.
  188. * @param $cache_id
  189. * The ID of the filtered text in {cache_filter}, if $cache is TRUE.
  190. *
  191. * @return
  192. * The prepared, escaped text.
  193. */
  194. function hook_filter_FILTER_prepare($text, $filter, $format, $langcode, $cache, $cache_id) {
  195. // Escape <code> and </code> tags.
  196. $text = preg_replace('|<code>(.+?)</code>|se', "[codefilter_code]$1[/codefilter_code]", $text);
  197. return $text;
  198. }
  199. /**
  200. * Process callback for hook_filter_info().
  201. *
  202. * Note: This is not really a hook. The function name is manually specified via
  203. * 'process callback' in hook_filter_info(), with this recommended callback
  204. * name pattern. It is called from check_markup().
  205. *
  206. * See hook_filter_info() for a description of the filtering process. This step
  207. * is where the filter actually transforms the text.
  208. *
  209. * @param $text
  210. * The text string to be filtered.
  211. * @param $filter
  212. * The filter object containing settings for the given format.
  213. * @param $format
  214. * The text format object assigned to the text to be filtered.
  215. * @param $langcode
  216. * The language code of the text to be filtered.
  217. * @param $cache
  218. * A Boolean indicating whether the filtered text is going to be cached in
  219. * {cache_filter}.
  220. * @param $cache_id
  221. * The ID of the filtered text in {cache_filter}, if $cache is TRUE.
  222. *
  223. * @return
  224. * The filtered text.
  225. */
  226. function hook_filter_FILTER_process($text, $filter, $format, $langcode, $cache, $cache_id) {
  227. $text = preg_replace('|\[codefilter_code\](.+?)\[/codefilter_code\]|se', "<pre>$1</pre>", $text);
  228. return $text;
  229. }
  230. /**
  231. * Tips callback for hook_filter_info().
  232. *
  233. * Note: This is not really a hook. The function name is manually specified via
  234. * 'tips callback' in hook_filter_info(), with this recommended callback
  235. * name pattern. It is called from _filter_tips().
  236. *
  237. * A filter's tips should be informative and to the point. Short tips are
  238. * preferably one-liners.
  239. *
  240. * @param $filter
  241. * An object representing the filter.
  242. * @param $format
  243. * An object representing the text format the filter is contained in.
  244. * @param $long
  245. * Whether this callback should return a short tip to display in a form
  246. * (FALSE), or whether a more elaborate filter tips should be returned for
  247. * theme_filter_tips() (TRUE).
  248. *
  249. * @return
  250. * Translated text to display as a tip.
  251. */
  252. function hook_filter_FILTER_tips($filter, $format, $long) {
  253. if ($long) {
  254. 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.');
  255. }
  256. else {
  257. return t('Lines and paragraphs break automatically.');
  258. }
  259. }
  260. /**
  261. * @addtogroup hooks
  262. * @{
  263. */
  264. /**
  265. * Perform actions when a new text format has been created.
  266. *
  267. * @param $format
  268. * The format object of the format being updated.
  269. *
  270. * @see hook_filter_format_update()
  271. * @see hook_filter_format_disable()
  272. */
  273. function hook_filter_format_insert($format) {
  274. mymodule_cache_rebuild();
  275. }
  276. /**
  277. * Perform actions when a text format has been updated.
  278. *
  279. * This hook allows modules to act when a text format has been updated in any
  280. * way. For example, when filters have been reconfigured, disabled, or
  281. * re-arranged in the text format.
  282. *
  283. * @param $format
  284. * The format object of the format being updated.
  285. *
  286. * @see hook_filter_format_insert()
  287. * @see hook_filter_format_disable()
  288. */
  289. function hook_filter_format_update($format) {
  290. mymodule_cache_rebuild();
  291. }
  292. /**
  293. * Perform actions when a text format has been disabled.
  294. *
  295. * @param $format
  296. * The format object of the format being disabled.
  297. *
  298. * @see hook_filter_format_insert()
  299. * @see hook_filter_format_update()
  300. */
  301. function hook_filter_format_disable($format) {
  302. mymodule_cache_rebuild();
  303. }
  304. /**
  305. * @} End of "addtogroup hooks".
  306. */

Functions

Namesort descending Description
hook_filter_FILTER_prepare Prepare callback for hook_filter_info().
hook_filter_FILTER_process Process callback for hook_filter_info().
hook_filter_FILTER_settings Settings callback for hook_filter_info().
hook_filter_FILTER_tips Tips callback for hook_filter_info().
hook_filter_format_disable Perform actions when a text format has been disabled.
hook_filter_format_insert Perform actions when a new text format has been created.
hook_filter_format_update Perform actions when a text format has been updated.
hook_filter_info Define content filters.
hook_filter_info_alter Perform alterations on filter definitions.