1 common.inc backdrop_add_js($data = NULL, $options = NULL)

Adds a JavaScript file, setting, or inline code to the page.

The behavior of this function depends on the parameters it is called with. Generally, it handles the addition of JavaScript to the page, either as reference to an existing file or as inline code. The following actions can be performed using this function:

  • Add a file ('file'): Adds a reference to a JavaScript file to the page.
  • Add inline JavaScript code ('inline'): Executes a piece of JavaScript code on the current page by placing the code directly in the page (for example, to tell the user that a new message arrived, by opening a pop up, alert box, etc.). This should only be used for JavaScript that cannot be executed from a file.
  • Add external JavaScript ('external'): Allows the inclusion of external JavaScript files that are not hosted on the local server. Note that these external JavaScript references do not get aggregated when preprocessing is on.
  • Add settings ('setting'): Adds settings to Backdrop's global storage of JavaScript settings. Per-page settings are required by some modules to function properly. All settings will be accessible at Backdrop.settings.

Examples:

  backdrop_add_js('core/misc/collapse.js');
  backdrop_add_js('core/misc/collapse.js', 'file');
  backdrop_add_js('jQuery(document).ready(function () { alert("Hello!"); });', 'inline');
  backdrop_add_js('jQuery(document).ready(function () { alert("Hello!"); });',
    array('type' => 'inline', 'scope' => 'footer', 'weight' => 5)
  );
  backdrop_add_js('http://example.com/example.js', 'external');
  backdrop_add_js(array('myModule' => array('key' => 'value')), 'setting');

Calling backdrop_static_reset('backdrop_add_js') will clear all JavaScript added so far.

If JavaScript aggregation is enabled, all JavaScript files added with $options['preprocess'] set to TRUE will be merged into one aggregate file. Preprocessed inline JavaScript will not be aggregated into this single file. Externally hosted JavaScripts are never aggregated.

The reason for aggregating the files is outlined quite thoroughly here: http://www.die.net/musings/page_load_time/ "Load fewer external objects. Due to request overhead, one bigger file just loads faster than two smaller ones half its size."

$options['preprocess'] should be only set to TRUE when a file is required for all typical visitors and most pages of a site. It is critical that all preprocessed files are added unconditionally on every page, even if the files are not needed on a page. However, it is preferred that modules do not use this function, but declare JS files intended for all pages in their .info file instead.

Non-preprocessed files should only be added to the page when they are actually needed.

@since 1.27.0 The 'browsers' option is deprecated.

Parameters

$data: (optional) If given, the value depends on the $options parameter, or $options['type'] if $options is passed as an associative array:

  • 'file': Path to the file relative to base_path().
  • 'inline': The JavaScript code that should be placed in the given scope.
  • 'external': The absolute path to an external JavaScript file that is not hosted on the local server. These files will not be aggregated if JavaScript aggregation is enabled.
  • 'setting': An associative array with configuration options. The array is merged directly into Backdrop.settings. All modules should wrap their actual configuration settings in another variable to prevent conflicts in the Backdrop.settings namespace. Settings within the same namespace will be recursively merged together unless a "key" option is specified in the $options array.

$options: (optional) A string defining the type of JavaScript that is being added in the $data parameter ('file'/'setting'/'inline'/'external'), or an associative array.

  • type: The type of JavaScript that is to be added to the page. Allowed values are 'file', 'inline', 'external' or 'setting'. Defaults to 'file'.
  • key: Applies to the 'setting' and 'inline' types only. A string that identifies data that should only be added once per page. If omitted, multiple settings within the same namespace will be merged together recursively.
  • scope: The location in which you want to place the script. Possible values are 'header' or 'footer'. If your theme implements different regions, you can also use these. Defaults to 'header'.
  • group: A number identifying the group in which to add the JavaScript. Available constants are:

    The group number serves as a weight: JavaScript within a lower weight group is presented on the page before JavaScript within a higher weight group.

  • every_page: For optimal front-end performance when aggregation is enabled, this should be set to TRUE if the JavaScript is present on every page of the website for users for whom it is present at all. This defaults to FALSE. It is set to TRUE for JavaScript files that are added via module and theme .info files. Modules that add JavaScript within hook_init() implementations, or from other code that ensures that the JavaScript is added to all website pages, should also set this flag to TRUE. All JavaScript files within the same group and that have the 'every_page' flag set to TRUE and do not have 'preprocess' set to FALSE are aggregated together into a single aggregate file, and that aggregate file can be reused across a user's entire site visit, leading to faster navigation between pages. However, JavaScript that is only needed on pages less frequently visited, can be added by code that only runs for those particular pages, and that code should not set the 'every_page' flag. This minimizes the size of the aggregate file that the user needs to download when first visiting the website. JavaScript without the 'every_page' flag is aggregated into a separate aggregate file. This other aggregate file is likely to change from page to page, and each new aggregate file needs to be downloaded when first encountered, so it should be kept relatively small by ensuring that most commonly needed JavaScript is added to every page.
  • weight: A number defining the order in which the JavaScript is added to the page relative to other JavaScript with the same 'scope', 'group', and 'every_page' value. In some cases, the order in which the JavaScript is presented on the page is very important. jQuery, for example, must be added to the page before any jQuery code is run, so jquery.js uses the JS_LIBRARY group and a weight of -20, jquery.once.js (a library backdrop.js depends on) uses the JS_LIBRARY group and a weight of -19, backdrop.js uses the JS_LIBRARY group and a weight of -1, other libraries use the JS_LIBRARY group and a weight of 0 or higher, and all other scripts use one of the other group constants. The exact ordering of JavaScript is as follows:

    • First by scope, with 'header' first, 'footer' last, and any other scopes provided by a custom theme coming in between, as determined by the theme.
    • Then by group.
    • Then by the 'every_page' flag, with TRUE coming before FALSE.
    • Then by weight.
    • Then by the order in which the JavaScript was added. For example, all else being the same, JavaScript added by a call to backdrop_add_js() that happened later in the page request gets added to the page after one for which backdrop_add_js() happened earlier in the page request.
  • defer: If set to TRUE, the defer attribute is set on the <script> tag. Defaults to FALSE. Note that setting this to TRUE will disable preprocessing as though the 'preprocess' option was set to FALSE.
  • attributes: An associative array of attributes for the <script> tag. This may be used to add 'async' or custom attributes. Note that setting any attributes will disable preprocessing as though the 'preprocess' option was set to FALSE.
  • cache: If set to FALSE, the JavaScript file is loaded anew on every page call; in other words, it is not cached. Used only when 'type' references a JavaScript file. Defaults to TRUE.
  • preprocess: If TRUE and JavaScript aggregation is enabled, the script file will be aggregated. Defaults to TRUE.
  • browsers: An array containing information specifying which browsers should load the JavaScript item. See backdrop_pre_render_conditional_comments() for details. This option is deprecated and no longer has an effect.

