jQ

*** See #315100: Allow to add JS/CSS libraries (sets of files, settings, and dependent libraries) for the patch to put jQ in core! ***

The jQ module allows other modules to register jQuery plugins in a central repository, and allows administrators of a site to enable or disable specific plugins globally.

The concept behind this module is to create a basic hook structure for jQuery wrapper modules, allowing other modules using these plugins to invoke them in a consistent fashion.

(Drupal 6 version only): You can also simply add new jQuery plugin files in your /plugins or /sites/example.com/plugins directory, and they'll be added to the registry. Then, for example, if you upload jquery.example.js, you could just jq_add('jquery.example'); and you're off. Additionally, if you have a .js and .css file with the same base name there, they'll both be added with the same call. Caveat: if you have two plugins with the same base name, there are no guarantees which will be added to the registry. Better off defining a hook_jq function in that case (see below for information on that).

Kudos to jjeff for his work on the jQuery Plugin Handler (JQP) module that inspired this latest functionality.

Current modules that support jQ:

• hoverIntent
• jCarousel
• Block Refresh
• jQuery Media
• jMedia
• Magnifier
• jQuery Plugins (which includes the Metadata and Validation plugins)
• jQuery Valid8

Current modules supported using the included jQ Bridge module:

• jQuery Form (which is included as part of core in Drupal 6)
• Cluetip (which favors a dependency on hoverIntent, but provides its own version if that module is not included)

The basic call to invoke a registered jQuery plugin on a page would be something like the following:

  jq_add('plugin-2'); 

This would load any files required by the plugin, unless an administrator has turned off the plugin manually.

The module defining the plugin would need at the least to provide the following hook:

function my_module_jq($op, $plugin = NULL) {
  switch ($op) {
    case 'info':
      return array(
      	'plugin-1' => array(
      		'name' => t('Plugin One'),
      		'description' => t('This is the Plugin One jQuery plugin. It can make your coffee.'),
                'version' => 'r5 // 2008-01-01 // jQuery 1.1.2',
                'url' => 'http://plugins.jquery.com/project/plugin-1',
      		'files' => array(
      			'js' => array(
      				drupal_get_path('module', 'my_module') . '/js/plugin-1.js',
      			),
      		),
      	),
      	'plugin-2' => array(
      		'name' => t('Plugin Two'),
      		'description' => t('This is the Plugin Two jQuery plugin. It can be found at !link.', array('!link' => l('jQuery Plugins', 'http://jquery.com/plugins/repository/whatever'))),
      		'files' => array(
      			'js' => array(
      				drupal_get_path('module', 'my_module') . '/js/plugin-2-min.js',
      				drupal_get_path('module', 'my_module') . '/js/plugin-2-additional.js',
      			),
      			'css' => array(
      				drupal_get_path('module', 'my_module') . '/css/plugin-2.css',
      			),
      		),
      	),
      );
    case 'add':
    	// any additional processing required when adding a plugin to a page.
    	switch ($plugin) {
    		case 'plugin-1':
    			// fancy code here...
    			break;
    	}
    break;
  }
}

In the future, we might add additional functionality, if we can identify other uses to simplify the jQuery invocation process, such as when jQuery calls are added inline.