A Labor of Love Part Deux – Creating the A-Z Directory Module Version Deux

This post references the original development effort to create the A-Z Directory module. Version 2 of the module was released this past Saturday and I wanted to take this opportunity to document lessons learned and to explain why version 1 is not compatible with version 2.

I have been humbled and honored that the open source community is reaching out to me for suggestions and feedback for future versions of the A-Z Directory module. I got suggestions to hyperlink the phone numbers, have configurable labels, and add icons.

With each update, I had to modify both the PHP template and the Javascript template. This had several disadvantages.

  1. Prohibits a developer’s ability to create a template override for the output of the contact information.
  2. Built-in security measures like Joomla’s email cloaking plug-in did not translate to the Javascript template.
  3. I had to maintain twice as much code. More code = more bugs.

I needed to maintain the Ajax call, but draw the output from the PHP template or from a template override. The key was to check for the existence of a template override first, and if one wasn’t found, load the module’s PHP template. Joomla has a built-in function that does just that:

require_once JModuleHelper::getLayoutPath( 'mod_azdirectory' );

Still using Joomla’s com_ajax component, the Ajax call is the same as before:

var request = {
'option' : 'com_ajax',
'module' : 'azdirectory',
'method' : 'getContacts',
'data' : letter,
'format' : 'json'
var jqxhr = jQuery.ajax({
method : 'get',
data : request,
dataType : 'json'

Now, within jQuery’s “done” callback, I am replacing the contents of the module’s parent div with the HTML output of the module’s PHP template or from a template override:

jqxhr.done( function( msg ) {
jQuery( '#modazdirectory' ).replaceWith( msg );

However, the event handlers—like clicking the last name letter—are no longer bound to the elements because the DOM was replaced. To correct this, I had to re-bind the event handlers by calling the appropriate functions within the “done” callback.

As I mentioned in the version history, these changes are not compatible with earlier versions only if you are using a template override.

Additional Resources