# Popover

## Overview

The popover plugin displays HTML in a container that overlays the page. It is triggered by clicking on a button or other UI element and the container is positioned near the element. The popover can be displayed and hidden at will.

## Usage

The plugin must be provided with an options object and a jQuery collection of elements.

```js
$('.my-button').popover(options);
```

Clicking `.my-button` will toggle display of the popover.

To open or close a popover programmatically, trigger a `click` event on the element:

```js
$('.my-button').click();
```

## Options

At minimum, the options must contain HTML to display:

```js
$('.my-button').popover({
    html: '<p>Hello world</p>'
});
```

For shorthand, if you only need to specify the HTML you can just pass a string:

```js
// Equivalent to the previous example
$('.my-button').popover('<p>Hello world</p>');
```

### Options

Property | Type | Description
--- | --- | ---
`html` | String | Contents to be displayed (required)
`badge` | Number | A value to be displayed in a badge superimposed over the toggle element. If the value is less than 1, no badge will be displayed.
`display` | Object | Defines the display properties of the popover (see below)

### Display options

Property | Type | Description
--- | --- | ---
`width` | String | The width of the popover (must be a CSS-friendly value; default: `auto`)
`height` | String | The height of the popover (must be a CSS-friendly value; default: `auto`)
`className` | String | Optional class name(s) to be added to the popover

## Example with default values

```js
$('.my-button').popover({
    html: '',
    badge: 0,
    display: {
        width: 'auto',
        height: 'auto'
    }
});
```

## Specifications

Clicking outside of an open popover will close it.

Only one popover may be open at a time. If a popover is open when a second popover is triggered, the first popover is closed before opening the second popover.

The popover container has the class `.cui-popover`.