CHAPTER 18 ■ USING JQUERY

Figure 18-6. After the Show Blocks button is clicked, blocks become visible.

Overridable JavaScript

The code in blockaway.module is simple and easy to understand. It just makes sure the blockaway.js file is included. However, if the module were more complicated, it would be friendlier to others to put the drupal_add_js() function call in a theme function instead of in hook_init(). That way, those who wanted to use your module but customize the JavaScript code in some way could do so without touching your module code at all (see Chapter 9 for how the theme system works its magic). The code that follows is a revised version of blockaway.module that declares a theme function using hook_theme(), moves the drupal_add_js() call into the theme function, and calls the theme function from hook_init(). The functionality is the same, but savvy developers can now override the blockaway.js file.

<?php

/**

*@file

*Use this module to learn about jQuery.

*/

/**

* Implements hook_init(). */

402

CHAPTER 18 ■ USING JQUERY

function blockaway_init() { theme('blockaway_javascript');

}

/**

*Implements hook_theme().

*Register our theme function.

*/

function blockaway_theme() { return array(

'blockaway_javascript' => array( 'arguments' => array(),

),

);

}

/**

*Theme function that just makes sure our JavaScript file

*gets included.

*/

function theme_blockaway_javascript() { drupal_add_js(drupal_get_path('module', 'blockaway') .'/blockaway.js');

}

Let’s go ahead and see if this approach works. We’re going to override the JavaScript provided by the module with JavaScript provided by the theme. Copy sites/all/modules/custom/blockaway/ blockaway.js to your current theme—for example, themes/bartik/ blockaway.js. Let’s change the JavaScript file slightly so that we’ll know which JavaScript file is being used. Change the effect from slideDown("slow") to fadeIn(5000); this will fade in the blocks over a period of five seconds. Here is the new file:

/**

* Hide blocks in sidebars, then make them visible at the click of a button. */

jQuery(document).ready(function() {

//Get all div elements of class 'block' inside the left sidebar.

//Add to that all div elements of class 'block' inside the

//right sidebar.

var blocks = jQuery('#sidebar-first div.block, #sidebar-second div.block');

//Hide them. blocks.hide();

//Add a button that, when clicked, will make them reappear.

jQuery('#sidebar-first').prepend('<div id="collapsibutton">Show Blocks</div>'); jQuery('#collapsibutton').css({

'width': '90px', 'border': 'solid',

403

CHAPTER 18 ■ USING JQUERY

'border-width': '1px', 'padding': '5px', 'background-color': '#fff'

});

// Add a handler that runs once when the button is clicked. jQuery('#collapsibutton').one('click', function() {

//Button clicked! Get rid of the button. jQuery('#collapsibutton').remove();

//Display all our hidden blocks using an effect. blocks.fadeIn("5000");

});

});

The last change we need to make is to tell Drupal to load this new JavaScript file instead of the one in sites/all/modules/custom/blockaway. We do that by overriding the theme function. Add the following function to the template.php file of your theme (if your theme doesn’t have a template.php file, it’s okay to create one):

/**

*Override theme_blockaway_javascript() with the

*following function.

*/

function bartik_blockaway_javascript() { drupal_add_js(path_to_theme() . '/blockaway.js');

}

■ Note Change the name of the preprocess function so that it uses the name of the theme you are using. In the preceding example, I am using the Bartik theme.

Visit the Modules page to rebuild the theme registry so your changes will be recognized. When you visit a page in your web browser, you should see the Show Blocks button, and clicking it should reveal the blocks via a gradual fade-in effect instead of the slide effect we were using earlier. Congratulations! You’ve learned how to use jQuery in your module, how to write it in a way that is friendly to themers and other developers, and coincidentally, how to cleanly override or enhance JavaScript files provided by other module developers who have been equally courteous.

Before we leave this example, let me demonstrate how to override a template file. First, remove the bartik_blockaway_javascript() function that you added to the template.php file. Next, in your current theme, create an empty file called blockawayjavascript. tpl.php. For example, if you are using the Bartik theme, create themes/bartik/blockaway-javascript.tpl.php. Don’t put anything inside this file. Now visit the Modules page. The act of visiting this page will rebuild the theme registry. Drupal will find the template file and use it instead of the theme function in your module. The result is that blockaway.js will never be loaded; you’ve essentially commented out the theme function by creating an empty template file (recall from Chapter 9 that, when building the theme registry, Drupal will look for a template file and then for theme functions).

404