Zebra_Dialog, a lightweight dialog box jQuery plugin

Zebra_Dialog, a lightweight dialog box jQuery plugin

http://stefangabos.ro/jquery/zebra-dialog/

• Latest version

  1.2

  released on

  April 07, 2012

• 1. Overview
• 2. Requirements
• 3. How to use
• 4. Configuration
• 5. Download
• 6. Changelog
• 7. Comments

A modal window is a child window that requires users to interact with it before they can continue using the parent application. Modal windows are one of the most commonly used user interface elements, and are used to command user awareness in order to communicate important information, or to alert of errors or warnings.

Zebra_Dialog is a small (4KB minified), compact (one Java Script file, no dependencies other than jQuery 1.5.2+) and highly configurable jQuery plugin for creating modal dialog boxes, meant to replace native Java Script “alert” and “confirmation” dialog boxes, and built using the jQuery Plugin Boilerplate.

Can also be used as a notification widget (when configured to show no buttons and to close automatically) for updates or errors, without distracting users from their browser experience by displaying obtrusive alerts.

Features:

• great looking dialog boxes, out of the box: CSS3, drop-shadows, rounded corners
• 5 types of dialog boxes available: confirmation, information, warning, error and question
• easily customizable appearance by editing the CSS (cascading style sheet) file
• create modal dialog boxes or non-modal dialog boxes
• easily add custom buttons
• position the dialog box wherever you want – not just in the middle of the screen
• use callback functions to handle user’s choice
• works in all major browsers (Firefox, Opera, Safari, Chrome, Internet Explorer 6+)

Icons for confirmation, information, error and question dialog boxes are made by DryIcon while the warning icon is made by Function Design & Development Studio.

Requirements

Zebra_Dialog has no dependencies other than jQuery.

I’ve only tested with jQuery 1.5.2 but it may work in earlier versions, too. If you can test, please let me know. Thanks!

How to use

First, load the latest version of jQuery either from a local source or from a CDN.

Load the Zebra_Dialog plugin

<script type="text/javascript" src="path/to/zebra_dialog.js"></script>

Load the plugin’s CSS file

<link rel="stylesheet" href="path/to/zebra_dialog.css" type="text/css">

Now, within the DOM-ready event do

