diff options
Diffstat (limited to 'site/docs/4.3/components/popovers.md')
| -rw-r--r-- | site/docs/4.3/components/popovers.md | 379 |
1 files changed, 0 insertions, 379 deletions
diff --git a/site/docs/4.3/components/popovers.md b/site/docs/4.3/components/popovers.md deleted file mode 100644 index b3a3a39b17..0000000000 --- a/site/docs/4.3/components/popovers.md +++ /dev/null @@ -1,379 +0,0 @@ ---- -layout: docs -title: Popovers -description: Documentation and examples for adding Bootstrap popovers, like those found in iOS, to any element on your site. -group: components -toc: true ---- - -## Overview - -Things to know when using the popover plugin: - -- Popovers rely on the 3rd party library [Popper.js](https://popper.js.org/) for positioning. You must include [popper.min.js]({{ site.cdn.popper }}) before bootstrap.js or use `bootstrap.bundle.min.js` / `bootstrap.bundle.js` which contains Popper.js in order for popovers to work! -- Popovers require the [tooltip plugin]({{ site.baseurl }}/docs/{{ site.docs_version }}/components/tooltips/) as a dependency. -- If you're building our JavaScript from source, it [requires `util.js`]({{ site.baseurl }}/docs/{{ site.docs_version }}/getting-started/javascript/#util). -- Popovers are opt-in for performance reasons, so **you must initialize them yourself**. -- Zero-length `title` and `content` values will never show a popover. -- Specify `container: 'body'` to avoid rendering problems in more complex components (like our input groups, button groups, etc). -- Triggering popovers on hidden elements will not work. -- Popovers for `.disabled` or `disabled` elements must be triggered on a wrapper element. -- When triggered from anchors that wrap across multiple lines, popovers will be centered between the anchors' overall width. Use `.text-nowrap` on your `<a>`s to avoid this behavior. -- Popovers must be hidden before their corresponding elements have been removed from the DOM. -- Popovers can be triggered thanks to an element inside a shadow DOM. - -{% include callout-info-prefersreducedmotion.md %} - -Keep reading to see how popovers work with some examples. - -## Example: Enable popovers everywhere - -One way to initialize all popovers on a page would be to select them by their `data-toggle` attribute: - -{% highlight js %} -$(function () { - $('[data-toggle="popover"]').popover() -}) -{% endhighlight %} - -## Example: Using the `container` option - -When you have some styles on a parent element that interfere with a popover, you'll want to specify a custom `container` so that the popover's HTML appears within that element instead. - -{% highlight js %} -$(function () { - $('.example-popover').popover({ - container: 'body' - }) -}) -{% endhighlight %} - -## Example - -{% capture example %} -<button type="button" class="btn btn-lg btn-danger" data-toggle="popover" title="Popover title" data-content="And here's some amazing content. It's very engaging. Right?">Click to toggle popover</button> -{% endcapture %} -{% include example.html content=example %} - -### Four directions - -Four options are available: top, right, bottom, and left aligned. - -<div class="bd-example popover-demo"> - <div class="bd-example-popovers"> - <button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="top" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus."> - Popover on top - </button> - <button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="right" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus."> - Popover on right - </button> - <button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="bottom" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus."> - Popover on bottom - </button> - <button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="left" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus."> - Popover on left - </button> - </div> -</div> - -{% highlight html %} -<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="top" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus."> - Popover on top -</button> - -<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="right" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus."> - Popover on right -</button> - -<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="bottom" data-content="Vivamus -sagittis lacus vel augue laoreet rutrum faucibus."> - Popover on bottom -</button> - -<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="left" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus."> - Popover on left -</button> -{% endhighlight %} - -### Dismiss on next click - -Use the `focus` trigger to dismiss popovers on the user's next click of a different element than the toggle element. - -{% capture callout %} -#### Specific markup required for dismiss-on-next-click - -For proper cross-browser and cross-platform behavior, you must use the `<a>` tag, _not_ the `<button>` tag, and you also must include a [`tabindex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex) attribute. -{% endcapture %} -{% include callout.html content=callout type="danger" %} - -{% capture example %} -<a tabindex="0" class="btn btn-lg btn-danger" role="button" data-toggle="popover" data-trigger="focus" title="Dismissible popover" data-content="And here's some amazing content. It's very engaging. Right?">Dismissible popover</a> -{% endcapture %} -{% include example.html content=example %} - -{% highlight js %} -$('.popover-dismiss').popover({ - trigger: 'focus' -}) -{% endhighlight %} - -### Disabled elements - -Elements with the `disabled` attribute aren't interactive, meaning users cannot hover or click them to trigger a popover (or tooltip). As a workaround, you'll want to trigger the popover from a wrapper `<div>` or `<span>` and override the `pointer-events` on the disabled element. - -For disabled popover triggers, you may also prefer `data-trigger="hover"` so that the popover appears as immediate visual feedback to your users as they may not expect to _click_ on a disabled element. - -{% capture example %} -<span class="d-inline-block" data-toggle="popover" data-content="Disabled popover"> - <button class="btn btn-primary" style="pointer-events: none;" type="button" disabled>Disabled button</button> -</span> -{% endcapture %} -{% include example.html content=example %} - -## Usage - -Enable popovers via JavaScript: - -{% highlight js %}$('#example').popover(options){% endhighlight %} - -### Options - -Options can be passed via data attributes or JavaScript. For data attributes, append the option name to `data-`, as in `data-animation=""`. - -{% capture callout %} -Note that for security reasons the `sanitize`, `sanitizeFn` and `whiteList` options cannot be supplied using data attributes. -{% endcapture %} -{% include callout.html content=callout type="warning" %} - -<table class="table table-bordered table-striped"> - <thead> - <tr> - <th style="width: 100px;">Name</th> - <th style="width: 100px;">Type</th> - <th style="width: 50px;">Default</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td>animation</td> - <td>boolean</td> - <td>true</td> - <td>Apply a CSS fade transition to the popover</td> - </tr> - <tr> - <td>container</td> - <td>string | element | false</td> - <td>false</td> - <td> - <p>Appends the popover to a specific element. Example: <code>container: 'body'</code>. This option is particularly useful in that it allows you to position the popover in the flow of the document near the triggering element - which will prevent the popover from floating away from the triggering element during a window resize.</p> - </td> - </tr> - <tr> - <td>content</td> - <td>string | element | function</td> - <td>''</td> - <td> - <p>Default content value if <code>data-content</code> attribute isn't present.</p> - <p>If a function is given, it will be called with its <code>this</code> reference set to the element that the popover is attached to.</p> - </td> - </tr> - <tr> - <td>delay</td> - <td>number | object</td> - <td>0</td> - <td> - <p>Delay showing and hiding the popover (ms) - does not apply to manual trigger type</p> - <p>If a number is supplied, delay is applied to both hide/show</p> - <p>Object structure is: <code>delay: { "show": 500, "hide": 100 }</code></p> - </td> - </tr> - <tr> - <td>html</td> - <td>boolean</td> - <td>false</td> - <td>Insert HTML into the popover. If false, <code>innerText</code> property will be used to insert content into the DOM. Use text if you're worried about XSS attacks.</td> - </tr> - <tr> - <td>placement</td> - <td>string | function</td> - <td>'right'</td> - <td> - <p>How to position the popover - auto | top | bottom | left | right.<br>When <code>auto</code> is specified, it will dynamically reorient the popover.</p> - <p>When a function is used to determine the placement, it is called with the popover DOM node as its first argument and the triggering element DOM node as its second. The <code>this</code> context is set to the popover instance.</p> - </td> - </tr> - <tr> - <td>selector</td> - <td>string | false</td> - <td>false</td> - <td>If a selector is provided, popover objects will be delegated to the specified targets. In practice, this is used to enable dynamic HTML content to have popovers added. See <a href="{{ site.repo }}/issues/4215">this</a> and <a href="https://codepen.io/Johann-S/pen/djJYPb">an informative example</a>.</td> - </tr> - <tr> - <td>template</td> - <td>string</td> - <td><code>'<div class="popover" role="tooltip"><div class="popover-arrow"></div><h3 class="popover-header"></h3><div class="popover-body"></div></div>'</code></td> - <td> - <p>Base HTML to use when creating the popover.</p> - <p>The popover's <code>title</code> will be injected into the <code>.popover-header</code>.</p> - <p>The popover's <code>content</code> will be injected into the <code>.popover-body</code>.</p> - <p><code>.popover-arrow</code> will become the popover's arrow.</p> - <p>The outermost wrapper element should have the <code>.popover</code> class.</p> - </td> - </tr> - <tr> - <td>title</td> - <td>string | element | function</td> - <td>''</td> - <td> - <p>Default title value if <code>title</code> attribute isn't present.</p> - <p>If a function is given, it will be called with its <code>this</code> reference set to the element that the popover is attached to.</p> - </td> - </tr> - <tr> - <td>trigger</td> - <td>string</td> - <td>'click'</td> - <td>How popover is triggered - click | hover | focus | manual. You may pass multiple triggers; separate them with a space. <code>manual</code> cannot be combined with any other trigger.</td> - </tr> - <tr> - <td>offset</td> - <td>number | string</td> - <td>0</td> - <td>Offset of the popover relative to its target. For more information refer to Popper.js's <a href="https://popper.js.org/popper-documentation.html#modifiers..offset.offset">offset docs</a>.</td> - </tr> - <tr> - <td>fallbackPlacement</td> - <td>string | array</td> - <td>'flip'</td> - <td>Allow to specify which position Popper will use on fallback. For more information refer to - Popper.js's <a href="https://popper.js.org/popper-documentation.html#modifiers..flip.behavior">behavior docs</a></td> - </tr> - <tr> - <td>boundary</td> - <td>string | element</td> - <td>'scrollParent'</td> - <td>Overflow constraint boundary of the popover. Accepts the values of <code>'viewport'</code>, <code>'window'</code>, <code>'scrollParent'</code>, or an HTMLElement reference (JavaScript only). For more information refer to Popper.js's <a href="https://popper.js.org/popper-documentation.html#modifiers..preventOverflow.boundariesElement">preventOverflow docs</a>.</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="{{ site.baseurl }}/docs/{{ site.docs_version }}/getting-started/javascript/#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> - -{% capture callout %} -#### Data attributes for individual popovers - -Options for individual popovers can alternatively be specified through the use of data attributes, as explained above. -{% endcapture %} -{% include callout.html content=callout type="info" %} - -### Methods - -{% include callout-danger-async-methods.md %} - -#### `$().popover(options)` - -Initializes popovers for an element collection. - -#### `.popover('show')` - -Reveals an element's popover. **Returns to the caller before the popover has actually been shown** (i.e. before the `shown.bs.popover` event occurs). This is considered a "manual" triggering of the popover. Popovers whose both title and content are zero-length are never displayed. - -{% highlight js %}$('#element').popover('show'){% endhighlight %} - -#### `.popover('hide')` - -Hides an element's popover. **Returns to the caller before the popover has actually been hidden** (i.e. before the `hidden.bs.popover` event occurs). This is considered a "manual" triggering of the popover. - -{% highlight js %}$('#element').popover('hide'){% endhighlight %} - -#### `.popover('toggle')` - -Toggles an element's popover. **Returns to the caller before the popover has actually been shown or hidden** (i.e. before the `shown.bs.popover` or `hidden.bs.popover` event occurs). This is considered a "manual" triggering of the popover. - -{% highlight js %}$('#element').popover('toggle'){% endhighlight %} - -#### `.popover('dispose')` - -Hides and destroys an element's popover. Popovers that use delegation (which are created using [the `selector` option](#options)) cannot be individually destroyed on descendant trigger elements. - -{% highlight js %}$('#element').popover('dispose'){% endhighlight %} - -#### `.popover('enable')` - -Gives an element's popover the ability to be shown. **Popovers are enabled by default.** - -{% highlight js %}$('#element').popover('enable'){% endhighlight %} - -#### `.popover('disable')` - -Removes the ability for an element's popover to be shown. The popover will only be able to be shown if it is re-enabled. - -{% highlight js %}$('#element').popover('disable'){% endhighlight %} - -#### `.popover('toggleEnabled')` - -Toggles the ability for an element's popover to be shown or hidden. - -{% highlight js %}$('#element').popover('toggleEnabled'){% endhighlight %} - -#### `.popover('update')` - -Updates the position of an element's popover. - -{% highlight js %}$('#element').popover('update'){% endhighlight %} - -### Events - -<table class="table table-bordered table-striped"> - <thead> - <tr> - <th style="width: 150px;">Event Type</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td>show.bs.popover</td> - <td>This event fires immediately when the <code>show</code> instance method is called.</td> - </tr> - <tr> - <td>shown.bs.popover</td> - <td>This event is fired when the popover has been made visible to the user (will wait for CSS transitions to complete).</td> - </tr> - <tr> - <td>hide.bs.popover</td> - <td>This event is fired immediately when the <code>hide</code> instance method has been called.</td> - </tr> - <tr> - <td>hidden.bs.popover</td> - <td>This event is fired when the popover has finished being hidden from the user (will wait for CSS transitions to complete).</td> - </tr> - <tr> - <td>inserted.bs.popover</td> - <td>This event is fired after the <code>show.bs.popover</code> event when the popover template has been added to the DOM.</td> - </tr> - </tbody> -</table> - -{% highlight js %} -$('#myPopover').on('hidden.bs.popover', function () { - // do something... -}) -{% endhighlight %} |