3 namespace Drupal\filter\Plugin;
5 use Drupal\Component\Plugin\PluginInspectionInterface;
6 use Drupal\Component\Plugin\ConfigurablePluginInterface;
7 use Drupal\Core\Form\FormStateInterface;
10 * Defines the interface for text processing filter plugins.
12 * User submitted content is passed through a group of filters before it is
13 * output in HTML, in order to remove insecure or unwanted parts, correct or
14 * enhance the formatting, transform special keywords, etc. A group of filters
15 * is referred to as a "text format". Administrators can create as many text
16 * formats as needed. Individual filters can be enabled and configured
17 * differently for each text format.
19 * @see \Drupal\filter\Entity\FilterFormat
21 * Filtering is a two-step process. First, the content is 'prepared' by calling
22 * the FilterInterface::prepare() method for every filter. The purpose is to
23 * escape HTML-like structures. For example, imagine a filter which allows the
24 * user to paste entire chunks of programming code without requiring manual
25 * escaping of special HTML characters like < or &. If the programming code were
26 * left untouched, then other filters could think it was HTML and change it. For
27 * many filters, the prepare step is not necessary.
29 * The second step is the actual processing step. The result from passing the
30 * text through all the filters' prepare steps gets passed to all the filters
31 * again, this time to the FilterInterface::process() method. The process method
32 * should then actually change the content: transform URLs into hyperlinks,
33 * convert smileys into images, etc.
35 * @see \Drupal\filter\Plugin\FilterInterface::process()
38 * Typically, only text processing is applied, but in more advanced use cases,
40 * - declare asset libraries to be loaded;
41 * - declare cache tags that the resulting filtered text depends upon, so when
42 * either of those cache tags is invalidated, the render-cached HTML that the
43 * filtered text is part of should also be invalidated;
44 * - create placeholders to apply uncacheable filtering, for example because it
45 * changes every few seconds.
47 * @see \Drupal\filter\Plugin\FilterInterface::process()
49 * Filters are discovered through annotations, which may contain the following
50 * definition properties:
51 * - title: (required) An administrative summary of what the filter does.
52 * - type: (required) A classification of the filter's purpose. This is one
54 * - FilterInterface::TYPE_HTML_RESTRICTOR: HTML tag and attribute
55 * restricting filters.
56 * - FilterInterface::TYPE_MARKUP_LANGUAGE: Non-HTML markup language filters
58 * - FilterInterface::TYPE_TRANSFORM_IRREVERSIBLE: Irreversible
59 * transformation filters.
60 * - FilterInterface::TYPE_TRANSFORM_REVERSIBLE: Reversible transformation
62 * - description: Additional administrative information about the filter's
63 * behavior, if needed for clarification.
64 * - status: The default status for new instances of the filter. Defaults to
66 * - weight: A default weight for new instances of the filter. Defaults to 0.
67 * - settings: An associative array containing default settings for new
68 * instances of the filter.
70 * Most implementations want to extend the generic basic implementation for
73 * @see \Drupal\filter\Annotation\Filter
74 * @see \Drupal\filter\FilterPluginManager
75 * @see \Drupal\filter\Plugin\FilterBase
78 interface FilterInterface extends ConfigurablePluginInterface, PluginInspectionInterface {
81 * Non-HTML markup language filters that generate HTML.
83 const TYPE_MARKUP_LANGUAGE = 0;
86 * HTML tag and attribute restricting filters to prevent XSS attacks.
88 const TYPE_HTML_RESTRICTOR = 1;
91 * Reversible transformation filters.
93 const TYPE_TRANSFORM_REVERSIBLE = 2;
96 * Irreversible transformation filters.
98 const TYPE_TRANSFORM_IRREVERSIBLE = 3;
101 * Returns the processing type of this filter plugin.
105 * - FilterInterface::TYPE_MARKUP_LANGUAGE
106 * - FilterInterface::TYPE_HTML_RESTRICTOR
107 * - FilterInterface::TYPE_TRANSFORM_REVERSIBLE
108 * - FilterInterface::TYPE_TRANSFORM_IRREVERSIBLE
110 public function getType();
113 * Returns the administrative label for this filter plugin.
117 public function getLabel();
120 * Returns the administrative description for this filter plugin.
124 public function getDescription();
127 * Generates a filter's settings form.
130 * A minimally prepopulated form array.
131 * @param \Drupal\Core\Form\FormStateInterface $form_state
132 * The state of the (entire) configuration form.
135 * The $form array with additional form elements for the settings of this
136 * filter. The submitted form values should match $this->settings.
138 public function settingsForm(array $form, FormStateInterface $form_state);
141 * Prepares the text for processing.
143 * Filters should not use the prepare method for anything other than escaping,
144 * because that would short-circuit the control the user has over the order in
145 * which filters are applied.
147 * @param string $text
148 * The text string to be filtered.
149 * @param string $langcode
150 * The language code of the text to be filtered.
153 * The prepared, escaped text.
155 public function prepare($text, $langcode);
158 * Performs the filter processing.
160 * @param string $text
161 * The text string to be filtered.
162 * @param string $langcode
163 * The language code of the text to be filtered.
165 * @return \Drupal\filter\FilterProcessResult
166 * The filtered text, wrapped in a FilterProcessResult object, and possibly
167 * with associated assets, cacheability metadata and placeholders.
169 * @see \Drupal\filter\FilterProcessResult
171 public function process($text, $langcode);
174 * Returns HTML allowed by this filter's configuration.
176 * May be implemented by filters of the FilterInterface::TYPE_HTML_RESTRICTOR
177 * type, this won't be used for filters of other types; they should just
180 * This callback function is only necessary for filters that strip away HTML
181 * tags (and possibly attributes) and allows other modules to gain insight in
182 * a generic manner into which HTML tags and attributes are allowed by a
185 * @return array|false
186 * A nested array with *either* of the following keys:
187 * - 'allowed': (optional) the allowed tags as keys, and for each of those
188 * tags (keys) either of the following values:
189 * - TRUE to indicate any attribute is allowed
190 * - FALSE to indicate no attributes are allowed
191 * - an array to convey attribute restrictions: the keys must be
192 * attribute names (which may use a wildcard, e.g. "data-*"), the
193 * possible values are similar to the above:
194 * - TRUE to indicate any attribute value is allowed
195 * - FALSE to indicate the attribute is forbidden
196 * - an array to convey attribute value restrictions: the key must
197 * be attribute values (which may use a wildcard, e.g. "xsd:*"),
198 * the possible values are TRUE or FALSE: to mark the attribute
199 * value as allowed or forbidden, respectively
200 * - 'forbidden_tags': (optional) the forbidden tags
202 * There is one special case: the "wildcard tag", "*": any attribute
203 * restrictions on that pseudotag apply to all tags.
205 * If no restrictions apply, then FALSE must be returned.
207 * Here is a concrete example, for a very granular filter:
210 * 'allowed' => array(
211 * // Allows any attribute with any value on the <div> tag.
213 * // Allows no attributes on the <p> tag.
215 * // Allows the following attributes on the <a> tag:
216 * // - 'href', with any value;
217 * // - 'rel', with the value 'nofollow' value.
220 * 'rel' => array('nofollow' => TRUE),
222 * // Only allows the 'src' and 'alt' attributes on the <alt> tag,
228 * // Allow RDFa on <span> tags, using only the dc, foaf, xsd and sioc
229 * // vocabularies/namespaces.
231 * 'property' => array('dc:*' => TRUE, 'foaf:*' => TRUE),
232 * 'datatype' => array('xsd:*' => TRUE),
233 * 'rel' => array('sioc:*' => TRUE),
235 * // Forbid the 'style' and 'on*' ('onClick' etc.) attributes on any
245 * A simpler example, for a very coarse filter:
248 * 'forbidden_tags' => array('iframe', 'script')
252 * The simplest example possible: a filter that doesn't allow any HTML:
255 * 'allowed' => array()
259 * And for a filter that applies no restrictions, i.e. allows any HTML:
264 * @see \Drupal\filter\Entity\FilterFormatInterface::getHtmlRestrictions()
266 public function getHTMLRestrictions();
269 * Generates a filter's tip.
271 * A filter's tips should be informative and to the point. Short tips are
272 * preferably one-liners.
275 * Whether this callback should return a short tip to display in a form
276 * (FALSE), or whether a more elaborate filter tips should be returned for
277 * template_preprocess_filter_tips() (TRUE).
279 * @return string|null
280 * Translated text to display as a tip, or NULL if this filter has no tip.
282 * @todo Split into getSummaryItem() and buildGuidelines().
284 public function tips($long = FALSE);