Extensibility AJAX

This document is designed to explain the concepts of enabling AJAX refresh in an Advanced Sidebox addon module. For further details, view the entire list of extensibility documents: Extensibility Docs

Using AJAX Refresh

ASB is constructed so that modules only need to provide a few basic parts of the actual AJAX routines. To make your module AJAX-ready, you won't need to worry about the JS side of things at all. In fact, in all of the default modules, I've created an intermediary function that produces the content and is shared by both the _build_template() function and the _xmlhttp() function.

Enabling AJAX Refresh

In your module's _info() function, add the xmlhttp setting with a value of (bool) true:

function asb_example_info()
{
	return array(
		"title" => 'XMLHTTP Example',
		[...]
		"xmlhttp" => true
	);
}

Creating the XMLHTTP Function

The _xmlhttp() function is much like the _build_template() function. It receives its arguments in the same way, but it receives a slightly different set of info and rather than eval()ing the output, it needs to return it.

The Benefits of An Intermediary Function

The _build_template() function and the _xmlhttp() function both need the same information, one must eval() the data so that ASB can access it globally and display it; the other must be return to an AJAX routine which will validate and display it. So, it makes good sense to create a function to build the add-on module's content and then simple call it from both functions:

function asb_example_build_template($args)
{
	// retrieve side box box settings
	extract($args);

	global $$template_var;
	$$template_var = asb_example_get_content();
	return true;
}

function asb_example_xmlhttp($args)
{
	// retrieve side box box settings
	extract($args);

	$content = asb_example_get_content();
	if($content)
	{
		return $content;
	}
	return 'nochange';
}

function asb_example_get_content()
{
	// get the content here, may need to be passed settings and/or width arguments
}

The XMLHTTP Arguments

The $args variable is an array the translate to these variables:

• $settings - (array) - used when the add-on module has individual settings, passes an associative array of add-on settings
• $dateline - (string) - the UNIX date stamp when the side box was last updated or checked for an update
• $width - (int) - side box columns (left/right) can have different widths so this value is provided to better size content based on the different value. The appropriate value for the side box's position will be passed

The XMLHTTP Settings

The final requirement of an AJAX-ready module is that is has a setting to adjust the refresh rate-- if that setting doesn't exist or is set to 0 by admin (or by default) then refresh will not occur. In the _info() function, add a setting for XMLHTTP like this:

function asb_example_info()
{
	global $lang;

	if(!$lang->asb_addon)
	{
		$lang->load('asb_addon');
	}

	return array(
		"title" => 'XMLHTTP Example',
		[...]
		"settings" => array(
			"xmlhttp_on" => array(
				"sid" => "NULL",
				"name" => "xmlhttp_on",
				"title" => $lang->asb_xmlhttp_on_title,
				"description" => $lang->asb_xmlhttp_on_description,
				"optionscode" => "text",
				"value" => '0'
			)
		)
	);
}

It is important to note both that we must globalize $lang and load the asb_addon language pack and also that the asb_xmlhttp_on_title and asb_xmlhttp_on_description language variables are shared by all AJAX-ready modules-- so no need to recreate them and everything can remain consistent.

The Return Value

As I've mentioned, the _xmlhttp() function returns the contents of the side box, but if there is no content, the module should return nochange as its value to signal that nothing needs to be updated.

This is in place to allow you to do some less intensive checking before you attempt to build the same content after each refresh. For example, the latest threads module can check the dateline argument against a quick query for the latest thread that was posted and quickly determine if anything new has been posted. If so, then call the intermediary function; if not, return nochange.

Once you have all of these things in place your module is now AJAX-ready. Just create an instance, set a valid refresh rate and then watch it work. 😄

For a working version, look here: AJAX Example

Next Topic

Using JavaScript Refresh