Index: includes/common.inc =================================================================== RCS file: /cvs/drupal/drupal/includes/common.inc,v retrieving revision 1.1041 diff -u -r1.1041 common.inc --- includes/common.inc 5 Nov 2009 16:19:25 -0000 1.1041 +++ includes/common.inc 6 Nov 2009 00:28:17 -0000 @@ -3550,33 +3550,27 @@ } /** - * Add a JavaScript file, setting or inline code to the page. + * Add 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. This can, for example, be useful to tell the user that - * a new message arrived, by opening a pop up, alert box etc. This should only - * be used for JavaScript which cannot be placed and executed from a file. - * When adding inline code, make sure that you are not relying on $ being jQuery. - * Wrap your code in (function ($) { ... })(jQuery); or use jQuery instead of $. - * - * - 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 a setting to Drupal's global storage of JavaScript settings. Per-page - * settings are required by some modules to function properly. All settings - * will be accessible at Drupal.settings. + * - 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. When adding inline code, make sure that you are not relying on + * $() being the jQuery function. Wrap your code in (function ($) { + * ... })(jQuery); or use jQuery() instead of $(). + * - 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 Drupal's global storage of + * JavaScript settings. Per-page settings are required by some modules to + * function properly. All settings will be accessible at Drupal.settings. * * Examples: * @code @@ -3592,61 +3586,56 @@ * Calling drupal_static_reset('drupal_add_js') will clear all JavaScript added * so far. * - * @param $data + * @param $data * (optional) If given, the value depends on the $options parameter: * - '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 array with configuration options as associative array. The - * array is directly placed in Drupal.settings. All modules should wrap - * their actual configuration settings in another variable to prevent - * the pollution of the Drupal.settings namespace. + * - 'setting': An associative array with configuration options. The + * array is directly placed in Drupal.settings. All modules should wrap + * their actual configuration settings in an array to prevent conflicts in + * the Drupal.settings namespace. * @param $options - * (optional) A string defining the type of JavaScript that is being added - * in the $data parameter ('file'/'setting'/'inline'), or an array which - * can have any or all of the following keys. JavaScript settings should + * (optional) A string defining the type of JavaScript that is being added in + * the $data parameter ('file'/'setting'/'inline'/'external'), or an array + * that can have any or all of the following keys. JavaScript settings should * always pass the string 'setting' only. - * - type - * The type of JavaScript that is to be added to the page. Allowed - * values are 'file', 'inline', 'external' or 'setting'. Defaults - * to 'file'. - * - scope - * The location in which you want to place the script. Possible values - * are 'header' or 'footer'. If your theme implements different regions, - * however, you can also use these. Defaults to 'header'. - * - weight - * A number defining the order in which the JavaScript is added to the - * page. In some cases, the order in which the JavaScript is presented - * on the page is very important. jQuery, for example, must be added to - * to the page before any jQuery code is run, so jquery.js uses a weight - * of JS_LIBRARY - 2, drupal.js uses a weight of JS_LIBRARY - 1, and all - * following scripts depending on jQuery and Drupal behaviors are simply - * added using the default weight of JS_DEFAULT. - * - * Available constants are: - * - JS_LIBRARY: Any libraries, settings, or jQuery plugins. - * - JS_DEFAULT: Any module-layer JavaScript. - * - JS_THEME: Any theme-layer JavaScript. - * - * If you need to invoke a JavaScript file before any other module's - * JavaScript, for example, you would use JS_DEFAULT - 1. - * Note that inline JavaScripts are simply appended to the end of the - * specified scope (region), so they always come last. - * - defer - * If set to TRUE, the defer attribute is set on the <script> tag. - * Defaults to FALSE. - * - cache - * If set to FALSE, the JavaScript file is loaded anew on every page - * call, that means, it is not cached. Used only when 'type' references - * a JavaScript file. Defaults to TRUE. - * - preprocess - * Aggregate the JavaScript if the JavaScript optimization setting has - * been toggled in admin/config/development/performance. Note that - * JavaScript of type 'external' is not aggregated. Defaults to TRUE. - * @return - * The contructed array of JavaScript files. + * - type: The type of JavaScript that is to be added to the page. Allowed + * values are 'file', 'inline', 'external' or 'setting'. Defaults + * to 'file'. + * - 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'. + * - weight: A number defining the order in which the JavaScript is added to + * the page. In some cases, the order in which the JavaScript is presented + * on the page is very important. jQuery, for example, must be added to to + * the page before any jQuery code is run, so jquery.js uses a weight of + * JS_LIBRARY - 2, drupal.js uses a weight of JS_LIBRARY - 1, and all + * following scripts depending on jQuery and Drupal behaviors are simply + * added using the default weight of JS_DEFAULT. Available constants are: + * - JS_LIBRARY: Any libraries, settings, or jQuery plugins. + * - JS_DEFAULT: Any module-layer JavaScript. + * - JS_THEME: Any theme-layer JavaScript. + * If you need to invoke a JavaScript file before any other module's + * JavaScript, for example, you would use JS_DEFAULT - 1. Note that inline + * JavaScripts are simply appended to the end of the specified scope + * (region), so they always come last. + * - defer: If set to TRUE, the defer attribute is set on the <script> + * tag. Defaults 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: Aggregate the JavaScript if the JavaScript optimization + * setting has been toggled in admin/config/development/performance. Note + * that JavaScript of type 'external' is not aggregated. Defaults to TRUE. + * + * @return + * The current array of JavaScript files, settings, and in-line code, + * including Drupal defaults, anything previously added with calls to + * drupal_add_js(), and this function call's additions. + * * @see drupal_get_js() */ function drupal_add_js($data = NULL, $options = NULL) {