jQuery-popover¶ ↑

• github.com/harryhorn/jquery-popover

Description:¶ ↑

jQuery-popover is a jQuery plugin that provides an easy way to create iPad like popovers.

Forked and based on juggy/jquery-popover by Julien Guimont.

jQuery-popover has been significantly refactored & enhanced. See details below.

Install¶ ↑

Simply:

• copy jquery.popover.js to your /javascripts folder

• copy jquery.popover.css to your /stylesheets folder

• make sure to reference the above JS and CSS files in your HTML

How to use¶ ↑

With jQuery-popover you can attach a popover to the click action of any DOM element. You set the popover header and content by providing a jQuery selector. For example:

 <a id="my-button">Popover</a>

 ...

<div id="my-popover">
   <div class="header">
   ...
   </div>
   <div class="content">
   ...
   </div>
 </div>

 ...

 $('#my-button').popover({header: '#my-popover > .header', content: '#my-popover > .content'});

jQuery-popover detaches the header and content from their original DOM location and attaches them to the hidden popover. Based on the size and location of the popover as it relates to the originating element, the popover will be optimally placed on the screen. The popup can appear on all 4 sides of the originating element. To limit the popup to certain directions see options documentation section below.

As of version 0.3.0 it is also possible to create popups on yet to be created buttons by using the live option. Internally this uses the jQuery live function to listen to events on buttons that match the selector used in the popover call, for example:

$('.button').popover({header: '#my-popover > .header', content: '#my-popover > .content', live: true});

This is useful when you wish to attach a popover to dynamic buttons that may be created later on via AJAX or other means. The only limitation in this case is that, similar to the jQuery live function, the popover plugin can only be used with selectors and not with derived wrapped sets.

By default, the live option is false and the jQuery bind function will be used to attach the popover only to existing elements that match the selector at call time.

Features & changes¶ ↑

New features and changes for version 0.3.0:

• live option that enables creating popovers for dynamically created buttons (see description below)

• The openEvent & closeEvent callbacks now get called with a wrapped button parameter on which the event occurred

• Changed the name of the event to trigger to close any open popup to hideOpenPopover

• Cleaned and re-factored the code

• Enhanced the demo HTML to include some live popups

New features:

• Popover can now be created on all sides of originating button

• Options to prevent popover from opening in certain directions

• Keyboard support for popover closure via ESC

• Optional screen padding value

• Optional z-index value for popup

Other changes:

• Changes plugin name to jquery.popover.js to follow jQuery conventions

• Popover wrapper method now returns the wrapped set

• Fixed various bugs

• General cleanup and code refactoring of JS and CSS

• Moved lib jquery.popover.sass file to jquery.popover.scss format and to use compass

• Added test files

• Added the documentation you are reading …

Original features:

• CSS stylable iPad like popover with arrow

• Optional offset for popover origin

• Optional popup opened event callback

• Optional popup closed event callback

Options documentation¶ ↑

All options to the popover wrapper method are passed via a single options hash and the method returns the wrapped set.

popover(options)

Options description:

• header - required - (Selector|Element) - jQuery selector for popover header

• content - required - (Selector|Element) - jQuery selector for popover content

• id: '' - (String) - id for created popover

• openEvent: null - (Function) - callback function to be called after popover is opened.

The originating button is passed as a parameter to the function

• closeEvent: null - (Function) - callback function to be called after popover is closed.

The originating button is passed as a parameter to the function

• offsetX: 0 - (Number) - Fixed X offset for popover location

• offsetY: 0 - (Number) - Fixed Y offset for popover location

• zindex: 100000 - (Number) - css z-index of the popover

• padding: 18 - (Number) - minimum padding to be kept between popover borders and edge of document

• closeOnEsc: true - (Boolean) - pass false to disable listening to keyboard ESC to close popover.

NOTE: in Version 0.2.3 this option behavior was changed to be local to each popover and not global. See CHANGELOG for details

• preventLeft: false - (Boolean) - pass true to prevent popover from opening on left side

• preventRight: false - (Boolean) - pass true to prevent popover from opening on right side

• preventTop: false - (Boolean) - pass true to prevent popover from opening on top side

• preventBottom: false - (Boolean) - pass true to prevent popover from opening on bottom side

• live: false - (Boolean) - pass true to create a popover on a selector using jQuery live.

See section ‘How to use’ above for details

Supported events¶ ↑

When a popover is opened it triggers a document popoverOpened event and when a popover is closed it triggers a document popoverClosed event.

You can programmatically open and close a popover by using the following:

$('#button').trigger('showPopover'); 

$('#button').trigger('hidePopover');

To close the currently open popover without knowing it’s originating button, do the following:

$(document).trigger('hideOpenPopover');

NOTE: the name of this event changed in version 0.3.0 from hidePopover to hideOpenPopover

Popover styling¶ ↑

The popover style provided in jquery.popover.css is a basic style to mimic the iPad popover look & feel but you can style it anyway you like. You should keep all the original class names used in the file as they are the ones used by the plugin.

You can use the original lib/jquery.popover.scss to generate a new jquery.popover.css file if you prefer working with Sass and Compass.

If you change the size of the triangle in CSS you need to also update this size in function calcPopoverPos in the plugin JS file.

Demo & specs¶ ↑

Open demo/demo.html for a demonstration of various popovers opening on different sides based on constraints as well as a demonstration of live popup buttons.

A suite of Jasmine specs has been added that also make use of the Jasmine-jquery library.

To run the Jasmine specs simply open jasmine/SpecRunner.html in a browser.

NOTE: Newer versions of Chrome don’t allow file:// URIs to read other file:// URIs. In effect, jasmine-jquery cannot properly load fixtures under some versions of Chrome. An override for this is to run Chrome with a switch --allow-file-access-from-files (I have not verified if this works for all Chrome versions though). The full discussion on this topic can be found in this GitHub ticket.

License:¶ ↑

(The MIT License)

Copyright © 2011 Harry Hornreich

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ‘Software’), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.