Backport sanitize docs from v4.

twbs · Feb 13, 2019 · d821de2 · d821de2
1 parent 5cd9ef4
commit d821de2
Show file tree

Hide file tree

Showing 4 changed files with 123 additions and 1 deletion.
diff --git a/docs/_includes/js/overview.html b/docs/_includes/js/overview.html
@@ -70,6 +70,81 @@ <h2 id="js-events">Events</h2>
 })
 {% 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
@@ -139,6 +139,11 @@ <h2 id="popovers-usage">Usage</h2>
 
   <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 @@ <h3 id="popovers-options">Options</h3>
             <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
@@ -115,6 +115,11 @@ <h4>Tooltips on disabled elements require wrapper elements</h4>
 
   <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 @@ <h3 id="tooltips-options">Options</h3>
             <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
@@ -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>