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.

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:

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.

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

$("#ex3a").popover({
	title: "<_<",
	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.

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").

$("#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").

$("#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]).

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.

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.

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.