7 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 4724
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

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().

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');

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

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).

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!

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

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');
}

It tooks me a week to achieve this so i figured someone will find it usefull to read it on the first place i went to look for an answer.

Apparently, setting $every_page to FALSE wasn't enough, completely uneffective to be honest, to prevent the aggregation of my library (i was using ckeditor lib).
Eventualy i found a hint here http://drupalcontrib.org/api/drupal/contributions!libraries!libraries.ap... in the last example, with the undocumented (not that i could find at least) use of the the preprocess variant.

The solution was to specify directly inside the library if the .js file could support JS aggregation, in my case it ended like this:

<?php
$items
['ckeditor'] = array( 'title' => 'ckeditor', 'version' => '4.3.1',
'css' => array( "$path/content.css" => array()),
'js' => array( "$path/ckeditor.js" => array('preprocess' => FALSE)));
?>

that file is not going to be aggregated regardless the value of $every_page you will choose.

This function has been removed in Drupal 8. Adding a library to the page should now be done using the #attached property of a renderable array. @see Change Record https://drupal.org/node/2169605

It wasn't clear to me how to find the value for the $module parameter, "the name of the module that registered the library". Erm, how do I know what that is exactly? I will describe how I found out.

My initial code was:

<?php
/**
* Implements hook_init().
*/
function mymodule_init() {
   
$info = libraries_load('underscore');
   
$return = drupal_add_library('underscore', 'underscore');
   
   
$info = libraries_load('backbone');
   
$return = drupal_add_library('backbone', 'backbone');
}
?>

I had added libraries_load() and drupal_add_library() to my own hook_init(), but it wasn't working, so something was wrong, but where? Firstly I added variables $info and $return to be able to easily view in my IDE what the return values from each of the functions was. The $info returned valid data, but my drupal_add_library() calls were both returning 'false'. Progress, of a sort, to know where things were not working.

I looked at the $info array returned and that contained $info['module']. The value was 'quickedit', so I changed my code to use this in the drupal_add_library() call:

<?php
/**
* Implements hook_init().
*/
function mymodule_init() {
   
$info = libraries_load('underscore');
   
$return = drupal_add_library('quickedit', 'underscore');
   
   
$info = libraries_load('backbone');
   
$return = drupal_add_library('quickedit', 'backbone');
}
?>

That worked!

So, if you want to know what the value for the $module parameter is, check the $info['module'] value returned by libraries_load().