Permalink
Fetching contributors…
Cannot retrieve contributors at this time
318 lines (292 sloc) 11.9 KB
<!DOCTYPE HTML>
<html lang="en">
<head>
<meta http-equiv="Content-type" content="text/html; charset=utf-8">
<title>Ender-overlay - an overlay plugin for Ender</title>
<link href='http://fonts.googleapis.com/css?family=Paytone+One' rel='stylesheet' type='text/css'>
<link rel="stylesheet" href="demos/main.css" type="text/css">
<!-- syntax highlights -->
<link rel="stylesheet" href="http://yandex.st/highlightjs/6.1/styles/github.min.css">
</head>
<body>
<div id="container" class="docs">
<h1>ender-overlay</h1>
<p>
Ender-overlay is a highly configurable overlay plugin for <a href="http://ender.no.de/">Ender</a>. You can easily build your
own <strong>gallery</strong> or other <strong>overlay</strong> based logic on the top of this plugin. It's just <strong>2.1 KByte</strong> (minified and gzipped).
</p>
<p>
It requires <a href="https://github.com/ender-js/jeesh">Jeesh</a> and <a href="https://github.com/ded/morpheus">Morpheus</a> 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 <a href="https://github.com/nemeseri/ender-overlay/issues">here</a>.
</p>
<p>
If you want to use <strong>CSS3 transitions</strong> 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).
</p>
<p>
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.
</p>
<p>
You might be interested in <a href="../ender-carousel">ender-carousel</a>, which is a simple carousel plugin for Ender.
</p>
<p>
I got a lot inspiration from <a href="http://flowplayer.org/tools/">jQuery Tools</a>, thanks for that.
</p>
<h2>Demos</h2>
<ul>
<li><a href="demos/basics.html">Basic configuration tutorial</a></li>
<li><a href="demos/content-types.html">Examples with different content types</a></li>
<li><a href="demos/configuration.html">Configuration examples</a></li>
<li><a href="demos/jquery.html">jQuery compatibility</a></li>
<li><a href="demos/zepto.html">Zepto compatibility</a></li>
</ul>
<!-- h2>Build</h2>
<p>To create an ender package containing ender-overlay, you need to install <a href="http://ender.no.de/">Ender</a> first. Then you can run build and get ender-overlay with all the prereuirements.</p>
<pre><code> $ npm install ender -g
$ ender build ender-overlay
</code></pre>
<p>To add ender-overlay to an existing ender package, you can run add.</p>
<pre><code> $ ender add ender-overlay
</code></pre-->
<h2>Download Source</h2>
<p>The source is hosted at <a href="https://github.com/nemeseri/ender-overlay">Github</a>.</p>
<a href="https://raw.github.com/nemeseri/ender-overlay/master/ender.overlay.js" class="button">Download v0.2.5</a>
<h2>Overlay configuration</h2>
<table class="config">
<thead>
<tr>
<th>Property</th>
<th>Default Value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>top</td>
<td>80</td>
<td>The distance from the top edge of the screen in pixels.</td>
</tr>
<tr>
<td>position</td>
<td>"absolute"</td>
<td>You can use <samp>absolute</samp> or <samp>fixed</samp> as a value. With <samp>absolute</samp>, the overlay will stay at the given position. With <samp>fixed</samp> it will stay in place even when you scroll. If you choose <samp>fixed</samp>, make sure to your overlay fit in the viewport, because at lower resolutions it can be a problem.</td>
</tr>
<tr>
<td>cssClass</td>
<td>"ender-overlay"</td>
<td>The common CSS style for your overlays. You can use this to style your overlays.</td>
</tr>
<tr>
<td>close</td>
<td>".close"</td>
<td>Selector or Ender DOM object. Every matched elements inside the overlay will close the overlay on a click event.</td>
</tr>
<tr>
<td>trigger</td>
<td>null</td>
<td>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 <a href="#methods">method</a> call.</td>
</tr>
<tr>
<td>zIndex</td>
<td>9999</td>
<td>Must be higher than the z-index of any direct child elements of the body element.</td>
</tr>
<tr>
<td>showMask</td>
<td>true</td>
<td>Whether the mask should be visible or not.</td>
</tr>
<tr>
<td>closeOnEsc</td>
<td>true</td>
<td>Whether the overlay closes if the user hits ESC.</td>
</tr>
<tr>
<td>closeOnMaskClick</td>
<td>true</td>
<td>Whether the overlay closes if the user clicks the cover mask.</td>
</tr>
<tr>
<td>autoOpen</td>
<td>false</td>
<td>Whether the overlay opens after creation.</td>
</tr>
<tr>
<td>allowMultipleDisplay</td>
<td>false</td>
<td>If it's <samp>false</samp>, then all overlays are closed automaticaly when a new overlay opens. If you set this to <samp>true</samp> you can manage multiple open overlays.</td>
</tr>
<tr>
<td>css3transition</td>
<td>false</td>
<td><strong>Experimental!</strong> 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.</td>
</tr>
<tr>
<td>startAnimationCss</td>
<td>{ opacity: 0 }</td>
<td>This is the starting point of the opening animation.</td>
</tr>
<tr>
<td>animationIn</td>
<td>
<pre>
{
opacity: 1,
duration: 250
}
</pre>
</td>
<td>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 <b>"none"</b> to disable opening animation.</td>
</tr>
<tr>
<td>animationOut</td>
<td>
<pre>
{
opacity: 0,
duration: 250
}
</pre>
</td>
<td>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 <b>"none"</b> to disable closing animation.</td>
</tr>
<tr>
<td>mask</td>
<td><a href="#maskConf">Default mask configuration</a></td>
<td>Mask configuration object. Please refer to the table <a href="#maskConf">below</a>.</td>
</tr>
<tr>
<td>onBeforeOpen</td>
<td></td>
<td>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 <a href="#methods">methods</a> section how to use this. If you return <samp>false</samp> the overlay won't open.</td>
</tr>
<tr>
<td>onBeforeClose</td>
<td></td>
<td>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 <a href="#methods">methods</a> section how to use this. If you return <samp>false</samp> the overlay won't close.</td>
</tr>
<tr>
<td>onOpen</td>
<td></td>
<td>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 <a href="#methods">methods</a> section how to use this.</td>
</tr>
<tr>
<td>onClose</td>
<td></td>
<td>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 <a href="#methods">methods</a> section how to use this.</td>
</tr>
</tbody>
</table>
<h2 id="maskConf">Mask configuration</h2>
<table class="config">
<thead>
<tr>
<th>Property</th>
<th>Default Value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>id</td>
<td>"ender-overlay-mask"</td>
<td>The <samp>id</samp> of the mask element. Only one mask element is created, no matter how much overlay you create.</td>
</tr>
<tr>
<td>zIndex</td>
<td>9998</td>
<td>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.</td>
</tr>
<tr>
<td>opacity</td>
<td>0.6</td>
<td>The opacity of the mask.</td>
</tr>
<tr>
<td>color</td>
<td>"#777"</td>
<td>The <samp>background-color</samp> of the mask.</td>
</tr>
<tr>
<td>css3transition</td>
<td>Inherited</td>
<td><strong>Experiental!</strong> 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.</td>
</tr>
<tr>
<td>durationIn</td>
<td>Inherited</td>
<td>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.</td>
</tr>
<tr>
<td>durationOut</td>
<td>Inherited</td>
<td>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.</td>
</tr>
</tbody>
</table>
<h2>Event listeners</h2>
<p>The following events are supported. The event-listeners are binded to the <samp>document</samp> object. You can trigger the events this way: <samp>$(document).trigger("ender-overlay.close");</samp></p>
<table class="events">
<thead>
<tr>
<th>Event name</th>
<th>What happens if it's triggered?</th>
</tr>
</thead>
<tbody>
<tr>
<td>ender-overlay.close</td>
<td>Closes all the cover mask and all the overlays.</td>
</tr>
<tr>
<td>ender-overlay.closeOverlay</td>
<td>Closes only the overlays. The mask will stay visible.</td>
</tr>
</tbody>
</table>
<h2 id="methods">Methods</h2>
<p>The $.overlay method will return the Overlay object. And you can call the following methods on it.</p>
<table class="methods">
<thead>
<tr>
<th>Method</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>open()</td>
<td>Opens the overlay.</td>
</tr>
<tr>
<td>close()</td>
<td>Closes the overlay.</td>
</tr>
<tr>
<td>getOverlay()</td>
<td>Returns the overlay element.</td>
</tr>
<tr>
<td>getOptions()</td>
<td>Returns the current overlay options.</td>
</tr>
<tr>
<td>setOptions(options)</td>
<td>You can update the options any time with this method.</td>
</tr>
</tbody>
</table>
<h2>Author</h2>
<p>I'm <a href="http://nemeseri.com">Andras Nemeseri</a> a Hungarian front-end developer. You can follow me on <a href="http://twitter.com/nemeseri">Twitter</a>. <br>Thanks to Dustin Diaz &amp; Jacob Thornton for Ender.</p>
</div> <!-- #container -->
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-25617420-1']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
</body>
</html>