iPad like popover in jQuery
Switch branches/tags
Pull request Compare This branch is 32 commits behind harryhorn:master.
Latest commit e0ef87f Jul 7, 2011 @harryhorn harryhorn readme fix

README.rdoc

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 popover.css to your /stylesheets folder

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

You can copy the test folder to your HTTP root public folder and use test.html to test the plugin

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

Features & changes

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 popover.sass file to 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

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

  • 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

  • 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

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, for example from the cancel button of a popup dialog, do the following:

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

Popover styling

The popover style provided in 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/popover.scss to generate a new popover.css file if you prefer working with SCSS 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.

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.