interface FilterInterface
Same name in this branch
- 10 core/lib/Drupal/Core/Routing/FilterInterface.php \Drupal\Core\Routing\FilterInterface
Same name in other branches
- 9 core/modules/filter/src/Plugin/FilterInterface.php \Drupal\filter\Plugin\FilterInterface
- 9 core/lib/Drupal/Core/Routing/FilterInterface.php \Drupal\Core\Routing\FilterInterface
- 8.9.x core/modules/filter/src/Plugin/FilterInterface.php \Drupal\filter\Plugin\FilterInterface
- 8.9.x core/lib/Drupal/Core/Routing/FilterInterface.php \Drupal\Core\Routing\FilterInterface
- 11.x core/modules/filter/src/Plugin/FilterInterface.php \Drupal\filter\Plugin\FilterInterface
- 11.x core/lib/Drupal/Core/Routing/FilterInterface.php \Drupal\Core\Routing\FilterInterface
Defines the interface for text processing filter plugins.
User submitted content is passed through a group of filters before it is output in HTML, in order to remove insecure or unwanted parts, correct or enhance the formatting, transform special keywords, etc. A group of filters is referred to as a "text format". Administrators can create as many text formats as needed. Individual filters can be enabled and configured differently for each text format.
Hierarchy
- interface \Drupal\Component\Plugin\ConfigurableInterface; interface \Drupal\Component\Plugin\DependentPluginInterface; interface \Drupal\Component\Plugin\PluginInspectionInterface
- interface \Drupal\filter\Plugin\FilterInterface extends \Drupal\Component\Plugin\ConfigurableInterface \Drupal\Component\Plugin\DependentPluginInterface \Drupal\Component\Plugin\PluginInspectionInterface
Expanded class hierarchy of FilterInterface
All classes that implement FilterInterface
See also
\Drupal\filter\Entity\FilterFormat
Filtering is a two-step process. First, the content is 'prepared' by calling the FilterInterface::prepare() method for every filter. The purpose 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 many filters, the prepare step is not necessary.
The second step is the actual processing step. The result from passing the text through all the filters' prepare steps gets passed to all the filters again, this time to the FilterInterface::process() method. The process method should then actually change the content: transform URLs into hyperlinks, convert smileys into images, etc.
\Drupal\filter\Plugin\FilterInterface::process()
Typically, only text processing is applied, but in more advanced use cases, filters may also:
- declare asset libraries to be loaded;
- declare Cache API tags that the resulting filtered text depends upon, so when either of those Cache API tags is invalidated, the render-cached HTML that the filtered text is part of should also be invalidated;
- create placeholders to apply uncacheable filtering, for example because it changes every few seconds.
\Drupal\filter\Plugin\FilterInterface::process()
Filters are discovered through annotations, which may contain the following definition properties:
- title: (required) An administrative summary of what the filter does.
- type: (required) A classification of the filter's purpose. This is one of
the following:
- FilterInterface::TYPE_HTML_RESTRICTOR: HTML tag and attribute restricting filters.
- FilterInterface::TYPE_MARKUP_LANGUAGE: Non-HTML markup language filters that generate HTML.
- FilterInterface::TYPE_TRANSFORM_IRREVERSIBLE: Irreversible transformation filters.
- FilterInterface::TYPE_TRANSFORM_REVERSIBLE: Reversible transformation filters.
- description: Additional administrative information about the filter's behavior, if needed for clarification.
- status: The default status for new instances of the filter. Defaults to FALSE.
- weight: A default weight for new instances of the filter. Defaults to 0.
- settings: An associative array containing default settings for new instances of the filter.
Most implementations want to extend the generic basic implementation for filter plugins.
\Drupal\filter\Annotation\Filter
\Drupal\filter\FilterPluginManager
\Drupal\filter\Plugin\FilterBase
34 files declare their use of FilterInterface
- editor.module in core/
modules/ editor/ editor.module - Adds bindings for client-side "text editors" to text formats.
- EditorFileReference.php in core/
modules/ editor/ src/ Plugin/ Filter/ EditorFileReference.php - EditorMediaDialog.php in core/
modules/ media/ src/ Form/ EditorMediaDialog.php - FilterAlign.php in core/
modules/ filter/ src/ Plugin/ Filter/ FilterAlign.php - FilterAPITest.php in core/
modules/ filter/ tests/ src/ Kernel/ FilterAPITest.php
1 string reference to 'FilterInterface'
- core.data_types.schema.yml in core/
config/ schema/ core.data_types.schema.yml - core/config/schema/core.data_types.schema.yml
File
-
core/
modules/ filter/ src/ Plugin/ FilterInterface.php, line 79
Namespace
Drupal\filter\PluginView source
interface FilterInterface extends ConfigurableInterface, DependentPluginInterface, PluginInspectionInterface {
/**
* Non-HTML markup language filters that generate HTML.
*/
const TYPE_MARKUP_LANGUAGE = 0;
/**
* HTML tag and attribute restricting filters to prevent XSS attacks.
*/
const TYPE_HTML_RESTRICTOR = 1;
/**
* Reversible transformation filters.
*/
const TYPE_TRANSFORM_REVERSIBLE = 2;
/**
* Irreversible transformation filters.
*/
const TYPE_TRANSFORM_IRREVERSIBLE = 3;
/**
* Returns the processing type of this filter plugin.
*
* @return int
* One of:
* - FilterInterface::TYPE_MARKUP_LANGUAGE
* - FilterInterface::TYPE_HTML_RESTRICTOR
* - FilterInterface::TYPE_TRANSFORM_REVERSIBLE
* - FilterInterface::TYPE_TRANSFORM_IRREVERSIBLE
*/
public function getType();
/**
* Returns the administrative label for this filter plugin.
*
* @return string
*/
public function getLabel();
/**
* Returns the administrative description for this filter plugin.
*
* @return string
*/
public function getDescription();
/**
* Generates a filter's settings form.
*
* @param array $form
* A minimally prepopulated form array.
* @param \Drupal\Core\Form\FormStateInterface $form_state
* The state of the (entire) configuration form.
*
* @return array
* The $form array with additional form elements for the settings of this
* filter. The submitted form values should match $this->settings.
*/
public function settingsForm(array $form, FormStateInterface $form_state);
/**
* Prepares the text for processing.
*
* Filters should not use the prepare method for anything other than escaping,
* because that would short-circuit the control the user has over the order in
* which filters are applied.
*
* @param string $text
* The text string to be filtered.
* @param string $langcode
* The language code of the text to be filtered.
*
* @return string
* The prepared, escaped text.
*/
public function prepare($text, $langcode);
/**
* Performs the filter processing.
*
* @param string $text
* The text string to be filtered.
* @param string $langcode
* The language code of the text to be filtered.
*
* @return \Drupal\filter\FilterProcessResult
* The filtered text, wrapped in a FilterProcessResult object, and possibly
* with associated assets, cacheability metadata and placeholders.
*
* @see \Drupal\filter\FilterProcessResult
*/
public function process($text, $langcode);
/**
* Returns HTML allowed by this filter's configuration.
*
* May be implemented by filters of the FilterInterface::TYPE_HTML_RESTRICTOR
* type, this won't be used for filters of other types; they should just
* return FALSE.
*
* This callback function is only necessary for filters that strip away HTML
* tags (and possibly attributes) and allows other modules to gain insight in
* a generic manner into which HTML tags and attributes are allowed by a
* format.
*
* @return array|false
* A nested array with the following structure:
* - 'allowed': the allowed tags as keys, and for each of those tags
* (keys) either of the following values:
* - TRUE to indicate any attribute is allowed
* - FALSE to indicate no attributes are allowed
* - an array to convey attribute restrictions: the keys must be
* attribute names (which may use a wildcard, e.g. "data-*"), the
* possible values are similar to the above:
* - TRUE to indicate any attribute value is allowed
* - FALSE to indicate the attribute is forbidden
* - an array to convey attribute value restrictions: the key must
* be attribute values (which may use a wildcard, e.g. "xsd:*"),
* the possible values are TRUE or FALSE: to mark the attribute
* value as allowed or forbidden, respectively
*
* There is one special case: the "wildcard tag", "*": any attribute
* restrictions on that pseudotag apply to all tags.
*
* If no restrictions apply, then FALSE must be returned.
*
* Here is a concrete example, for a very granular filter:
* @code
* [
* 'allowed' => [
* // Allows any attribute with any value on the <div> tag.
* 'div' => TRUE,
* // Allows no attributes on the <p> tag.
* 'p' => FALSE,
* // Allows the following attributes on the <a> tag:
* // - 'href', with any value;
* // - 'rel', with the value 'nofollow' value.
* 'a' => [
* 'href' => TRUE,
* 'rel' => ['nofollow' => TRUE],
* ],
* // Only allows the 'src' and 'alt' attributes on the <alt> tag,
* // with any value.
* 'img' => [
* 'src' => TRUE,
* 'alt' => TRUE,
* ],
* // Forbid the 'style' and 'on*' ('onClick' etc.) attributes on any
* // tag.
* '*' => [
* 'style' => FALSE,
* 'on*' => FALSE,
* ],
* ]
* ]
* @endcode
*
* The simplest example possible: a filter that doesn't allow any HTML:
* @code
* [
* 'allowed' => []
* ]
* @endcode
*
* And for a filter that applies no restrictions, i.e. allows any HTML:
* @code
* FALSE
* @endcode
*
* @see \Drupal\filter\Entity\FilterFormatInterface::getHtmlRestrictions()
*/
public function getHTMLRestrictions();
/**
* Generates a filter's tip.
*
* A filter's tips should be informative and to the point. Short tips are
* preferably one-liners.
*
* @param bool $long
* Whether this callback should return a short tip to display in a form
* (FALSE), or whether a more elaborate filter tips should be returned for
* template_preprocess_filter_tips() (TRUE).
*
* @return string|null
* Translated text to display as a tip, or NULL if this filter has no tip.
*
* @todo Split into getSummaryItem() and buildGuidelines().
*/
public function tips($long = FALSE);
}
Members
Title Sort descending | Modifiers | Object type | Summary | Overrides |
---|---|---|---|---|
ConfigurableInterface::defaultConfiguration | public | function | Gets default configuration for this plugin. | 13 |
ConfigurableInterface::getConfiguration | public | function | Gets this plugin's configuration. | 13 |
ConfigurableInterface::setConfiguration | public | function | Sets the configuration for this plugin instance. | 13 |
DependentPluginInterface::calculateDependencies | public | function | Calculates dependencies for the configured plugin. | 19 |
FilterInterface::getDescription | public | function | Returns the administrative description for this filter plugin. | 1 |
FilterInterface::getHTMLRestrictions | public | function | Returns HTML allowed by this filter's configuration. | 1 |
FilterInterface::getLabel | public | function | Returns the administrative label for this filter plugin. | 1 |
FilterInterface::getType | public | function | Returns the processing type of this filter plugin. | 1 |
FilterInterface::prepare | public | function | Prepares the text for processing. | 1 |
FilterInterface::process | public | function | Performs the filter processing. | 23 |
FilterInterface::settingsForm | public | function | Generates a filter's settings form. | 1 |
FilterInterface::tips | public | function | Generates a filter's tip. | 1 |
FilterInterface::TYPE_HTML_RESTRICTOR | constant | HTML tag and attribute restricting filters to prevent XSS attacks. | ||
FilterInterface::TYPE_MARKUP_LANGUAGE | constant | Non-HTML markup language filters that generate HTML. | ||
FilterInterface::TYPE_TRANSFORM_IRREVERSIBLE | constant | Irreversible transformation filters. | ||
FilterInterface::TYPE_TRANSFORM_REVERSIBLE | constant | Reversible transformation filters. | ||
PluginInspectionInterface::getPluginDefinition | public | function | Gets the definition of the plugin implementation. | 6 |
PluginInspectionInterface::getPluginId | public | function | Gets the plugin_id of the plugin instance. | 2 |
Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.