# jQuery.popover

Easy to use and customizable popover plugin for jQuery.

Take a look at this blog post for more details.

## Table of Contents

## Usage

### Initialization

With default settings, calling $(element).popover(); will initalize an empty popover on the element.

I have a popover, but you can't see me. Yet.

When you click the link above, the popover is shown. This is achieved by using `{ trigger: 'click' }` in the parameters. You can hide the popover by clicking anywhere there's not a popover. The source code for the above example is:

    $("#ex1").popover({
    	trigger: 'click'
    });

When this code was executed, the popover was created but not shown. A `click` event was bound to the `a`-tag with which the popover is “connected”. When that element is clicked, the popover is shown.

But hows an empty popover any fun? Let's try this:

Please, let me speak!

Now we've put some content in our popover using the parameters `{ title: "Hello", content: "Finally, I can speak!" }`, like so:

    $("#ex2").popover({
    	title: "Hello",
    	content: "Finally, I can speak!"
    });

Note that I've ommited `{ trigger: 'click' }` in this example. It's the default setting for popovers.

### Pulling the trigger manually

You can show, hide and fade out an initialized popover manually by calling `popover('show')`, `popover('hide')` and `popover('fadeOut')` on the element the popover was initialized over.

Nope, can't be triggered, bro. Oh yes you can!

The code for this example is as follows. Click a code box to expand it.

    $("#ex3a").popover({
    	title: "&lt;_&lt;",
    	content: "Damn.",
    	trigger: 'none'
    });
    $("#ex3b").click(function(event) {
    	event.preventDefault();
    	event.stopPropagation();
    	$("#ex3a").popover('show');
    });

You must must call `event.preventDefault()` and `event. stopPropagation()` on the triggeree (?) / element that triggers the popover, otherwise `click`-event will bubble up to the document and the popover will immediately be hidden.

You can call `popover('fadeOut')` and `popover('hide')` to hide popovers with and without a fade animation.

### Hide and destroy

Use `popover('hide')`, `popover('fadeOut')` and `popover('destory')` to hide, fade out and destroy popovers. Call these methods on the element where the popover was initialized over.

I have a popover.
Show | Hide | Fade out | Destroy

These methods can be seen as the API for jQuery.popover. Here the code for this example:

    $("#ex4a").popover({
    	title: "Guess what this is...",
    	content: "Pa's wijze lynx bezag vroom het fikse aquaduct.",
    	trigger: 'none'
    });
    $("#ex4b").click(function(event) {
    	event.preventDefault();
    	event.stopPropagation();
    	$("#ex4a").popover('show');
    });
    $("#ex4c").click(function(event) {
    	event.preventDefault();
    	event.stopPropagation();
    	$("#ex4a").popover('hide');
    });
    $("#ex4d").click(function(event) {
    	event.preventDefault();
    	event.stopPropagation();
    	$("#ex4a").popover('fadeOut');
    });
    $("#ex4e").click(function(event) {
    	event.preventDefault();
    	event.stopPropagation();
    	$("#ex4a")
    		.popover('destroy')
    		.text("Nooo! What have you done?!");
    });

It could probably be a bit shorter, but I'll let you figure that out.

### Modifying on the fly

#### Title

You can change the title on the fly with by using `popover('title', "Text")`.

PHP or Ruby? PHP | Ruby

    $("#ex5a").popover({
    	title: "Hmm...",
    });
    $("#ex5b, #ex5c").click(function(event) {
    	event.preventDefault();
    	event.stopPropagation();
    	$("#ex5a").popover(
    		'title',
    		$(this).text()+" is your friend"
    	).popover('show');
    });

#### Content

You can change the title on the fly with by using `popover('content', "Text")`.

Click here first | change content

    $("#ex6a").popover({
    	title: "Dynamic content",
    	content: "At least a popover that makes some sense..."
    });
    $("#ex6b").click(function(event) {
    	event.preventDefault();
    	event.stopPropagation();
    	$("#ex6a").popover(
    		'content',
    		"At least a popover that makes some sense... Don't get used to it."
    	).popover('show');
    });

#### Loading AJAX content

You can load a webpage as content via AJAX by using `popover('ajax', "http://example.com/" [, options])`.

Click here first | load ajax content

Please note this only works when running on a webserver.

    $("#ex7a").popover({
    	title: "What's this",
    	content: "...",
    	classes: "wider"
    });
    $("#ex7b").click(function(event) {
    	event.preventDefault();
    	event.stopPropagation();
    	$("#ex7a").popover(
    		'ajax',
    		"ajax.html"
    	).popover('title', "It's AJAX content!").popover('show');
    });

Alternatively, you can set an URL in the initialization parameters to load an URL immediately on setup, like so:

    $("#selector").popover({
    	url: "test.html"
    	});

