0
0
mirror of https://github.com/twbs/bootstrap.git synced 2024-12-04 16:24:22 +01:00

Backport sanitize docs from v4.

This commit is contained in:
XhmikosR 2019-02-12 18:18:31 +02:00
parent 5cd9ef47f6
commit d821de2712
4 changed files with 123 additions and 1 deletions

View File

@ -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 %}

View File

@ -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>
@ -240,6 +245,24 @@ sagittis lacus vel augue laoreet rutrum faucibus.">
<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>
<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 -->

View File

@ -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 -->

View File

@ -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>