Backport sanitize docs from v4.

diff --git a/docs/_includes/js/overview.html b/docs/_includes/js/overview.html
index b8a10cf80d51efa9e9e46c010cb5a807404785fe..911b59098dfc0ec6c1911ebcf72df333833f68fa 100644 (file)
--- a/docs/_includes/js/overview.html
+++ b/docs/_includes/js/overview.html
@@ -70,6 +70,81 @@ $('#myModal').on('show.bs.modal', function (e) {
 })
 {% endhighlight %}
 
+  <h2 id="js-sanitizer">Sanitizer</h2>
+
+  <p>Tooltips and Popovers use our built-in sanitizer to sanitize options which accept HTML.</p>
+  <p>The default <code>whiteList</code> value is the following:</p>
+
+{% 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 %}
+
+  <p>If you want to add new values to this default <code>whiteList</code> you can do the following:</p>
+
+{% 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 %}
+
+  <p>If you want to bypass our sanitizer because you prefer to use a dedicated library, for example <a href="https://www.npmjs.com/package/dompurify">DOMPurify</a>, you should do the following:</p>
+
+{% highlight js %}
+$('#yourTooltip').tooltip({
+  sanitizeFn: function (content) {
+    return DOMPurify.sanitize(content)
+  }
+})
+{% endhighlight %}
+
+  <div class="bs-callout bs-callout-danger" id="callout-sanitizer-no-createhtmldocument">
+    <h4>Browsers without <code>document.implementation.createHTMLDocument</code></h4>
+    <p>In case of browsers that don't support <code>document.implementation.createHTMLDocument</code>, like Internet Explorer 8, the built-in sanitize function returns the HTML as is.</p>
+    <p>If you want to perform sanitization in this case, please specify <code>sanitizeFn</code> and use an external library like <a href="https://www.npmjs.com/package/dompurify">DOMPurify</a>.</p>
+  </div>
+
   <h2 id="js-version-nums">Version numbers</h2>
   <p>The version of each of Bootstrap's jQuery plugins can be accessed via the <code>VERSION</code> property of the plugin's constructor. For example, for the tooltip plugin:</p>
 {% highlight js %}

diff --git a/docs/_includes/js/popovers.html b/docs/_includes/js/popovers.html
index 2d440f3c2106b5b031afb5c27fefc7258354c6be..1d129c28a4de8472774e060cf37e47b76aba4ccf 100644 (file)
--- a/docs/_includes/js/popovers.html
+++ b/docs/_includes/js/popovers.html
@@ -139,6 +139,11 @@ sagittis lacus vel augue laoreet rutrum faucibus.">
 
   <h3 id="popovers-options">Options</h3>
   <p>Options can be passed via data attributes or JavaScript. For data attributes, append the option name to <code>data-</code>, as in <code>data-animation=""</code>.</p>
+
+  <div class="bs-callout bs-callout-warning" id="callout-popover-disabled-options">
+    <p>Note that for security reasons the <code>sanitize</code>, <code>sanitizeFn</code> and <code>whiteList</code> options cannot be supplied using data attributes.</p>
+  </div>
+
   <div class="table-responsive">
     <table class="table table-bordered table-striped js-options-table js-options-table">
       <thead>
@@ -239,7 +244,25 @@ sagittis lacus vel augue laoreet rutrum faucibus.">
             <p>Keeps the popover within the bounds of this element. Example: <code>viewport: '#viewport'</code> or <code>{ "selector": "#viewport", "padding": 0 }</code></p>
             <p>If a function is given, it is called with the triggering element DOM node as its only argument. The <code>this</code> context is set to the popover instance.</p>
           </td>
-       </tr>
+        </tr>
+        <tr>
+          <td>sanitize</td>
+          <td>boolean</td>
+          <td>true</td>
+          <td>Enable or disable the sanitization. If activated <code>'template'</code>, <code>'content'</code> and <code>'title'</code> options will be sanitized.</td>
+        </tr>
+        <tr>
+          <td>whiteList</td>
+          <td>object</td>
+          <td><a href="#js-sanitizer">Default value</a></td>
+          <td>Object which contains allowed attributes and tags</td>
+        </tr>
+        <tr>
+          <td>sanitizeFn</td>
+          <td>null | function</td>
+          <td>null</td>
+          <td>Here you can supply your own sanitize function. This can be useful if you prefer to use a dedicated library to perform sanitization.</td>
+        </tr>
       </tbody>
     </table>
   </div><!-- /.table-responsive -->

diff --git a/docs/_includes/js/tooltips.html b/docs/_includes/js/tooltips.html
index 09545369f79cc4249ca95d34aab576245daf27d0..b1c8b1e8f80d11c73a96cca025bc8cddbfe91fb7 100644 (file)
--- a/docs/_includes/js/tooltips.html
+++ b/docs/_includes/js/tooltips.html
@@ -115,6 +115,11 @@ $('#example').tooltip(options)
 
   <h3 id="tooltips-options">Options</h3>
   <p>Options can be passed via data attributes or JavaScript. For data attributes, append the option name to <code>data-</code>, as in <code>data-animation=""</code>.</p>
+
+  <div class="bs-callout bs-callout-warning" id="callout-tooltip-disabled-options">
+    <p>Note that for security reasons the <code>sanitize</code>, <code>sanitizeFn</code> and <code>whiteList</code> options cannot be supplied using data attributes.</p>
+  </div>
+
   <div class="table-responsive">
     <table class="table table-bordered table-striped js-options-table">
       <thead>
@@ -206,6 +211,24 @@ $('#example').tooltip(options)
             <p>If a function is given, it is called with the triggering element DOM node as its only argument. The <code>this</code> context is set to the tooltip instance.</p>
           </td>
         </tr>
+        <tr>
+          <td>sanitize</td>
+          <td>boolean</td>
+          <td>true</td>
+          <td>Enable or disable the sanitization. If activated <code>'template'</code>, <code>'content'</code> and <code>'title'</code> options will be sanitized.</td>
+        </tr>
+        <tr>
+          <td>whiteList</td>
+          <td>object</td>
+          <td><a href="#js-sanitizer">Default value</a></td>
+          <td>Object which contains allowed attributes and tags</td>
+        </tr>
+        <tr>
+          <td>sanitizeFn</td>
+          <td>null | function</td>
+          <td>null</td>
+          <td>Here you can supply your own sanitize function. This can be useful if you prefer to use a dedicated library to perform sanitization.</td>
+        </tr>
       </tbody>
     </table>
   </div><!-- /.table-responsive -->

diff --git a/docs/_includes/nav/javascript.html b/docs/_includes/nav/javascript.html
index f8d314faa596e44da4e7201b1345d3b4b5494f6a..6cfc90abfb5f723ea740effa83717ee6edd5358e 100644 (file)
--- a/docs/_includes/nav/javascript.html
+++ b/docs/_includes/nav/javascript.html
@@ -6,6 +6,7 @@
     <li><a href="#js-programmatic-api">Programmatic API</a></li>
     <li><a href="#js-noconflict">No conflict</a></li>
     <li><a href="#js-events">Events</a></li>
+    <li><a href="#js-sanitizer">Sanitizer</a></li>
     <li><a href="#js-version-nums">Version numbers</a></li>
     <li><a href="#js-disabled">When JavaScript is disabled</a></li>
     <li><a href="#callout-third-party-libs">Third-party libraries</a></li>