ender-overlay

Ender-overlay is a highly configurable overlay plugin for Ender. You can easily build your own gallery or other overlay based logic on the top of this plugin. It's just 2.1 KByte (minified and gzipped).

It requires Jeesh and Morpheus for animations. Even though, you can leave Morpheus out if you are fine without animations. Currently it's tested in Chrome, Firefox, Safari, Opera and IE7+. You can report bugs here.

If you want to use CSS3 transitions instead of JS animations, just set the "css3transition" property to true. It will only work if the animationIn or animationOut properties are not "none". Only recent Firefox and Webkit based browsers will use transitions, older browsers will fall back to JS animations (if morpheus is available).

Moreover, it's even compatible with jQuery and Zepto! So if you want to include it in a jQuery/Zepto based project, you can do it without any extra work.

You might be interested in ender-carousel, which is a simple carousel plugin for Ender.

I got a lot inspiration from jQuery Tools, thanks for that.

Demos

Download Source

The source is hosted at Github.

Download v0.2.4

Overlay configuration

Property Default Value Description
top 80 The distance from the top edge of the screen in pixels.
position "absolute" You can use absolute or fixed as a value. With absolute, the overlay will stay at the given position. With fixed it will stay in place even when you scroll. If you choose fixed, make sure to your overlay fit in the viewport, because at lower resolutions it can be a problem.
cssClass "ender-overlay" The common CSS style for your overlays. You can use this to style your overlays.
close ".close" Selector or Ender DOM object. Every matched elements inside the overlay will close the overlay on a click event.
trigger null Selector or Ender DOM object. Every matched elements will be assigned with a click event handler wich opens the overlay. If you don't set this, you need to open the overlay manually with a method call.
zIndex 9999 Must be higher than the z-index of any direct child elements of the body element.
showMask true Whether the mask should be visible or not.
closeOnEsc true Whether the overlay closes if the user hits ESC.
closeOnMaskClick true Whether the overlay closes if the user clicks the cover mask.
autoOpen false Whether the overlay opens after creation.
allowMultipleDisplay false If it's false, then all overlays are closed automaticaly when a new overlay opens. If you set this to true you can manage multiple open overlays.
css3transition false Experimental! You can start using CSS transitions instead of JS animations. This feature is currently limited to recent versions of Firefox and Webkit based browsers. It will only work if the animationIn or animationOut property are not "none". It will fall back to JS animations if transition is not supported by the browser.
startAnimationCss { opacity: 0 } This is the starting point of the opening animation.
animationIn
{
    opacity: 1,
    duration: 250
}
Opening animation params. Set the CSS properties you want to animate and the duration of the animation. Check the configuration demo page for more info. If the mask is enabled it will inherit the animation duration automatically. Set to "none" to disable opening animation.
animationOut
{
    opacity: 0,
    duration: 250
}
Closing animation params. Set the CSS properties you want to animate and the duration of the animation. Check the configuration demo page for more info. If the mask is enabled it will inherit the animation duration automatically. Set this to "none" to disable closing animation.
mask Default mask configuration Mask configuration object. Please refer to the table below.
onBeforeOpen You can set a callback function here. It's called just before opening the overlay. It will get the overlay object as a parameter. Please refer to the methods section how to use this. If you return false the overlay won't open.
onBeforeClose You can set a callback function here. It's called just before closing the overlay. It will get the overlay object as a parameter. Please refer to the methods section how to use this. If you return false the overlay won't close.
onOpen You can set a callback function here. It's called after the overlay opened. It will get the overlay object as a parameter. Please refer to the methods section how to use this.
onClose You can set a callback function here. It's called after the overlay closed. It will get the overlay object as a parameter. Please refer to the methods section how to use this.

Mask configuration

Property Default Value Description
id "ender-overlay-mask" The id of the mask element. Only one mask element is created, no matter how much overlay you create.
zIndex 9998 Must be higher than the z-index of any direct child elements of the body element. Must be lower than the z-index of the overlays.
opacity 0.6 The opacity of the mask.
color "#777" The background-color of the mask.
css3transition Inherited Experiental! You can turn on the css3 transitions with this property. If you don't set it explicitly, it will be inherited from the overlay settings.
durationIn Inherited Fade in animation duration. Set to 0 to disable animation. If you don't set it explicitly, it will be inherited from the overlay settings.
durationOut Inherited Fade out animation duration. Set to 0 to disable animation. If you don't set it explicitly, it will be inherited from the overlay settings.

Event listeners

The following events are supported. The event-listeners are binded to the document object. You can trigger the events this way: $(document).trigger("ender-overlay.close");

Event name What happens if it's triggered?
ender-overlay.close Closes all the cover mask and all the overlays.
ender-overlay.closeOverlay Closes only the overlays. The mask will stay visible.

Methods

The $.overlay method will return the Overlay object. And you can call the following methods on it.

Method Description
open() Opens the overlay.
close() Closes the overlay.
getOverlay() Returns the overlay element.
getOptions() Returns the current overlay options.
setOptions(options) You can update the options any time with this method.

Author

I'm Andras Nemeseri a Hungarian front-end developer. You can follow me on Twitter.
Thanks to Dustin Diaz & Jacob Thornton for Ender.