$(document).ready(function() { // show a dialog box when clicking on a link $(anchor).bind('click', function(e) { e.preventDefault(); $.Zebra_Dialog('The link was clicked!'); }); });

Demos

1. Default dialog box, no custom settings. Click here to open.

$.Zebra_Dialog('<strong>Zebra_Dialog</strong>, a small, compact and highly' + 'configurable dialog box plugin for jQuery');

2. The five dialog box types, with titles: error, warning, question, information and confirmation.

// this example is for the "error" box only 
// for the other types the "type" property changes to "warning", "question", "information" and "confirmation" 
// and the text for the "title" property also changes 
$.Zebra_Dialog('<strong>Zebra_Dialog</strong>, a small, compact and highly' + 'configurable dialog box plugin for jQuery', { 'type': 'error', 'title': 'Error' });

3. Custom buttons and the callback function. Click here to open.
Note that the onClose event is executed *after* the dialog box is closed! see the next example for executing functions *before* the closing of the dialog box

$.Zebra_Dialog('<strong>Zebra_Dialog</strong>, a small, compact and highly' + 'configurable dialog box plugin for jQuery', {
 'type': 'question', 
'title': 'Custom buttons', 
'buttons': ['Yes', 'No', 'Help'],
'onClose': function(caption) { 
alert((caption != '' ? '"' + caption + '"' : 'nothing') + ' was clicked'); } });

3.1 Custom buttons with attached callback functions. Click here to open.
Note that the callback functions attached to custom buttons are executed *before* the dialog box is closed and as soon as a button is clicked! see the previous example for executing functions *after* the closing of the dialog box

$.Zebra_Dialog('<strong>Zebra_Dialog</strong>, a small, compact and highly' + 'configurable dialog box plugin for jQuery', { 
'type': 'question', 
'title': 'Custom buttons', 
'buttons': [ {caption: 'Yes', 
callback: function() { alert('"Yes" was clicked')}}, {caption: 'No', 
callback: function() { alert('"No" was clicked')}}, 
{caption: 'Cancel', 
callback: function() { alert('"Cancel" was clicked')}} ] });

4. Position the dialog box in the top-right corner. Click here to open.

$.Zebra_Dialog('<strong>Zebra_Dialog</strong>, a small, compact and highly' + 'configurable dialog box plugin for jQuery', { 'title': 'Custom positioning', 
'position': ['right - 20', 'top + 20'] });

5. Use as a notification widget – no buttons and close automatically after 2 seconds.
Note how the plugin needs to be instantiated with the “new” keyword or only the last opened box will close!
Click here to open.

 $.Zebra_Dialog('<strong>Zebra_Dialog</strong>, a small, compact and highly' + 'configurable dialog box plugin for jQuery', { 
'buttons': false, 
'modal': false, 
'position': ['right - 20', 'top + 20'], 
'auto_close': 2000 });

6. Customizing the appearance – make the title bar have a dark-blue background

The CSS is

/* Notice how we're targting the dialog box's title bar through the custom class */ 
.myclass .ZebraDialog_Title {
 background: #330066 } .myclass .ZebraDialog_Body { 
background-image: url('coffee_48.png') }

Click here to open.

$.Zebra_Dialog('<strong>Zebra_Dialog</strong>, a small, compact and highly' + 'configurable dialog box plugin for jQuery',{'custom_class': 'myclass', 
'title': 'Customizing the appearance' });

Configuration

All parameters are optional.

animation_speed	integer	The speed, in milliseconds, by which the overlay and the dialog box will be animated when closing. Default is 250
auto_close	mixed	The number of milliseconds after which to automatically close the dialog box or FALSE to not automatically close the dialog box. Default is FALSE.
buttons	mixed	Use this for localization and for adding custom buttons. If set to TRUE, the default buttons will be used, depending on the type of the dialog box: ['Yes', 'No'] for “question” type and ['Ok'] for the other dialog box types. For custom buttons, use an array containing the captions of the buttons to display: ['My button 1', 'My button 2']. Set to FALSE if you want no buttons. Note that when the dialog box is closed as a result of clicking a button, the “onClose” event is triggered and the callback function (if any) receives as argument the caption of the clicked button. See the comments for the “onClose” event below for more information. You can also attach callback functions to individual buttons by using objects in the form of: [ {caption: 'My button 1', callback: function() { // code }}, {caption: 'My button 2', callback: function() { // code }} ] The main difference is that a callback function attached this way is executed as soon as the button is clicked rather than *after* the dialog box is closed, as it is the case with the “onClose” event. Callback functions attached to buttons get as argument the entire dialog box jQuery object.
custom_class	mixed	An extra class to add to the dialog box’s container. Useful for customizing a dialog box elements’ styles at run-time. For example, setting this value to “mycustom” and in the CSS file having something like .mycustom .ZebraDialog_Title { background: red } would set the dialog box title’s background to red. See the CSS file for what can be changed. Default is FALSE
keyboard	boolean	When set to TRUE, pressing the ESC key will close the dialog box. Default is TRUE.
message	string	The message in the dialog box – this is passed as argument when the plugin is called.
modal	boolean	When set to TRUE there will be a semitransparent overlay behind the dialog box, preventing users from clicking the page’s content. Default is TRUE.
overlay_close	boolean	Should the dialog box close when the overlay is clicked? Default is TRUE.
overlay_opacity	double	The opacity of the overlay (between 0 and 1) Default is .9
position	mixed	Position of the dialog box. Can be either “center” (which would center the dialog box) or an array with 2 elements, in the form of ['horizontal_position +/- offset', 'vertical_position +/- offset'] (notice how everything is enclosed in quotes) where “horizontal_position” can be “left”, “right” or “center”, “vertical_position” can be “top”, “bottom” or “middle”, and “offset” represents an optional number of pixels to add/substract from the respective horizontal or vertical position. Positions are relative to the viewport (the area of the browser that is visible to the user)! Examples: ['left + 20', 'top + 20'] would position the dialog box in the top-left corner, shifted 20 pixels inside. ['right - 20', 'bottom - 20'] would position the dialog box in the bottom-right corner, shifted 20 pixels inside. ['center', 'top + 20'] would position the dialog box in center-top, shifted 20 pixels down. Default is ['center', 'middle']
title	string	Title of the dialog box Default is “” (an empty string – no title)
type	mixed	Dialog box type. Can be any of the following: - confirmation - error - information - question - warning If you don’t want an icon, set the “type” property to FALSE. By default, all types except “question” have a single button with the caption “Ok”; type “question” has two buttons, with the captions “Ok” and “Cancel” respectively. Default is “information”.
vcenter_short_message	boolean	Should short messages be vertically centered? Default is TRUE.
width	integer	Width of the dialog box By default, the width of the dialog box is set in the CSS file. Use this property to override the default width at run-time. Must be an integer, greater than 0. Anything else will instruct the script to use the default value, as set in the CSS file. Value should be no less than 200 for optimal output. Default is 0 – use the value from the CSS file.
Events
onClose		Event fired when *after* the dialog box is closed. For executing functions *before* the closing of the dialog box, see the “buttons” attribute. The callback function (if any) receives as argument the caption of the clicked button or boolean FALSE if the dialog box is closed by pressing the ESC key or by clicking on the overlay.
Public methods
close		Call this method to manually close the dialog box.

version 1.2 (zip, 99.6Kb)

Zebra_Dialog is distributed under the LGPL.

In plain English, this means that you have the right to view and to modify the source code of this software, but if you modify and distribute it, you are required to license your copy under a LGPL-compatible license, and to make the entire source code of your derivation available to anybody you distribute the software to.

You also have the right to use this software together with software thas has different licensing terms (including, but not limited to, commercial and closed-source software), and distribute the combined software, as long as state that your software contains portions licensed under the LGPL license, and provide information about where the LGPL licensed software can be downloaded.

If you distribute copies of this software you may not change the copyright or license of this software.

You may also like:

• jQuery Plugin Boilerplate
• Zebra_Accordion, a tiny accordion jQuery plugin
• Zebra_Cookie, an extremely small jQuery plugin for writing, reading and deleting cookies
• Zebra_Datepicker, a lightweight datepicker jQuery plugin
• Zebra_Tooltips, a lightweight tooltips jQuery plugin
• Zebra_TransForm, a tiny jQuery plugin for replacing checkboxes, radio buttons and selects