drupal_add_js

定義

drupal_add_js($data = NULL, $type = 'module', $scope = 'header', $defer = FALSE, $cache = TRUE)
includes/common.inc, 第 1600 行之後

描述

加入一個 JavaScript 的檔案、設定、或是程式碼到頁面中

根據不同的參數，會有不同的結果產生。一般，它會加入 JavaScript 的"檔案連結"或是"直接貼入程式碼"到網頁裡。以下列出不同的結果：

  • 加入一個檔案('core', 'module' and 'theme'): 加入一個連結到網頁中。排列的順有一定的規則， 'core' 最前面，再來是 'module' ，最後是 'theme'，就算加入 的時間比較晚，還是會依這個順序排列。
    例：

    drupal_addjs('js1.js', 'module');
    drupal_addjs('js2.js', 'core');

    因為 'core' 的順序在前面，所以 js2.js 會排在 js1.js 前面，會優先被讀入。
  • 加入一段程式碼 ('inline'): 貼入程式碼，如果目的不是引用一個 *.js 的檔案，而是一段 JavaScript 程式碼，就用這個參數。例如，開一個新視窗，或是跳出訊息視窗顯示一段訊息。
  • * 加入一個設定 ('setting'): 傳入一個變數的值。這個值會被放到名為 Drupal.settings 的陣列中，讓其它部分的 JavaScript 去呼叫它。

參數

$data (選擇性) 如果用到這個參數，它的內容的和後面的 $type 參數有關：

  • 'core', 'module' 或 'theme': 一個由網站根目錄算起的相對路徑(*.js 檔案)
  • 'inline': 一段 JavaScript 程式碼
  • 'setting': 一個關連陣列，將會被轉換為 Drupal.settings 下的物件

$type (選擇性) 一個表示要放到網頁裡的 JavaScript 是哪一種類型。可以是 'core', 'module', 'theme', 'inline' 和 'setting'。你也可以自訂一個名稱，這時 $data 的內容會被視為一個 JavaScript 檔案(*.js)路徑。預設值是 'module'
排列順序： 'core' -> 'module' -> 'theme' -> 'setting' -> 'inline' -> [自訂的名稱]

$scope (選擇性) JavaScript 程式要放置的位置，預設可以是 'header'(開頭) and 'footer'(節尾). 如果你所用的版型有定義其它的位置，也可以使用它們放到這個參數中。

$defer (選擇性) 如果為 TRUE，在 標籤中會加入 defer 屬性，預設為 FALSE。這個參數在 $type 是 'setting' 沒有作用。

$cache (選擇性) 如果設定為 FALSE， JavaScript 檔案會在每一次呼叫頁面的時候重新讀取，預設值是 TRUE，這個參數只對 $type 表示引入的是一個 JavaScript 檔案有用

值回值

如果第一個參數為 NULL，就會傳回和 $scope 同樣參數 JavaScript 陣列回來

範例

1. 引入檔案

drupal_add_js('test1.js', 'module');
drupal_add_js('test2.js', 'theme');
drupal_add_js('test3.js', 'core');

結果網頁原始檔的開頭部分可以找到類似下面的程式碼


由於 core 的較優先，所以會被排在前面先被讀入。

2. 加入程式碼 & 加入設定

drupal_add_js('alert("var1 = "+Drupal.settings.var1);', 'inline');
drupal_add_js(array('var1' => 123, 'var2' => 456), 'setting');

執行的時候，會跳出一個訊息視窗，顯示「var1 = 123」。

原始碼

<?php
function drupal_add_js($data = NULL, $type = 'module', $scope = 'header', $defer = FALSE, $cache = TRUE) {
if (!is_null($data)) {
_drupal_add_js('misc/jquery.js', 'core', 'header', FALSE, $cache);
_drupal_add_js('misc/drupal.js', 'core', 'header', FALSE, $cache);
}
return _drupal_add_js($data, $type, $scope, $defer, $cache);
}
?>

Drupal版本: