Struct ruma_html::SanitizerConfig

source ·

pub struct SanitizerConfig { /* private fields */ }

Expand description

Configuration to sanitize HTML elements and attributes.

Implementations§

source §

impl SanitizerConfig

source

pub fn new() -> Self

Constructs an empty SanitizerConfig that will not filter any element or attribute.

The list of allowed and replaced elements can be changed with Self::allow_elements(), Self::replace_elements(), Self::ignore_elements(), Self::remove_elements(), Self::remove_reply_fallback().

The list of allowed and replaced attributes can be changed with Self::allow_attributes(), Self::replace_attributes(), Self::remove_attributes(), Self::allow_schemes(), Self::deny_schemes(), Self::allow_classes(), Self::remove_classes().

source

pub fn with_mode(mode: HtmlSanitizerMode) -> Self

Constructs a SanitizerConfig with the given mode for filtering elements and attributes.

The mode defines the basic list of allowed and replaced elements and attributes and the maximum nesting level of elements.

The list of allowed and replaced elements can be changed with Self::allow_elements(), Self::replace_elements(), Self::ignore_elements(), Self::remove_elements(), Self::remove_reply_fallback().

The list of allowed and replaced attributes can be changed with Self::allow_attributes(), Self::replace_attributes(), Self::remove_attributes(), Self::allow_schemes(), Self::deny_schemes(), Self::allow_classes(), Self::remove_classes().

source

pub fn strict() -> Self

Constructs a SanitizerConfig that will filter elements and attributes not suggested in the Matrix specification.

The list of allowed and replaced elements can be changed with Self::allow_elements(), Self::replace_elements(), Self::ignore_elements(), Self::remove_elements(), Self::remove_reply_fallback().

The list of allowed and replaced attributes can be changed with Self::allow_attributes(), Self::replace_attributes(), Self::remove_attributes(), Self::allow_schemes(), Self::deny_schemes(), Self::allow_classes(), Self::remove_classes().

This is the same as calling SanitizerConfig::with_mode(HtmlSanitizerMode::Strict).

source

pub fn compat() -> Self

Constructs a SanitizerConfig that will filter elements and attributes not [suggested in the Matrix specification], except a few for improved compatibility:

The matrix scheme is allowed in links.

The list of allowed elements can be changed with Self::allow_elements(), Self::replace_elements(), Self::ignore_elements(), Self::remove_elements(), Self::remove_reply_fallback().

The list of allowed attributes can be changed with Self::allow_attributes(), Self::replace_attributes(), Self::remove_attributes(), Self::allow_schemes(), Self::deny_schemes(), Self::allow_classes(), Self::remove_classes().

This is the same as calling SanitizerConfig::with_mode(HtmlSanitizerMode::Compat).

source

pub fn replace_elements( self, elements: impl IntoIterator<Item = NameReplacement>, behavior: ListBehavior, ) -> Self

Change the list of replaced HTML elements.

The given list is added to or replaces the list of replacements of the current mode, depending on the ListBehavior.

The replacement occurs before the removal, so the replaced element should not be in the allowed list of elements, but the replacement element should.

§Parameters

elements: The list of element names replacements.

source

