Popover popover.js

A more robust version of a tooltip, that allows for larger pieces of content or interactive functionality.

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

Static Popover

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.

Four Directions

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

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>

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>

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 a 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/3.0/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>

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>

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-cfw-popover-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.

<span class="d-inline-block" data-cfw="popover" data-cfw-popover-content="Popover for disabled item">
  <button class="btn btn-primary" style="pointer-events: none;" 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

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.

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
}

Methods

.CFW_Popover(options)

Activates a popover on a given element. Accepts an optional options object.

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

.CFW_Popover('toggle')

Toggles a popover item to be shown or hidden.

.CFW_Popover('show')

Shows an element's popover.

.CFW_Popover('hide')

Hides an element's popover.

.CFW_Popover('unlink')

Hides the popover, removes events and attributes from both trigger and popover.

.CFW_Popover('dispose')

Calls the unlink method, and then removes the popover from the DOM.

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

Key Commands

The following key commands are handled when focus is inside the popover:

• 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.