Skip to content

Commit

Permalink
Backport sanitize docs from v4.
Browse files Browse the repository at this point in the history
  • Loading branch information
XhmikosR committed Feb 13, 2019
1 parent 5cd9ef4 commit d821de2
Show file tree
Hide file tree
Showing 4 changed files with 123 additions and 1 deletion.
75 changes: 75 additions & 0 deletions docs/_includes/js/overview.html
Original file line number Diff line number Diff line change
Expand Up @@ -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 %}
Expand Down
25 changes: 24 additions & 1 deletion docs/_includes/js/popovers.html
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down Expand Up @@ -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 -->
Expand Down
23 changes: 23 additions & 0 deletions docs/_includes/js/tooltips.html
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down Expand Up @@ -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 -->
Expand Down
1 change: 1 addition & 0 deletions docs/_includes/nav/javascript.html
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down

0 comments on commit d821de2

Please sign in to comment.