### Parameters

You may've noticed the `{ classes: "wider" }` parameter in the previous example. The value of the `classes`-parameter is applied to the popover by jQuery's `addClass()` method. You can use this to add classes for different sizes of popovers.

There are other parameters you can pass to the `popover()` method. Following is a list of them.

Option | Preffered type | Description | Default | Since
--- | --- | --- | --- | ---
verticalOffset | int | Offset the popover by y px vertically (movement depends on position of popover. If `position == 'bottom'`, positive numbers are down) | `10` | v1.0.0
horizontalOffset | int | Offset the popover by x px horizontally (movement depends on position of popover. If `position == 'right'`, positive numbers are right) | `10` | v1.0.0
title | bool|string | Contents of the heading. Set to false for no title. | `false` | v1.0.0
content | bool|string | Contents of the body of the popover. Set to false for no body. | `false` | v1.0.0
url | bool|string | Automatically load an URL into the content field on initialization, if set to an url. | `false` | v1.0.0
classes | string | Add stylesheet classes to the popover box on initalization, for example "large". | `""` | v1.0.0
position | string | Determine place of the popover. Set to "auto" for automatic placement. Yet to be implemented | `"auto"` | 1.0.8
fadeSpeed | int | How fast to fade this popover out when fading out. | `160` | v1.0.0
trigger | string | How to trigger the popover. "click" activates the popover when the linked-to element is clicked, "hover" when it's hovered on, "focus" shows it when focused and hides the popover when unfocused/blurred, and everything else sets it to manual. | `"click"` | v1.0.0
preventDefault | bool | Execute `event.preventDefault()` method on the element the popover is called on. Set this to false if you want the element (for example an `a`-element) to still execute code already bound with `.click()`. | `true` | v1.0.0
stopChildrenPropagation | bool | Execute `event.preventPropagation()` method on all children of the popover, so `click` events won't bubble up and hide the popover. | `true` | v1.0.5
hideOnHTMLClick | bool | Hide all popovers when clicked outside of them. | `true` | v1.0.0
animateChange | bool | Animate a popover reposition. Yet to be implemented. | `true` | -
autoReposition | bool | Automatically reposition popover on popover change and window resize. | `true` | v1.0.8
anchor | bool|string|jQuery | Use this parameter to anchor the popover to a different element than it's invoked on. This is useful when using `{ trigger: 'hover' }`. | `false` | v1.0.2

For convienience, here is this plugin's defaults prototype.

    var defaults = {
    	verticalOffset: 10,
    	horizontalOffset: 10,
    	title: false,
    	content: false,
    	url: false,
    	classes: '',
    	position: 'auto',
    	fadeSpeed: 160,
    	trigger: 'click',
    	preventDefault: true,
    	stopChildrenPropagation:
    	hideOnHTMLClick: true,
    	animateChange: true,
    	autoReposition: true,
    	anchor: false: false
    }

### Methods

Following is a reference of all methods you can call. Every method returns a jQuery result set, to maintain chainability.

Method | Returns | Description | Usage
--- | --- | --- | ---
init | jQuery | (default method) Initializes a popover on elements. Reads defaults (see above), combines them with parameters and makes and links the popover. | `$("#selector").popover(["init", ] { title: "Test" });`
destroy | jQuery | Removes the linked popover(s) from the DOM, as well as it's data/settings. | `$("#selector").popover('destroy');`
show | jQuery | Show a linked popover, if it exists. | `$("#selector").popover('show');`
hide | jQuery | Hide a linked popover, if it exists. | `$("#selector").popover('hide');`
fadeOut | jQuery | Fade out a linked popover, if it exists, in as many milliseconds you set the fadeSpeed parameter to on initialization, or how many as you passed to the method. | `$("#selector").popover('fadeOut' [, 1000]);`
hideAll | jQuery | Hide all initialized popovers. | `$("#selector").popover('hideAll');`
fadeOutAll | jQuery | Fade out all initialized popovers. The duration is set by using the parameter `fadeSpeed` when initiaizing, or passing this to the method. | `$("#selector").popover('fadeOutAll' [, 1000]);`
setTrigger | jQuery | Sets a popover's trigger method (see this for information on triggers). Also unbinds the previous trigger(s). | `$("#selector").popover('setTrigger', 'hover');`
setOption | jQuery | Sets an option to the specified value. | `$("#selector").popover('setOption', 'fadeSpeed', 500);`
getData | mixed | Get a popover's data. If multiple elements are targeted, the function returns an array of objects. | `$("#selector").popover('getData');`

### Download

You can download jQuery.popover by cloning it from Github:

`git clone git@github.com:klaas4/jQuery.popover.git`

Or simply download the zip-package.

Please also check out my blog at http://daveyyzermans.nl/, and if you want, shoot me an e-mail.