Popover popover.js

Notices

Overview

Important notes about using the popover widget:

• 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 white-space: nowrap; on your <a>s to avoid this behavior.

Examples

Default Toggle Example

<button type="button" class="btn btn-info" data-cfw="popover" title="Click Popover Example" data-cfw-popover-content="Click the trigger or close button to close me." data-cfw-popover-placement="forward">Click to toggle popover</button>

Four Directions

Four options are available: top, forward( right), bottom, and reverse (left) aligned.

Heads up! When using the right-to-left, rtl, variant of Figuration all horizontal directions will be reversed. Meaning left becomes right, and vice-versa.

<button type="button" class="btn" data-cfw="popover" data-cfw-popover-container="body" data-cfw-popover-placement="top" data-cfw-popover-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
  Popover on top
</button>

<button type="button" class="btn" data-cfw="popover" data-cfw-popover-container="body" data-cfw-popover-placement="forward" data-cfw-popover-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
  Forward popover
</button>

<button type="button" class="btn" data-cfw="popover" data-cfw-popover-container="body" data-cfw-popover-placement="bottom" data-cfw-popover-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
  Popover on bottom
</button>

<button type="button" class="btn" data-cfw="popover" data-cfw-popover-container="body" data-cfw-popover-placement="reverse" data-cfw-popover-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
  Reverse popover
</button>

Hover Example

<button type="button" class="btn btn-info" id="cf-example-hover-popover" data-cfw="popover" title="Hover Popover Example" data-cfw-popover-content="Stop hovering over the trigger or the popover to auto-close." data-cfw-popover-placement="forward" data-cfw-popover-trigger="hover focus">Hover/focus to show popover</button>

Dismissable Example

Use the focus trigger to dismiss popovers on the user's next click of a different element than the toggle element.

<button type="button" class="btn btn-info" data-cfw="popover" title="Dismissable Popover example" data-cfw-popover-content="Click on an element other than the trigger or popover to close." data-cfw-popover-trigger="focus">Dismissable popover</button>

Draggable Example

Allow users to move popovers around the screen by enabling the drag option. Drag support mouse, keyboard (with arrow keys), and touch movement.

<button type="button" class="btn btn-info" data-cfw="popover" title="Draggable Popover Example" data-cfw-popover-content="Click the trigger or close link to close me." data-cfw-popover-placement="forward" data-cfw-popover-drag="true">Draggable popover</button>

Popover with HTML

<button type="button" class="btn btn-info" data-cfw="popover" data-cfw-popover-html="true" data-cfw-popover-placement="forward" data-cfw-popover-content="<em>Popover</em> <u>with</u> <b>HTML</b>" title="<em>Popover</em> <u>with</u> <b>HTML</b>">Popover with HTML</button>

If using more complex HTML, using a data attribute might not be optimal. A better option would be to use the Javascript options, or with a pre-generated popover, as shown in the following example.

<button type="button" class="btn btn-info" id="html-popover">Popover with HTML</button>

<script>
$('#html-popover').CFW_Popover({
  html: true,
  title: '<em>Popover</em> <u>with</u> <b>HTML</b>',
  content: '<span aria-hidden="true">&middot;</span> <em>Popover</em> <u>with</u> <b>HTML</b>'
});
</script>

Pre-generated Popover

Have complex content that you would like to show in a popover, or one that is updated dynamically? Create the popover and then link to it with the target option.

Show Popover

Popover title

Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum.

<button type="button" class="btn btn-info" data-cfw="popover" data-cfw-popover-target="#popoverExample0" data-cfw-popover-placement="forward">Show Popover</button>

<div class="popover" id="popoverExample0">
  <h3 class="popover-header">Popover title</h3>
  <div class="popover-body">
    <p>Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum.</p>
    <figure class="figure">
      <img src="/assets/4.4/img/test.gif" class="figure-img img-fluid" alt="Sample image">
      <figcaption class="figure-caption">Sample image caption.</figcaption>
    </figure>
  </div>
  <div class="popover-arrow"></div>
</div>

Custom Placement

Locate a popover anywhere you need with the placement option.

