VeilJS is slated to become the small library for overlays and dialogues that integrates easily into your project.
It assumes as little as possible about your markup, styling and frontend code. Whether you want to use it with Zurb Foundation or Bootstrap, wrap it in a Knockout binding or an Angular Directive, or swap out jQuery with Zepto through requireJS — Veil is built with these requirements in mind.
- easy to read, extend and hook into to do your bidding
- well-documented
- tested
- small
- veil.js
- The library itself. (required)
- veil-jquery.js
- A jQuery plugin adapter for Veil. See the section (TODO) (optional)
- veil-knockout.js
- A Knockout binding for Veil. See the section (TODO) (optional)
- veil-examples.css
- Some example styles (TODO) (optional)
Either:
-
With Bower:
$ bower install veiljs(not yet released) -
Download the latest release: link
-
Clone the repository:
$ git clone https://github.com/janfoeh/veiljs.git
Include the components in your site:
<head>
<script type="text/javascript" src="veil.js"></script>
<!-- optional: the jQuery adapter if you prefer to use Veil in the form of $(selector).veil() -->
<script type="text/javascript" src="veil-jquery.js"></script>
<!-- optional: the Knockout binding -->
<script type="text/javascript" src="veil-knockout.js"></script>
</head>These affect all Veil instances on a page. Set them through Veil.globalOptions.
<tr>
<td>cssTransitionSupport</td>
<td><i>true</i></td>
<td>see - TODO - for more details</td>
</tr>
| Option | Default | Description |
|---|---|---|
| backdropMarkup | "<div class='veil-backdrop'></div>" |
the markup for the backdrop. Set to null to disable it.
|
Veil.globalOptions.backdropMarkup = null;
These affect only individual instances.
<tr>
<td>listenToCustomEvents</td>
<td><i>false</i></td>
<td>enables custom events. See <a href="#events">Events</a></td>
</tr>
<tr>
<td>debug</td>
<td><i>false</i></td>
<td>provide debug information and error handling in the console</td>
</tr>
| Option | Default | Description |
|---|---|---|
| overlayClass | additional CSS class(es) to apply to the overlay markup |
new Veil({overlayClass: 'my-custom-class'});
You can set defaults for all future instances, too:
Veil.prototype.defaults.overlayClass = 'my-custom-class';
- .show()
- Displays the overlay. Creates the markup if it is not already present
- .hide()
- Hides the overlay. Keeps the overlay markup in the DOM
- .overlay()
- Returns the overlay markup from the DOM as a jQuery object. Creates the markup if it is not already present
- .exists()
- Does the overlay currently exist in the DOM?
- .isActive()
- Is the overlay currently active, or in the process of activating?
- .setContent(string)
- Set or update the overlay content
- .destroy()
- Remove the overlay markup from the DOM immediately. Does not hide it first if currently active
- .addCallback(triggerName, callback)
- Adds a callback function, to be executed at <triggerName>
See the docs for more details.
You can add callbacks either in an object literal as the second argument to new Veil(options, callbacks), or through
addCallback(). The second form allows multiple callbacks per trigger, which are executed in the order they where added.
var v = new Veil({}, {afterCreate: function(overlay) {} });
v.addCallback('afterCreate', function(overlay) {});- afterCreate
- Called after the overlay markup has been created. Receives the overlay DOM element as a jQuery object. It is called in the scope of the Veil instance.
- afterShow
- Called after the overlay markup has been shown. Receives the overlay DOM element as a jQuery object. It is called in the scope of the Veil instance.
See the docs for more details.
Set the listenToCustomEvents option to true to have Veil listen for custom events. Event listeners are bound to the
overlay and use the "veil" event namespace.
- hide.veil
- Hides the overlay
var veil = new Veil({listenToCustomEvents: true});
veil.setContent("<button class='close'>Close me</button>");
$('.close').on('click', function() {
$(this).trigger('hide.veil');
});Of course in this specific example the same effect could be achieved by simply calling veil.hide() in the click handler.
Please bear with me for the sake of simplicity here.
Veil overlays and backdrops can be animated completely with CSS transitions; to achieve this, it cycles to a set of state classes:
(no state class) -> .activating -> .active -> .deactivating -> (no state class)
Since you will most likely want to hide inactive overlays through display: none, and CSS cannot transition the display property, Veil
inserts the .activating state for a couple of milliseconds as a workaround.
Veil listens to the transitionend event, so that the .deactivating
// overlays are hidden by default
.veil-overlay {
display: none;
z-index: 10;
-webkit-transition: all 0.3s;
-moz-transition: all 0.3s;
-o-transition: all 0.3s;
transition: all 0.3s;
filter: progid:DXImageTransform.Microsoft.Alpha(Opacity=0);
opacity: 0;
-webkit-transform: scale(0.7);
-moz-transform: scale(0.7);
-ms-transform: scale(0.7);
-o-transform: scale(0.7);
transform: scale(0.7);
}
// in all other states, they are displayed
.veil-overlay.activating, .veil-overlay.active, .veil-overlay.deactivating {
display: block;
}
// the changes from .activating to .active
.veil-overlay.active {
filter: progid:DXImageTransform.Microsoft.Alpha(Opacity=100);
opacity: 1;
-webkit-transform: scale(1);
-moz-transform: scale(1);
-ms-transform: scale(1);
-o-transform: scale(1);
transform: scale(1);
}
// when deactivating, transition back to the default opacity and transform values
.veil-overlay.deactivating {
filter: progid:DXImageTransform.Microsoft.Alpha(Opacity=0);
opacity: 0;
-webkit-transform: scale(0.7);
-moz-transform: scale(0.7);
-ms-transform: scale(0.7);
-o-transform: scale(0.7);
transform: scale(0.7);
}