Add v3.4.1 docs.

2026-05-21 13:24:08 +03:00 · 2019-02-13 16:53:27 +02:00
parent 3c5ce6447b
commit 60bbc5a184
34 changed files with 430 additions and 142 deletions
@@ -97,13 +97,13 @@
      <ul class="nav navbar-nav navbar-right">
        <li class="dropdown">
          <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">
-            v3.4.0 <span class="caret"></span>
+            v3.4.1 <span class="caret"></span>
          </a>
          <ul class="dropdown-menu">
            <li><a href="https://getbootstrap.com/">Latest (4.x)</a></li>
            <li><a href="https://v4-alpha.getbootstrap.com/">v4 Alpha 6</a></li>
            <li class="divider"></li>
-            <li class="active"><a href="https://getbootstrap.com/docs/3.4/">v3.4.0</a></li>
+            <li class="active"><a href="https://getbootstrap.com/docs/3.4/">v3.4.1</a></li>
            <li><a href="https://getbootstrap.com/docs/3.3/">v3.3.7</a></li>
            <li><a href="https://getbootstrap.com/2.3.2/">v2.3.2</a></li>
          </ul>
@@ -188,9 +188,78 @@
  <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="nx">data</span><span class="p">)</span> <span class="k">return</span> <span class="nx">e</span><span class="p">.</span><span class="nx">preventDefault</span><span class="p">()</span> <span class="c1">// stops modal from being shown</span>
 <span class="p">})</span></code></pre></figure>

