Creating a custom dialog with jquery and jquery.blockUI
The goal of this article is to demostrate how to create a dialog with it own self-contained functionality using jQuery and blockUI.
For this we need jQuery (v1.3.x) ((jQuery (v1.3.x) from jquery.com)) and blockUI(v2.15+) ((blockUI(v2.15+) from malsup.com)). I assume you have at least basic understanding of jQuery and JavaScript to make use of this article.
I tend to think of a dialog like an interface with it's own enclosure containing attributes, private functions and public functions. The idea is that we can reuse the functionality easily, just include the javascript-file in the webpage and call a function.
The dialog I'll create here is a dialog from which a user will select the size of a pair of jeans.
I pack my code into a namespace, so I create the namespace first ((Covered in Namespacing in JavaScript)). My dialog will be a subset of UI.dialog.
var UI = {
dialog : {}
};
Now I can create the basic structure of our interface in a new file:
( function( UI, $ ) {
// Make sure the namespace exists.
if ( !UI.dialog ) {
UI.dialog = {};
}
// It this interface already loaded?
if ( UI.dialog.selectSize ) {
// If so don't intiate it again
return;
}
// Attributes
// Private functions
// Public functions
UI.dialog.selectSize = function( ) {
};
} )( UI, jQuery );
This piece of code shows the basic code-structure I use to create an interface.
First I create an enclosure which is an anonymous function ((Covered in Reintroducing a little sanity in working with JavaScript)),
which is called immediately with the UI and jQuery parameter. Everything inside this enclosure is unreachable from the outside, unless I intentionally make it public by binding functions or variables to a global variable like UI.
I these three sections in my enclosure:
- Attribute section
- Private function section
- Public function section
In the same way I would have it in a class in C++ or Java, which is the model I used to come up with this.
Now I'll create the HTML part of this dialog. I'll add the function setupHTML to the private functions section.
function setupHTML( q, msg, sizes ) {
// We need a group name to make exclusive selection in the radio buttons we are going to create.
var group_name = "size_" + parseInt( Math.random( ) * 100, 10 );
// Write the HTML much like the way, we would write it directly in our .html-file.
var dd = "<div style='text-align : left; cursor : default;'>";
dd += "<div style='font-weight: bolder; padding-left:20px;padding-right:20px;'>" + msg + "</div>";
// Add a radio-button for each size in our sizes, array.
$.each( sizes, function( i, size ) {
dd += "<div>";
dd += "<input type='radio' id='" + group_name + "_" + i + "' style='margin-right: 8px;' name='" + group_name + "' value='" + size + "' />";
dd += "<label for='" + group_name + "_" + i + "'>" + size + "</label>";
dd += "</div>";
} );
// Add buttons
dd += "<div style='text-align: right; padding : 5px;'>";
dd += "<button xvalue='okay' disabled='disabled'>Okay</button>";
dd += "<button xvalue='cancel'>Cancel</button>";
dd += "</div>";
dd += "</div>";
q.html( dd );
}
Now that we have the function for creating the HTML, we need to create the function to open the dialog.
This function is called UI.dialog.selectSize(...) and takes three parameters:
- msg // The message to the user
- sizes // An array containing the available sizes
- callback // The function is called after the user clicks "okay". The first parameter in the callback function is the selected size
UI.dialog.selectSize = function( msg, sizes, callback ) {
// There is no point in showing the dialog without both msg and sizes
if ( msg && sizes ) {
// Block the whole page
$.blockUI( {
message : $( "<div id='select_size_overlay'></div>" ),
css : {
width : "auto",
height : "auto"
}
} );
// The container for the dialog is the div I created above,
// we need to find it and add the content to it.
var q = $( "#select_size_overlay" );
setupHTML( q, msg, sizes );
// TODO: Handle events
}
};
In this function I haven't added the events yet, this is because I haven't created the event functions yet.
To limit the potential memory leaks in browsers like IE6, I choose not to make them inline event-functions but to make them private functions.
The potential memory leak is that referencing DOM-element in inline function, creates an extra reference to that element which can confuse the garbage collector. The problem is increased if the function is inline, since it's created every time the parent function is call which could be many time.
I put my event functions in the private functions-section of my interface.
function button_click_event( e ) {
// Get the element that was clicked, which is e.target.
// This should work in all browsers since jQuery have been so kind as to fix broken event-objects.
var el = $( e.target );
// Get data for this event
// This is important since it holds reference to data from the UI.dialog.selectSize-function.
var data = e.data;
// The xvalue-attr tells the event-handler which action we want to perform.
var xvalue = el.attr( "xvalue" );
if ( xvalue == "okay" ) {
// Is something selected?
var radios = data.radios;
var selected_val = radios.filter( ":checked" ).val( );
if ( selected_val ) {
if ( $.isFunction( data.callback ) ) {
data.callback( selected_val );
}
$.unblockUI( );
} else {
// Should never happen, since the okay button should be disabled
alert( "You must select a size." );
}
} else if ( xvalue == "cancel" ) {
$.unblockUI( );
}
}
function radio_click_event( e ) {
// Get the element that was clicked.
var el = $( e.target );
// Get data for this event
var data = e.data;
// Toggle okay-button on/off on selection
var radios = data.radios;
var okay_button = data.buttons.filter( "[xvalue=okay]" );
if ( radios.filter( ":checked" ).size( ) > 0 ) {
okay_button.removeAttr( "disabled" );
} else {
okay_button.attr( "disabled", "disabled" );
}
}
Now that these event-functions have been created I can bind them in the UI.dialog.selectSize-function:
UI.dialog.selectSize = function( msg, sizes, callback ) {
// There is no point in showing the dialog without both msg and sizes
if ( msg && sizes ) {
// Block the whole page
$.blockUI( {
message : $( "<div id='select_size_overlay'></div>" ),
css : {
width : "auto",
height : "auto"
}
} );
// The container for the dialog is the div I created above,
// we need to find it and add the content to it.
var q = $( "#select_size_overlay" );
setupHTML( q, msg, sizes );
// Inorder for the dialog to work, we need to bind some event to the elements in it.
var buttons = q.find( "button[xvalue]" );
var radios = q.find( "input[type=radio]" );
// Handle events
// I'm using jQuery's bind function to bind the events to the elements and to parse data to those events.
// I can't use buttons.click( button_click_event ),
because I need to parse some extra data to the events.
// Handle click event for the buttons
buttons.bind( "click", {
callback : callback,
buttons : buttons,
radios : radios
}, button_click_event );
// Handle click event for the radio-buttons
radios.bind( "click", {
buttons : buttons,
radios : radios
}, radio_click_event );
}
};
Now I'm done with writing the dialog interface, here is the entire code including jslint parameters ((I prefer to run all my JS-code through jslint to find hidden errors.)):
/*jslint undef: true, browser: true */
/*global jQuery, UI */
( function( UI, $ ) {
if ( !UI.dialog ) {
// This is part of the UI.dialog namespace, if the namespace doesn't exist create the namespace object
UI.dialog = {};
}
// It this interface already loaded?
if ( UI.dialog.selectSize ) {
return;
}
// Attributes
// Private functions
function setupHTML( q, msg, sizes ) {
// We need a group name to make exclusive selection in the radio buttons we are going to create.
var group_name = "size_" + parseInt( Math.random( ) * 100, 10 );
// Write the HTML much like the way, we would write it directly in our .html-file.
var dd = "<div style='text-align : left; cursor : default;'>";
dd += "<div style='font-weight: bolder; padding-left:20px;padding-right:20px;'>" + msg + "</div>";
// Add a radio-button for each size in our sizes, array.
$.each( sizes, function( i, size ) {
dd += "<div>";
dd += "<input type='radio' id='" + group_name + "_" + i + "' style='margin-right: 8px;' name='" + group_name + "' value='" + size + "' />";
dd += "<label for='" + group_name + "_" + i + "'>" + size + "</label>";
dd += "</div>";
} );
// Add buttons
dd += "<div style='text-align: right; padding : 5px;'>";
dd += "<button xvalue='okay' disabled='disabled'>Okay</button>";
dd += "<button xvalue='cancel'>Cancel</button>";
dd += "</div>";
dd += "</div>";
q.html( dd );
}
/*
* Event for handling click on any button in the overlay
*/
function button_click_event( e ) {
// Get the element that was clicked. jQuery fixes the incompatibility between browsers' event-object (e).
var el = $( e.target );
// Get data for this event
var data = e.data;
// The xvalue-attr tells the event-handler which action we want to perform.
var xvalue = el.attr( "xvalue" );
if ( xvalue == "okay" ) {
// Is something selected?
var radios = data.radios;
var selected_val = radios.filter( ":checked" ).val( );
if ( selected_val ) {
if ( $.isFunction( data.callback ) ) {
data.callback( selected_val );
}
$.unblockUI( );
} else {
// Should never happen, since the okay button should be disabled
alert( "You must select a size." );
}
} else if ( xvalue == "cancel" ) {
$.unblockUI( );
}
}
function radio_click_event( e ) {
// Get the element that was clicked. jQuery fixes the incompatibility between browsers' event-object (e).
var el = $( e.target );
// Get data for this event
var data = e.data;
// Toggle okay-button on/off on selection
var radios = data.radios;
var okay_button = data.buttons.filter( "[xvalue=okay]" );
if ( radios.filter( ":checked" ).size( ) > 0 ) {
okay_button.removeAttr( "disabled" );
} else {
okay_button.attr( "disabled", "disabled" );
}
}
// Public functions
UI.dialog.selectSize = function( msg, sizes, callback ) {
if ( msg && sizes ) {
$.blockUI( {
message : $( "<div id='select_size_overlay'></div>" ),
css : {
width : "auto",
height : "auto"
}
} );
var q = $( "#select_size_overlay" );
setupHTML( q, msg, sizes );
var buttons = q.find( "button[xvalue]" );
var radios = q.find( "input[type=radio]" );
// Handle events
// Handle click event for the buttons
buttons.bind( "click", {
callback : callback,
buttons : buttons,
radios : radios
}, button_click_event );
// Handle click event for the radio-buttons
radios.bind( "click", {
buttons : buttons,
radios : radios
}, radio_click_event );
}
};
} ) ( UI, jQuery );
Using the dialog is as simple as this:
UI.dialog.selectSize( "Select size of the jeans", [
"xx-small", "x-small", "small", "medium", "large", "x-large", "xx-large", "xxx-large", "xxxx-large"
], function( size ) {
// TODO: Do something usefull with the size
alert( size );
} );