<button type="button" class="btn btn-info" id="cf-example-placed-popover" title="Custom placed popover" data-cfw-popover-content="Look, I am way over here!">Custom Placement Popover</button>
<script>
  $('#cf-example-placed-popover').CFW_Popover({
    placement : function(tip, trigger) {
      var $trigger = $(trigger);
      var loc = {};
      var pos = $trigger.offset();
      loc.top = pos.top;
      loc.left = pos.left + $trigger.parent().width() - $trigger.outerWidth();
      return loc;
    }
  });
</script>

Custom Container

When you have some styles on a parent element that interfere with a popover, you may want to specify a custom container so that the popover's HTML appears within that element instead. This is common in elements with overflow styles, or dimensions smaller than the popover, such as responsive tables or input groups.

$('#example-popover').CFW_Popover({
  container: 'body'
});

Another situation where you will want to set an explicit custom container are popovers inside a modal dialog, to make sure that the popover itself is appended to the modal. This is particularly important for popovers that contain interactive elements – modal dialogs will trap focus, so unless the popover is a child element of the modal, users won't be able to focus or activate these interactive elements.

$('#example-popover').CFW_Popover({
  container: '#example-modal .modal-body'
});

Viewport Constrainment

Keep popovers in their place with the viewport option.

<div class="container-viewport" id="viewport-popover">
  <p class="viewport-text">Viewport constraints for popovers.</p>
  <button type="button" class="btn btn-info popover-viewport-bottom" title="This should be shifted to the right">Shift Right</button>
  <button type="button" class="btn btn-info popover-viewport-right" title="This should be shifted down">Shift Down</button>
  <button type="button" class="btn btn-info float-end popover-viewport-bottom" title="This should be shifted to the left">Shift Left</button>
  <button type="button" class="btn btn-info popover-viewport-right btn-bottom" title="This should be shifted up">Shift Up</button>
  <button type="button" class="btn btn-info popover-viewport-drag btn-drag" title="This should be confined to the viewport box">Drag Test (click)</button>
</div>
<script>
  $('.popover-viewport-right').CFW_Popover({
    placement: 'forward',
    viewport: '#viewport-popover',
    padding: 2
  });
  $('.popover-viewport-bottom').CFW_Popover({
    placement: 'bottom',
    viewport: '#viewport-popover',
    padding: 2
  });
  $('.popover-viewport-drag').CFW_Popover({
    drag: true,
    viewport: '#viewport-popover',
    padding: 2
  });
</script>

Fixed Draggable

Create a fixed position draggable popover by overriding the popperConfig options with a positionFixed: true setting.

<button class="btn popover-drag-fixed btn-secondary" title="This should be confined to the window">Fixed Drag</button>
<script>
$('.popover-drag-fixed').CFW_Popover({
  drag: true,
  popperConfig: {
    positionFixed: true
  }
});
</script>

If a fixed position draggable popover is constrained by a viewport, then it will not move when the container is scrolled, but will attempt to stay inside the viewport if the body is scrolled.

<div class="container-viewport container-viewport-scroll" id="viewport-popover-scroll">
  <p class="viewport-text">Test viewport constraints for popovers.</p>
  <button class="btn popover-viewport-drag-fixed-scroll btn-drag" title="This should be confined to the viewport box">Fixed Drag</button>
</div>
<script>
$('.popover-viewport-drag-fixed-scroll').CFW_Popover({
  placement: 'reverse',
  drag: true,
  viewport: '#viewport-popover-scroll',
  popperConfig: {
    positionFixed: true
  }
});
</script>

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>, ideally made keyboard-focusable using tabindex="0".

For disabled popover triggers, you may also prefer data-cfw-popover-trigger="hover focus" so that the popover appears as immediate visual feedback to your users as they may not expect to click on a disabled element.

<span class="d-inline-block" tabindex="0" data-cfw="popover" data-cfw-popover-trigger="hover focus" data-cfw-popover-content="Popover for disabled item">
  <button class="btn btn-primary" type="button" disabled>Disabled button</button>
</span>

Usage

The popover widget, by default, generates content and markup on demand, and by default places popovers after their trigger element.

Via Data Attributes

Toggle

The required markup for a popover is only a data-cfw="popover" attribute and title or a data-cfw-popover-content="" on the HTML element you wish to have a popover. The generated markup of a popover is rather simple, though it does require a position (by default, set to top by the widget).

