Part of the power of having jQuery integrated with Drupal is the ability to take advantage of the strong jQuery developer community. There are many, many plug-ins for jQuery that can add some great functionality to your site - usually with very little code.
jqModal is just one of these plug-ins. It can be used to create modal (or non-modal) dialog boxes. In this example, I'm going to show you how to use it to create a modal "Please Wait..." dialog box. This can be useful when your user submits a form that might take a few seconds to process. Having a modal dialog box not only gives the user some feedback that the site is actually doing something, but it also stops the user from clicking the "submit" button multiple times.
I've created a sample module (Drupal 5) to illustrate how it works. You can download it and integrate it into your own modules.
Let's take a quick look at the various files in the module:
- jqmodal.info - standard Drupal 5 .info file
- jqmodal.module - implements hook_form_alter and a theme function for the modal window
- sample.js - jQuery code that enables the modal window and displays it at the proper time
- sample.js - CSS code that themes the modal window
- /jqmodal/jqmodal.js - jqmodal plug-in
- /jqmodal/jqmodal.css - jqmodal default css
For simplicity, all of the files are included in the jqmodal module. In a live site, you may want to move the contents of sample.js and sample.css to your site's theme.
The guts of the code are in the jqmodal.module file:
function jqmodal_form_alter($form_id, &$form) {
global $user;
switch($form_id) {
case 'comment_form':
drupal_add_js(drupal_get_path('module', 'jqmodal') . '/jqmodal/jqmodal.js');
drupal_add_css(drupal_get_path('module', 'jqmodal') . '/jqmodal/jqmodal.css');
drupal_add_js(drupal_get_path('module', 'jqmodal') . '/sample.js');
drupal_add_css(drupal_get_path('module', 'jqmodal') . '/sample.css');
$form['throbber'] = array(
'#type' => 'markup',
'#value' => theme('jqmodal_throbber_window', 'Please wait...', 'He that can have patience can have what he will.'),
);
break;
}
}
function theme_jqmodal_throbber_window($toptext, $bottomtext) {
$output = '<div class="throbber">';
$output .= '<div class="toprow">' . $toptext . '</div>';
$output .= '<div class="bottomrow">' . $bottomtext . '</div>';
$output .= '</div>';
return $output;
}
The jqmodal_form_alter function simply adds the modal window to the comment form. There are a couple of drupal_add_js and drupal_add_css functions to includes the plug-in and an additional form element to hold the modal window. The sample.css code sets the modal window's display to "none" so it is does not appear when the user first displays the page. The additional form element passes two strings to the modal window - these are used to customize the message that is displayed to the user. Ideally, the values of the strings can be set using the module's settings page.
The theme function takes the 2 text strings and outputs the HTML for the modal window. By using a theme function, the look and feel of the modal window can be easily customized.
The sample.js file is quite short:
$(document).ready(function(){
$('.throbber').jqm({modal:true});
$('#comment-form .form-submit').click(function() {
$('.throbber').jqmShow();
return true;
});
});
After ensuring that the page is loaded, a call to the .jqm() function calls the plugin and sets up the modal window for the targeted elements (in this case, anything with a class="throbber"). Then, we just attach the jqmShow() function to the click action of comment form submit buttons.
The sample.css file controls the look of the modal dialog box:
.throbber {
position: fixed;
top: 50%;
left: 50%;
margin-left: -200px;
width: 400px;
margin-top: -80px;
height: 160px;
background-color: green;
color: #333;
border: 1px solid black;
padding: 5px;
display: none;
}
.throbber div {
background-color: #FFFFFF;
margin: 5px;
font-size: 1.2em;
font-weight: bold;
color: #000000;
padding: 5px;
border: 1px solid red;
}
The only thing that is actually necessary to make everything work is the "display: none;" definition. This hides the modal dialog box when the page is first rendered. The rest of the CSS code is just for taking care of how the modal dialog box looks.
What I've shown here is just a small portion of what the jqModal dialog box can do. Additional functionality includes close buttons, AJAX calls for the content of the box, and the ability to display multiple boxes. The jqModal home page has a bunch of demos that you can check out.