Return value

array: The current array of JavaScript files, settings, and in-line code, including Backdrop defaults, anything previously added with calls to backdrop_add_js(), and this function call's additions.

See also

backdrop_get_js()

File

core/includes/common.inc, line 4680
Common functions that many Backdrop modules will need to reference.

Code

function backdrop_add_js($data = NULL, $options = NULL) {
  $javascript = &backdrop_static(__FUNCTION__, array());

  // Construct the options, taking the defaults into consideration.
  if (isset($options)) {
    if (!is_array($options)) {
      $options = array('type' => $options);
    }
  }
  else {
    $options = array();
  }
  $options += backdrop_js_defaults($data);

  // Preprocess can only be set if caching is enabled and no attributes
  // nor defer tag are set.
  $options['preprocess'] = $options['cache'] && empty($options['attributes']) && empty($options['defer']) ? $options['preprocess'] : FALSE;

  // Tweak the weight so that files of the same weight are included in the
  // order of the calls to backdrop_add_js().
  $options['weight'] += count($javascript) / 1000;

  // Add an every page weight for sorting.
  $options['every_page_weight'] = $options['every_page'] ? -1 : 1;

  if (isset($data)) {
    // Add jquery.js and backdrop.js, as well as the basePath setting, the
    // first time a JavaScript file is added.
    if (empty($javascript)) {
      // url() generates the prefix using hook_url_outbound_alter(). Instead of
      // running the hook_url_outbound_alter() again here, extract the prefix
      // from url().
      $prefix = '';
      url('', array('prefix' => &$prefix));
      $javascript = array(
        'settings' => array(
          'data' => array(
            array('basePath' => base_path()),
            array('pathPrefix' => empty($prefix) ? '' : $prefix),
          ),
          'type' => 'setting',
          'scope' => 'header',
          'group' => JS_SETTING,
          'every_page' => TRUE,
          'weight' => 0,
          'browsers' => array(),
        ),
        'core/misc/backdrop.js' => array(
          'data' => 'core/misc/backdrop.js',
          'type' => 'file',
          'scope' => 'header',
          'group' => JS_LIBRARY,
          'every_page' => TRUE,
          'weight' => -1,
          'preprocess' => TRUE,
          'cache' => TRUE,
          'defer' => FALSE,
          'attributes' => array(),
          'browsers' => array(),
          'version' => BACKDROP_VERSION,
        ),
      );
      // Backwards-compatibility for JavaScript.
      if (!empty($GLOBALS['settings']['backdrop_drupal_compatibility'])) {
        $javascript['settings']['data'][] = array('drupalCompatibility' => TRUE);
      }

      // Register all required libraries.
      backdrop_add_library('system', 'jquery', TRUE);
      backdrop_add_library('system', 'jquery.once', TRUE);
    }

    switch ($options['type']) {
      case 'setting':
        // All JavaScript settings are placed in the header of the page with
        // the library weight so that inline scripts appear afterwards.
        if (isset($options['key'])) {
          $javascript['settings']['data'][$options['key']] = $data;
        }
        else {
          $javascript['settings']['data'][] = $data;
        }
        break;

      case 'inline':
        if (isset($options['key'])) {
          $javascript[$options['key']] = $options;
        }
        else {
          $javascript[] = $options;
        }
        break;

      default: // 'file' and 'external'
        // Local and external files must keep their name as the associative key
        // so the same JavaScript file is not added twice.
        $javascript[$options['data']] = $options;
    }
  }
  return $javascript;
}