Drupal 6

This tutorial is on how to call a JavaScript function after a Drupal 6 #AHAH event. You can view the tutorial on how to call a JavaScript function after a Drupal 7 #AJAX event here: Calling a JavaScript function after an #AJAX event

Introduction

In Drupal 6, I've at times in the past needed to fire off a function after an AHAH callback. The problem here is that AHAH is a pre-built set of functions by Drupal, and as far as I can tell, the only function it executes after completion is Drupal.behaviors. However, I personally don't see anything in the Drupal object to differentiate whether Drupal.behaviors is being fired on initial page load, or after an AHAH event. jQuery to the rescue! jQuery offers a nice little .ajaxComplete() function that is fired off after every Ajax event. We can use this function to fire off whatever other function we want when AHAH is complete.

Requirements

• To understand this tutorial, you will need a strong understanding of how to build Drupal modules, how the Drupal form API works, how theme functions are registered, and how to add JavaScript to pages. I won't be going into a lot of detail on what exactly I am doing as I go along, so without this knowledge you may find it difficult to follow along in some spots.

• This tutorial also makes use of the AHAH Helper module. This module takes a lot of the work out of doing AHAH. I've used it for this tutorial simply to provide a simple way to add some AHAH to the tutorial. The core points of this module however (executing a function after an AHAH event) by no means have a dependency on this module, and you will be able to use the main ideas given without ever touching this module. The advantage of this module is that no AHAH callback functions need to be created, as the module takes care of all of that.

• In this tutorial I am creating a module called ahah_callback. All naming conventions will be built upon this.

Disclaimer

I am new to this method. It may be possible that there is a much cleaner method of doing this. If anyone knows one, I would love to know it so I can use it in the future. Please feel free to leave a comment and point me in the right direction.

The setup: Register a path, and build a form

The first thing we need to do is build a form that we can use for the tutorial. So we will register a path allowing us to access the form:

function ahah_callback_menu()
{
	return array
	(
		'ahah_callback' => array
		(
			'title' => 'AHAH callback test',
			'page callback' => 'drupal_get_form',
			'page arguments' => array('ahah_callback_form'),
			'access arguments' => array('access content'),
		),
	);
}

Next we need to build our callback function:

function ahah_callback_form($form_state)
{
	$form = array();
	// The AHAH helper module requires that the next
	// function be called at the beginning of the form definition
	ahah_helper_register($form, $form_state);
	// First we create a wrapper to be used by the AHAH
	$form['container'] = array
	(
		'#prefix' => '<div id="ahah_container">',
		'#suffix' => '</div>',
	);
	// Next we add some data in this container
	$form['container']['data'] = array
	(
		'#value' => '<p>Form element</p>',
	);
	// And finally we add our AHAH enabled button
	$form['button'] = array
	(
		'#type' => 'submit',
		'#value' => 'submit',
		'#ahah' => array
		(
			// The following path is how the AHAH helper module
			// registers paths. See the documentation for that
			// module for more information
			'path' => ahah_helper_path(array('container')),
			'wrapper' => 'ahah_container',
			'method' => 'append',
		),
	);
	// We will reproduce the above form elements in order to show
	// the contrast between different AHAH events later on in the
	// tutorial. So we recreate the container, the data, and the button.
	$form['container2'] = array
	(
		'#prefix' => '<div id="ahah_container2">',
		'#suffix' => '</div>',
	);
	$form['container2']['data'] = array
	(
		'#value' => '<p>form element2</p>',
	);
	$form['button2'] = array
	(
		'#type' => 'submit',
		'#value' => 'submit',
		'#ahah' => array
		(
			'path' => ahah_helper_path(array('container2')),
			'wrapper' => 'ahah_container2',
			'method' => 'append',
		),
	);
	return $form;
}

At this point, you should have a working form. When either of the buttons is pushed, the data relevant to that button increases. Note: if this isn't working for you at this point, make sure you have installed the AHAH Helper module.

We only have one thing left to do, and that is add our jQuery (JavaScript) document to our form. I add my javascript in theme functions, for reasons that are beyond the scope of this tutorial. As a short explanation, it makes everything a little more stable. So we need to do two things. The first is to register a theme function using hook_theme(), then second is to implement that theme function.

First, hook_theme():

function ahah_callback_theme()
{
	return array
	(
		'ahah_callback_form' => array
		(
			'arguments' => array('form' => NULL),
		),
	);
}

I've now registered the function theme_ahah_callback_form. As this function has the same name as the actual form, it will be automatically called, and nothing needs to be added to the form definition. This function is passed one variable, $form (all form theme functions are passed this variable, and only this variable).

Next, the theme function:

function theme_ahah_callback_form($form)
{
	// First we get the path to our module
	$path = drupal_get_path('module', 'ahah_callback');
	// Next we add the JavaScript document to the page. Note: I keep my
	// JavaScript documents in a folder called 'js'. If you have your
	// script in the root of the module folder, make sure to adjust your
	// path accordingly
	drupal_add_js($path . '/js/ahah_callback.js');
	// Finally we return the rendered form.
	return drupal_render($form);
}

Note: make sure you clear your cache after adding this code, or the the theme function won't be entered and the javascript will not be added.

The goods: jQuery magic

Now we get to the meat of this tutorial - the jQuery magic. This is where it all happens. The first thing we need to do is wrap our code in an anonymous function, passing in the jQuery object in order to prevent namespace collisions:

(function($) {
	// Our code will go in here
}(jQuery));

Next, we need to use the .ajaxComplete() function. I will attach this to the document, as in this tutorial it doesn't have any relation to any particular element.

(function($) {
	$(document).ajaxComplete(function()
	{
		// the code to be fired after the AHAH is completed will go here
	});
}(jQuery));

Each AHAH event will have a callback path. We need to find out what ours is, in order to be able to specifically target the AHAH call on the page that we want, so that our function isn't accidentally triggered by another completely separate AHAH callback on the page. I do this using the following:

(function($) {
	// we need to add some variables to the ajaxComplete()
	// callback function. The one we are most concerned with
	// is the 3rd, 'settings'
	$(document).ajaxComplete(function(e, xhr, settings)
	{
		alert(settings.url);
	});
}(jQuery));

Now, when we trigger the AHAH, after it is complete, we will get a javascript alert telling us the path that was accessed. In the case of this tutorial, the two buttons access the following paths:

• /[path_to_webroot]/ahah_helper/container

• /[path_to_webroot]/ahah_helper/container2

Note: your path to webroot will be different from mine, or possibly non-existent. In my case, the webroot is a folder called 'sandbox'. You will see this reference to sandbox in my next code.

Finally, we add a conditional (or multiple conditionals in this case) containing our code to be executed when the AHAH event in question is triggered.

(function($) {
	$(document).ajaxComplete(function(e, xhr, settings)
	{
		// button 1
		if(settings.url == "/sandbox/ahah_helper/container")
		{
			alert("button 1 pushed");
		}
		// button 2
		else if(settings.url == "/sandbox/ahah_helper/container2")
		{
			alert("button 2 pushed");
		}
	});
}

And that does it for us! When the first AHAH enabled button on the page has finished its AHAH, the text 'button 1 pushed' is shown in a javascript alert. When the second AHAH enabled button on the page has finished its AHAH, the text 'button 2 pushed' is shown in a javascript alert.

I hope this tutorial helps you out. Good luck!