pub fn remove_elements( self, elements: impl IntoIterator<Item = &'static str>, ) -> Self

Remove the given HTML elements.

When an element is removed, the element and its children are dropped. If you want to remove an element but keep its children, use SanitizerConfig::ignore_elements or SanitizerConfig::allow_elements.

Removing elements has a higher priority than ignoring or allowing. So if an element is in this list, it will always be removed.

§Parameters

elements: The list of element names to remove.

source

pub fn remove_reply_fallback(self) -> Self

Remove the rich reply fallback.

Calling this allows to remove the mx-reply element in addition to the list of elements to remove.

Removing elements has a higher priority than ignoring or allowing. So if this settings is set, mx-reply will always be removed.

source

pub fn ignore_elements( self, elements: impl IntoIterator<Item = &'static str>, ) -> Self

Ignore the given HTML elements.

When an element is ignored, the element is dropped and replaced by its children. If you want to drop an element and its children, use SanitizerConfig::remove_elements.

Removing elements has a lower priority than removing but a higher priority than allowing.

§Parameters

elements: The list of element names to ignore.

source

pub fn allow_elements( self, elements: impl IntoIterator<Item = &'static str>, behavior: ListBehavior, ) -> Self

Change the list of allowed HTML elements.

The given list is added to or replaces the list of allowed elements of the current mode, depending on the ListBehavior.

If an element is not allowed, it is ignored. If no mode is set and no elements are explicitly allowed, all elements are allowed.

§Parameters

elements: The list of element names.

source

pub fn replace_attributes<'a>( self, attrs: impl IntoIterator<Item = ElementAttributesReplacement<'a>>, behavior: ListBehavior, ) -> Self

Change the list of replaced attributes per HTML element.

The given list is added to or replaces the list of replacements of the current mode, depending on the ListBehavior.

The replacement occurs before the removal, so the replaced attribute should not be in the list of allowed attributes, but the replacement attribute should. Attribute replacement occurs before element replacement, so if you want to replace an attribute on an element that is set to be replaced, you must use the replaced element’s name, not the name of its replacement.

§Parameters

attrs: The list of element’s attributes replacements.

source

pub fn remove_attributes<'a>( self, attrs: impl IntoIterator<Item = PropertiesNames<'a>>, ) -> Self

Remove the given attributes per HTML element.

Removing attributes has a higher priority than allowing. So if an attribute is in this list, it will always be removed.

§Parameters

attrs: The list of attributes per element. The value of parent is the element name, and properties contains attribute names.

source

pub fn allow_attributes<'a>( self, attrs: impl IntoIterator<Item = PropertiesNames<'a>>, behavior: ListBehavior, ) -> Self

Change the list of allowed attributes per HTML element.

The given list is added to or replaces the list of allowed attributes of the current mode, depending on the ListBehavior.

If an attribute is not allowed, it is removed. If no mode is set and no attributes are explicitly allowed, all attributes are allowed.

§Parameters

attrs: The list of attributes per element. The value of parent is the element name, and properties contains attribute names.

source

pub fn deny_schemes<'a>( self, schemes: impl IntoIterator<Item = ElementAttributesSchemes<'a>>, ) -> Self

Deny the given URI schemes per attribute per HTML element.

Denying schemes has a higher priority than allowing. So if a scheme is in this list, it will always be denied.

If a scheme is denied, its element is removed, because it is deemed that the element will not be usable without it URI.

§Parameters

schemes: The list of schemes per attribute per element.

source

pub fn allow_schemes<'a>( self, schemes: impl IntoIterator<Item = ElementAttributesSchemes<'a>>, behavior: ListBehavior, ) -> Self

Change the list of allowed schemes per attribute per HTML element.

The given list is added to or replaces the list of allowed schemes of the current mode, depending on the ListBehavior.

If a scheme is not allowed, it is denied. If a scheme is denied, its element is ignored, because it is deemed that the element will not be usable without it URI. If no mode is set and no schemes are explicitly allowed, all schemes are allowed.

§Parameters

schemes: The list of schemes per attribute per element.

source

pub fn remove_classes<'a>( self, classes: impl IntoIterator<Item = PropertiesNames<'a>>, ) -> Self

Deny the given classes per HTML element.

Removing classes has a higher priority than allowing. So if a class is in this list, it will always be removed.

If all the classes of a class attribute are removed, the whole attribute is removed.

In the list of classes, the names must match the full class name. * can be used as a wildcard for any number of characters. So language will only match a class named language, and language-* will match any class name starting with language-.

§Parameters

attrs: The list of classes per element. The value of parent is the element name, and properties contains classes.

source

pub fn allow_classes<'a>( self, classes: impl IntoIterator<Item = PropertiesNames<'a>>, behavior: ListBehavior, ) -> Self

Change the list of allowed classes per HTML element.

The given list is added, removed or replaces the list of allowed classes of the current mode, depending on the ListBehavior.

If a class is not allowed, it is removed. If all the classes of a class attribute are removed, the whole attribute is removed. If no mode is set and no classes are explicitly allowed, all classes are allowed.

In the list of classes, the names must match the full class name. * can be used as a wildcard for any number of characters. So language will only match a class named language, and language-* will match any class name starting with language-.

§Parameters

attrs: The list of classes per element. The value of parent is the element name, and properties contains classes.

source

pub fn max_depth(self, depth: u32) -> Self

The maximum nesting level of HTML elements.

This overrides the maximum depth set by the mode, if one is set.

All elements that are deeper than the maximum depth will be removed. If no mode is set and no maximum depth is explicitly set, elements are not filtered by their nesting level.