If the popover item is already created, you can link to it using data-cfw-popover-target="#somePopover", or href="#somePopover". The proper role and aria- attributes will be automatically created to link the trigger and target elements.

Dismiss

Dismissal can be achieved with data-cfw-dismiss attributes on a button within the popover as demonstrated below:

<button type="button" class="close" data-cfw-dismiss="popover" aria-label="Close"><span aria-hidden="true">&times;</span></button>

or on a button outside the popover using the additional data-cfw-popover-target as demonstrated below:

<button type="button" class="close" data-cfw-dismiss="popover" data-cfw-popover-target="#myPopover">Close popover</button>

Via JavaScript

Enable manually with:

$('#myPopover').CFW_Popover();

Close Triggers

Any element with a data attribute of data-cfw-dismiss="popover" within the popover element will act as a close trigger for the popover. There can be multiple close triggers, such as a header/titlebar close and a cancel button in the footer.

Draggable Popovers

The added functionality from the Drag widget allows for touch and mouse dragging to be available.

The drag event handlers will auto-enable when a data-cfw-drag="popover" trigger item is found within the popover item. The drag option will insert a drag trigger into the popover element, resulting in invoking the drag handlers.

Draggable popovers will force the following settings:

• container: 'body'
• trigger: 'click'

Options

Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-cfw-popover, as in data-cfw-popover-placement="forward".

function myPopoverAlign(tip, trigger) {
// this - popover data-api
// tip -> popover target
// trigger -> popover trigger
}

$('#myPopover').CFW_Popover({
  placement: 'forward'
});

Methods

Method calls can be made on either the trigger or the target <div class="popover"> element.

$('#myPopover').CFW_Popover('show');

Events

Event callbacks happen on the toggle/trigger element.

$('#myPopover').on('afterHide.cfw.popover', function() {
  // do something...
});

Server-side Apps

Popovers are designed to hopefully work with server side applications, such as Apache Wicket, and other instances where the server-side application might need to create or update the popover content after the initial page load.

A quick example:

1. An item with an event handler that makes a callback to create a new popover is interacted with.
2. Call as needed:
   
   • $('#myPopover').CFW_Popover('hide');
   • or $('#myPopover').CFW_Popover('unlink');
   • or $('#myPopover').CFW_Popover('dispose');
3. Update/create the popover object and insert into DOM.
4. Initialize the popover: $('#myPopover').CFW_Popover(options); with desired options.
5. Show popover: $('#myPopover').CFW_Popover('show');

Accessibility

Consider Keyboard and Assistive Technology Users

You should only add popovers to HTML elements that are traditionally keyboard-focusable and interactive (such as links or form controls). Although arbitrary HTML elements (such as <span>s) can be made focusable by adding the tabindex="0" attribute, this will add potentially annoying and confusing tab stops on non-interactive elements for keyboard users. In addition, most assistive technologies currently do not announce the tooltip in this situation. Additionally, do not rely solely on hover as the trigger for your popovers as this will make them impossible to trigger for keyboard users.

Avoid adding an excessive amount of content in popovers with the html option. Once popovers are displayed, their content is tied to the trigger element with the aria-describedby attribute, causing all of the popover’s content to be announced to assistive technology users as one long, uninterrupted stream.

Key Commands

The following key commands are handled when focus is inside the popover, or on the popover trigger:

• Esc - Close the popover

Focus Handling

Popovers have additional focus handling when using keyboard navigation.

If navigating from above the popover's trigger (typically with the Tab key), the trigger becomes focused, the next forward focus will move from the trigger to the first focusable item inside the popover.

If navigating from below the popover's trigger (typically with the Shift + Tab key combination), when the trigger is focused, focus will be moved from the trigger to the last focusable item inside the popover.

When navigating forward, out the bottom of the popover, the focus will be moved to the next focusable item in the document relative to the trigger. This is done so that if the container option is used, the focus will move to next logical item. Otherwise, when using container: body, the focus will potentially drop off the end of the HTML document, leaving a keyboard user in an akward situation.

When navigating backward, out the top of the popover, the focus will be moved to the trigger.

This will not necessarily work with some assistive technologies reading modes.

SASS Reference

Variables

The available Customization options, or Sass variables, that can be customized for the popover component.

Mixins

No mixins available.