Skip to content

Commit d821de2

Browse files
XhmikosRXhmikosR
committed
Backport sanitize docs from v4.
1 parent 5cd9ef4 commit d821de2

File tree

4 files changed

+123
-1
lines changed

4 files changed

+123
-1
lines changed

‎docs/_includes/js/overview.html

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,81 @@ <h2 id="js-events">Events</h2>
7070
})
7171
{% endhighlight %}
7272

73+
<h2 id="js-sanitizer">Sanitizer</h2>
74+
75+
<p>Tooltips and Popovers use our built-in sanitizer to sanitize options which accept HTML.</p>
76+
<p>The default <code>whiteList</code> value is the following:</p>
77+
78+
{% highlight js %}
79+
var ARIA_ATTRIBUTE_PATTERN = /^aria-[\w-]*$/i
80+
var DefaultWhitelist = {
81+
// Global attributes allowed on any supplied element below.
82+
'*': ['class', 'dir', 'id', 'lang', 'role', ARIA_ATTRIBUTE_PATTERN],
83+
a: ['target', 'href', 'title', 'rel'],
84+
area: [],
85+
b: [],
86+
br: [],
87+
col: [],
88+
code: [],
89+
div: [],
90+
em: [],
91+
hr: [],
92+
h1: [],
93+
h2: [],
94+
h3: [],
95+
h4: [],
96+
h5: [],
97+
h6: [],
98+
i: [],
99+
img: ['src', 'alt', 'title', 'width', 'height'],
100+
li: [],
101+
ol: [],
102+
p: [],
103+
pre: [],
104+
s: [],
105+
small: [],
106+
span: [],
107+
sub: [],
108+
sup: [],
109+
strong: [],
110+
u: [],
111+
ul: []
112+
}
113+
{% endhighlight %}
114+
115+
<p>If you want to add new values to this default <code>whiteList</code> you can do the following:</p>
116+
117+
{% highlight js %}
118+
var myDefaultWhiteList = $.fn.tooltip.Constructor.DEFAULTS.whiteList
119+
120+
// To allow table elements
121+
myDefaultWhiteList.table = []
122+
123+
// To allow td elements and data-option attributes on td elements
124+
myDefaultWhiteList.td = ['data-option']
125+
126+
// You can push your custom regex to validate your attributes.
127+
// Be careful about your regular expressions being too lax
128+
var myCustomRegex = /^data-my-app-[\w-]+/
129+
myDefaultWhiteList['*'].push(myCustomRegex)
130+
{% endhighlight %}
131+
132+
<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>
133+
134+
{% highlight js %}
135+
$('#yourTooltip').tooltip({
136+
sanitizeFn: function (content) {
137+
return DOMPurify.sanitize(content)
138+
}
139+
})
140+
{% endhighlight %}
141+
142+
<div class="bs-callout bs-callout-danger" id="callout-sanitizer-no-createhtmldocument">
143+
<h4>Browsers without <code>document.implementation.createHTMLDocument</code></h4>
144+
<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>
145+
<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>
146+
</div>
147+
73148
<h2 id="js-version-nums">Version numbers</h2>
74149
<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>
75150
{% highlight js %}

‎docs/_includes/js/popovers.html

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -139,6 +139,11 @@ <h2 id="popovers-usage">Usage</h2>
139139

140140
<h3 id="popovers-options">Options</h3>
141141
<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>
142+
143+
<div class="bs-callout bs-callout-warning" id="callout-popover-disabled-options">
144+
<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>
145+
</div>
146+
142147
<div class="table-responsive">
143148
<table class="table table-bordered table-striped js-options-table js-options-table">
144149
<thead>
@@ -239,7 +244,25 @@ <h3 id="popovers-options">Options</h3>
239244
<p>Keeps the popover within the bounds of this element. Example: <code>viewport: '#viewport'</code> or <code>{ "selector": "#viewport", "padding": 0 }</code></p>
240245
<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>
241246
</td>
242-
</tr>
247+
</tr>
248+
<tr>
249+
<td>sanitize</td>
250+
<td>boolean</td>
251+
<td>true</td>
252+
<td>Enable or disable the sanitization. If activated <code>'template'</code>, <code>'content'</code> and <code>'title'</code> options will be sanitized.</td>
253+
</tr>
254+
<tr>
255+
<td>whiteList</td>
256+
<td>object</td>
257+
<td><a href="#js-sanitizer">Default value</a></td>
258+
<td>Object which contains allowed attributes and tags</td>
259+
</tr>
260+
<tr>
261+
<td>sanitizeFn</td>
262+
<td>null | function</td>
263+
<td>null</td>
264+
<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>
265+
</tr>
243266
</tbody>
244267
</table>
245268
</div><!-- /.table-responsive -->

‎docs/_includes/js/tooltips.html

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -115,6 +115,11 @@ <h4>Tooltips on disabled elements require wrapper elements</h4>
115115

116116
<h3 id="tooltips-options">Options</h3>
117117
<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>
118+
119+
<div class="bs-callout bs-callout-warning" id="callout-tooltip-disabled-options">
120+
<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>
121+
</div>
122+
118123
<div class="table-responsive">
119124
<table class="table table-bordered table-striped js-options-table">
120125
<thead>
@@ -206,6 +211,24 @@ <h3 id="tooltips-options">Options</h3>
206211
<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>
207212
</td>
208213
</tr>
214+
<tr>
215+
<td>sanitize</td>
216+
<td>boolean</td>
217+
<td>true</td>
218+
<td>Enable or disable the sanitization. If activated <code>'template'</code>, <code>'content'</code> and <code>'title'</code> options will be sanitized.</td>
219+
</tr>
220+
<tr>
221+
<td>whiteList</td>
222+
<td>object</td>
223+
<td><a href="#js-sanitizer">Default value</a></td>
224+
<td>Object which contains allowed attributes and tags</td>
225+
</tr>
226+
<tr>
227+
<td>sanitizeFn</td>
228+
<td>null | function</td>
229+
<td>null</td>
230+
<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>
231+
</tr>
209232
</tbody>
210233
</table>
211234
</div><!-- /.table-responsive -->

‎docs/_includes/nav/javascript.html

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
<li><a href="#js-programmatic-api">Programmatic API</a></li>
77
<li><a href="#js-noconflict">No conflict</a></li>
88
<li><a href="#js-events">Events</a></li>
9+
<li><a href="#js-sanitizer">Sanitizer</a></li>
910
<li><a href="#js-version-nums">Version numbers</a></li>
1011
<li><a href="#js-disabled">When JavaScript is disabled</a></li>
1112
<li><a href="#callout-third-party-libs">Third-party libraries</a></li>

0 commit comments

Comments
 (0)