function drupal_add_library

7 common.inc drupal_add_library($module, $name, $every_page = NULL)
8 common.inc drupal_add_library($module, $name, $every_page = NULL)

Adds multiple JavaScript or CSS files at the same time.

A library defines a set of JavaScript and/or CSS files, optionally using settings, and optionally requiring another library. For example, a library can be a jQuery plugin, a JavaScript framework, or a CSS framework. This function allows modules to load a library defined/shipped by itself or a depending module, without having to add all files of the library separately. Each library is only loaded once.

Parameters

$module: The name of the module that registered the library.

$name: The name of the library to add.

$every_page: Set to TRUE if this library is added to every page on the site. Only items with the every_page flag set to TRUE can participate in aggregation.

Return value

TRUE if the library was successfully added; FALSE if the library or one of its dependencies could not be added.

See also

drupal_get_library()

hook_library()

hook_library_alter()

13 calls to drupal_add_library()
drupal_add_js in includes/common.inc
Adds a JavaScript file, setting, or inline code to the page.
drupal_add_tabledrag in includes/common.inc
Assists in adding the tableDrag JavaScript behavior to a themed table.
drupal_process_attached in includes/common.inc
Adds attachments to a render() structure.
JavaScriptTestCase::testLibraryAlter in modules/simpletest/tests/common.test
Adds a JavaScript library to the page and alters it.
JavaScriptTestCase::testLibraryRender in modules/simpletest/tests/common.test
Adds a library to the page and tests for both its JavaScript and its CSS.

... See full list

2 string references to 'drupal_add_library'
JavaScriptTestCase::setUp in modules/simpletest/tests/common.test
Sets up a Drupal site for running functional and integration tests.
overlay_render_region in modules/overlay/overlay.module
Renders an individual page region.

File

includes/common.inc, line 4681
Common functions that many Drupal modules will need to reference.

Code

function drupal_add_library($module, $name, $every_page = NULL) {
  $added = &drupal_static(__FUNCTION__, array());

  // Only process the library if it exists and it was not added already.
  if (!isset($added[$module][$name])) {
    if ($library = drupal_get_library($module, $name)) {
      // Add all components within the library.
      $elements['#attached'] = array(
        'library' => $library['dependencies'],
        'js' => $library['js'],
        'css' => $library['css'],
      );
      $added[$module][$name] = drupal_process_attached($elements, JS_LIBRARY, TRUE, $every_page);
    }
    else {
      // Requested library does not exist.
      $added[$module][$name] = FALSE;
    }
  }

  return $added[$module][$name];
}

Comments

Posted by jim0203 on

It is mentioned, but it would be good to be clearer about the fact that the libraries need to have been defined by hook_library().

Posted by skomorokh on

You can find out which libraries are available from a module via drupal_get_library(), I used something like: dpm(drupal_get_library('system'));

This I learned after attempting to re-use the jQuery BBQ library from core. I had blindly googled about and found a few places mentioning this: drupal_add_library('overlay', 'jquery-bbq');

Whereas in the release it's: drupal_add_library('system', 'jquery.bbq');

Posted by shafiul on

Where do I call this function? In my module or template files or pre-processor functions?

Posted by jackbravo on

you can add it on the preprocess_html (theme) or in the hook_init function if you are including the library in all pages or just on the hook function you are using the library (module).

Posted by Dorian on

This is so abstract for me. Could someone post a nice example of how to add a jqueryplugin of a cusom module with this library api...

That would be awesome!

Posted by mattsmith3 on

use hook_init in the .module file.

function my_module_init() {
        drupal_add_library('system', 'ui.tabs');
}

other scripts (not jquery.ui... but custom module scripts) should be added via the .info file:

scripts[]   =    js/my_module.js

Posted by allenfantasy on

Just drag an example from a third-party module called "View Accordion", which I used to add the jQuery Accordion to my views:

//...
function pre_render($result) {
  drupal_add_library('system', 'ui.accordion');
  ...
}

Actually you can add a jQuery plugin library wherever you want in your theme:

function mytheme_preprocess_page($vars) {
  //prefix code
  drupal_add_plugin('system', 'ui.tabs');
  //suffix code
}

Or in your custom module, like this:

function mymodule_preprocess_node($vars) {
  drupal_add_library('system', 'ui.tabs');
}