function drupal_add_library

You are here

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