From d821de271297a74a8d6a309de1d4cd9113dd77ed Mon Sep 17 00:00:00 2001 From: XhmikosR Date: Tue, 12 Feb 2019 18:18:31 +0200 Subject: [PATCH] Backport sanitize docs from v4. --- docs/_includes/js/overview.html | 75 ++++++++++++++++++++++++++++++ docs/_includes/js/popovers.html | 25 +++++++++- docs/_includes/js/tooltips.html | 23 +++++++++ docs/_includes/nav/javascript.html | 1 + 4 files changed, 123 insertions(+), 1 deletion(-) diff --git a/docs/_includes/js/overview.html b/docs/_includes/js/overview.html index b8a10cf80d51..911b59098dfc 100644 --- a/docs/_includes/js/overview.html +++ b/docs/_includes/js/overview.html @@ -70,6 +70,81 @@

Events

}) {% endhighlight %} +

Sanitizer

+ +

Tooltips and Popovers use our built-in sanitizer to sanitize options which accept HTML.

+

The default whiteList value is the following:

+ +{% highlight js %} +var ARIA_ATTRIBUTE_PATTERN = /^aria-[\w-]*$/i +var DefaultWhitelist = { + // Global attributes allowed on any supplied element below. + '*': ['class', 'dir', 'id', 'lang', 'role', ARIA_ATTRIBUTE_PATTERN], + a: ['target', 'href', 'title', 'rel'], + area: [], + b: [], + br: [], + col: [], + code: [], + div: [], + em: [], + hr: [], + h1: [], + h2: [], + h3: [], + h4: [], + h5: [], + h6: [], + i: [], + img: ['src', 'alt', 'title', 'width', 'height'], + li: [], + ol: [], + p: [], + pre: [], + s: [], + small: [], + span: [], + sub: [], + sup: [], + strong: [], + u: [], + ul: [] +} +{% endhighlight %} + +

If you want to add new values to this default whiteList you can do the following:

+ +{% highlight js %} +var myDefaultWhiteList = $.fn.tooltip.Constructor.DEFAULTS.whiteList + +// To allow table elements +myDefaultWhiteList.table = [] + +// To allow td elements and data-option attributes on td elements +myDefaultWhiteList.td = ['data-option'] + +// You can push your custom regex to validate your attributes. +// Be careful about your regular expressions being too lax +var myCustomRegex = /^data-my-app-[\w-]+/ +myDefaultWhiteList['*'].push(myCustomRegex) +{% endhighlight %} + +

If you want to bypass our sanitizer because you prefer to use a dedicated library, for example DOMPurify, you should do the following:

+ +{% highlight js %} +$('#yourTooltip').tooltip({ + sanitizeFn: function (content) { + return DOMPurify.sanitize(content) + } +}) +{% endhighlight %} + +
+

Browsers without document.implementation.createHTMLDocument

+

In case of browsers that don't support document.implementation.createHTMLDocument, like Internet Explorer 8, the built-in sanitize function returns the HTML as is.

+

If you want to perform sanitization in this case, please specify sanitizeFn and use an external library like DOMPurify.

+
+

Version numbers

The version of each of Bootstrap's jQuery plugins can be accessed via the VERSION property of the plugin's constructor. For example, for the tooltip plugin:

{% highlight js %} diff --git a/docs/_includes/js/popovers.html b/docs/_includes/js/popovers.html index 2d440f3c2106..1d129c28a4de 100644 --- a/docs/_includes/js/popovers.html +++ b/docs/_includes/js/popovers.html @@ -139,6 +139,11 @@

Usage

Options

Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-, as in data-animation="".

+ +
+

Note that for security reasons the sanitize, sanitizeFn and whiteList options cannot be supplied using data attributes.

+
+
@@ -239,7 +244,25 @@

Options

Keeps the popover within the bounds of this element. Example: viewport: '#viewport' or { "selector": "#viewport", "padding": 0 }

If a function is given, it is called with the triggering element DOM node as its only argument. The this context is set to the popover instance.

- + + + + + + + + + + + + + + + + + + +
sanitizebooleantrueEnable or disable the sanitization. If activated 'template', 'content' and 'title' options will be sanitized.
whiteListobjectDefault valueObject which contains allowed attributes and tags
sanitizeFnnull | functionnullHere you can supply your own sanitize function. This can be useful if you prefer to use a dedicated library to perform sanitization.
diff --git a/docs/_includes/js/tooltips.html b/docs/_includes/js/tooltips.html index 09545369f79c..b1c8b1e8f80d 100644 --- a/docs/_includes/js/tooltips.html +++ b/docs/_includes/js/tooltips.html @@ -115,6 +115,11 @@

Tooltips on disabled elements require wrapper elements

Options

Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-, as in data-animation="".

+ +
+

Note that for security reasons the sanitize, sanitizeFn and whiteList options cannot be supplied using data attributes.

+
+
@@ -206,6 +211,24 @@

Options

If a function is given, it is called with the triggering element DOM node as its only argument. The this context is set to the tooltip instance.

+ + + + + + + + + + + + + + + + + +
sanitizebooleantrueEnable or disable the sanitization. If activated 'template', 'content' and 'title' options will be sanitized.
whiteListobjectDefault valueObject which contains allowed attributes and tags
sanitizeFnnull | functionnullHere you can supply your own sanitize function. This can be useful if you prefer to use a dedicated library to perform sanitization.
diff --git a/docs/_includes/nav/javascript.html b/docs/_includes/nav/javascript.html index f8d314faa596..6cfc90abfb5f 100644 --- a/docs/_includes/nav/javascript.html +++ b/docs/_includes/nav/javascript.html @@ -6,6 +6,7 @@
  • Programmatic API
  • No conflict
  • Events
    • +
  • Sanitizer
  • Version numbers
  • When JavaScript is disabled
  • Third-party libraries