+  <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>
+
+<figure class="highlight"><pre><code class="language-js" data-lang="js"><span class="kd">var</span> <span class="nx">ARIA_ATTRIBUTE_PATTERN</span> <span class="o">=</span> <span class="sr">/^aria-</span><span class="se">[\w</span><span class="sr">-</span><span class="se">]</span><span class="sr">*$/i</span>
+<span class="kd">var</span> <span class="nx">DefaultWhitelist</span> <span class="o">=</span> <span class="p">{</span>
+  <span class="c1">// Global attributes allowed on any supplied element below.</span>
+  <span class="s1">'*'</span><span class="p">:</span> <span class="p">[</span><span class="s1">'class'</span><span class="p">,</span> <span class="s1">'dir'</span><span class="p">,</span> <span class="s1">'id'</span><span class="p">,</span> <span class="s1">'lang'</span><span class="p">,</span> <span class="s1">'role'</span><span class="p">,</span> <span class="nx">ARIA_ATTRIBUTE_PATTERN</span><span class="p">],</span>
+  <span class="na">a</span><span class="p">:</span> <span class="p">[</span><span class="s1">'target'</span><span class="p">,</span> <span class="s1">'href'</span><span class="p">,</span> <span class="s1">'title'</span><span class="p">,</span> <span class="s1">'rel'</span><span class="p">],</span>
+  <span class="na">area</span><span class="p">:</span> <span class="p">[],</span>
+  <span class="na">b</span><span class="p">:</span> <span class="p">[],</span>
+  <span class="na">br</span><span class="p">:</span> <span class="p">[],</span>
+  <span class="na">col</span><span class="p">:</span> <span class="p">[],</span>
+  <span class="na">code</span><span class="p">:</span> <span class="p">[],</span>
+  <span class="na">div</span><span class="p">:</span> <span class="p">[],</span>
+  <span class="na">em</span><span class="p">:</span> <span class="p">[],</span>
+  <span class="na">hr</span><span class="p">:</span> <span class="p">[],</span>
+  <span class="na">h1</span><span class="p">:</span> <span class="p">[],</span>
+  <span class="na">h2</span><span class="p">:</span> <span class="p">[],</span>
+  <span class="na">h3</span><span class="p">:</span> <span class="p">[],</span>
+  <span class="na">h4</span><span class="p">:</span> <span class="p">[],</span>
+  <span class="na">h5</span><span class="p">:</span> <span class="p">[],</span>
+  <span class="na">h6</span><span class="p">:</span> <span class="p">[],</span>
+  <span class="na">i</span><span class="p">:</span> <span class="p">[],</span>
+  <span class="na">img</span><span class="p">:</span> <span class="p">[</span><span class="s1">'src'</span><span class="p">,</span> <span class="s1">'alt'</span><span class="p">,</span> <span class="s1">'title'</span><span class="p">,</span> <span class="s1">'width'</span><span class="p">,</span> <span class="s1">'height'</span><span class="p">],</span>
+  <span class="na">li</span><span class="p">:</span> <span class="p">[],</span>
+  <span class="na">ol</span><span class="p">:</span> <span class="p">[],</span>
+  <span class="na">p</span><span class="p">:</span> <span class="p">[],</span>
+  <span class="na">pre</span><span class="p">:</span> <span class="p">[],</span>
+  <span class="na">s</span><span class="p">:</span> <span class="p">[],</span>
+  <span class="na">small</span><span class="p">:</span> <span class="p">[],</span>
+  <span class="na">span</span><span class="p">:</span> <span class="p">[],</span>
+  <span class="na">sub</span><span class="p">:</span> <span class="p">[],</span>
+  <span class="na">sup</span><span class="p">:</span> <span class="p">[],</span>
+  <span class="na">strong</span><span class="p">:</span> <span class="p">[],</span>
+  <span class="na">u</span><span class="p">:</span> <span class="p">[],</span>
+  <span class="na">ul</span><span class="p">:</span> <span class="p">[]</span>
+<span class="p">}</span></code></pre></figure>
+
+  <p>If you want to add new values to this default <code>whiteList</code> you can do the following:</p>
+
+<figure class="highlight"><pre><code class="language-js" data-lang="js"><span class="kd">var</span> <span class="nx">myDefaultWhiteList</span> <span class="o">=</span> <span class="nx">$</span><span class="p">.</span><span class="nx">fn</span><span class="p">.</span><span class="nx">tooltip</span><span class="p">.</span><span class="nx">Constructor</span><span class="p">.</span><span class="nx">DEFAULTS</span><span class="p">.</span><span class="nx">whiteList</span>
+
+<span class="c1">// To allow table elements</span>
+<span class="nx">myDefaultWhiteList</span><span class="p">.</span><span class="nx">table</span> <span class="o">=</span> <span class="p">[]</span>
+
+<span class="c1">// To allow td elements and data-option attributes on td elements</span>
+<span class="nx">myDefaultWhiteList</span><span class="p">.</span><span class="nx">td</span> <span class="o">=</span> <span class="p">[</span><span class="s1">'data-option'</span><span class="p">]</span>
+
+<span class="c1">// You can push your custom regex to validate your attributes.</span>
+<span class="c1">// Be careful about your regular expressions being too lax</span>
+<span class="kd">var</span> <span class="nx">myCustomRegex</span> <span class="o">=</span> <span class="sr">/^data-my-app-</span><span class="se">[\w</span><span class="sr">-</span><span class="se">]</span><span class="sr">+/</span>
+<span class="nx">myDefaultWhiteList</span><span class="p">[</span><span class="s1">'*'</span><span class="p">].</span><span class="nx">push</span><span class="p">(</span><span class="nx">myCustomRegex</span><span class="p">)</span></code></pre></figure>
+
+  <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>
+
+<figure class="highlight"><pre><code class="language-js" data-lang="js"><span class="nx">$</span><span class="p">(</span><span class="s1">'#yourTooltip'</span><span class="p">).</span><span class="nx">tooltip</span><span class="p">({</span>
+  <span class="na">sanitizeFn</span><span class="p">:</span> <span class="kd">function</span> <span class="p">(</span><span class="nx">content</span><span class="p">)</span> <span class="p">{</span>
+    <span class="k">return</span> <span class="nx">DOMPurify</span><span class="p">.</span><span class="nx">sanitize</span><span class="p">(</span><span class="nx">content</span><span class="p">)</span>
+  <span class="p">}</span>
+<span class="p">})</span></code></pre></figure>
+
+  <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>
-<figure class="highlight"><pre><code class="language-js" data-lang="js"><span class="nx">$</span><span class="p">.</span><span class="nx">fn</span><span class="p">.</span><span class="nx">tooltip</span><span class="p">.</span><span class="nx">Constructor</span><span class="p">.</span><span class="nx">VERSION</span> <span class="c1">// =&gt; "3.4.0"</span></code></pre></figure>
+<figure class="highlight"><pre><code class="language-js" data-lang="js"><span class="nx">$</span><span class="p">.</span><span class="nx">fn</span><span class="p">.</span><span class="nx">tooltip</span><span class="p">.</span><span class="nx">Constructor</span><span class="p">.</span><span class="nx">VERSION</span> <span class="c1">// =&gt; "3.4.1"</span></code></pre></figure>

  <h2 id="js-disabled">No special fallbacks when JavaScript is disabled</h2>
  <p>Bootstrap's plugins don't fall back particularly gracefully when JavaScript is disabled. If you care about the user experience in this case, use <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/noscript"><code>&lt;noscript&gt;</code></a> to explain the situation (and how to re-enable JavaScript) to your users, and/or add your own custom fallbacks.</p>
@@ -1294,6 +1363,11 @@

  <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>
@@ -1385,6 +1459,24 @@
            <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 -->
@@ -1585,6 +1677,11 @@ sagittis lacus vel augue laoreet rutrum faucibus."</span><span class="nt">&gt;</

  <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>
@@ -1685,7 +1782,25 @@ sagittis lacus vel augue laoreet rutrum faucibus."</span><span class="nt">&gt;</
            <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 -->
@@ -2614,6 +2729,7 @@ sagittis lacus vel augue laoreet rutrum faucibus."</span><span class="nt">&gt;</
    <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>