Streamline JavaScript addition and add settings storage

Tweaked it a bit to use Drupal.settings instead of Drupal. Removed the theme function as script tags don't need to be themed.

(Changed title to better reflect what this patch does)

Rerolled against HEAD (due to http://drupal.org/node/73961).

Changed the patch in huge parts. It now uses the same system as drupal_add_css() (different 'layers').

Here is the (very comprehensive) documentation for the new

drupal_add_js<code>: (Note that the function itself is not that complex)

<code>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 ('core', 'module' and 'theme'):
  Adds a reference to a JavaScript file to the page header. JavaScript files are placed in a certain order
  from 'core' first, to 'module' and finally 'theme' so that files that are later added, can override
  previously added files with ease.

- Add inline JavaScript code ('page'):
  Executes a piece of JavaScript code on the current page by placing the code directly in the head of 
  the page. This can, for example, be useful to tell the user that a new message arrived using a pop up, 
  alert box or similar method.

- Call a JavaScript function ('call'):
  Generates a Javascript call, while importing the arguments as is. PHP arrays are turned into JS objects 
  to preserve keys. This means the array keys must conform to JS's member naming rules.

- 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. The settings will be accessible at Drupal.settings[$flag].

@param $data
  (optional) If given, the value depends on the $type parameter:
  - 'core', 'module' or 'theme': The path to the JavaScript file relative to the base_path().
  - 'page': The JavaScript code that should be placed directly in the head of the page.
  - 'setting': An array with configuration options as associative array.
  - 'call': The name of the function that should be called on page load.     
@param $type
  (optional) The type of JavaScript that should be added to the page. Allowed values are 'core',
  'module', 'theme', 'page', 'setting' and 'call'.
@param $flag
  (optional) The value of this parameter depends on the $type parameter:
  - 'core', 'module', 'theme' and any undefined value: Sets whether the JavaScript file should be
    cached (TRUE, default value) or loaded anew on every page (FALSE).
  - 'setting': The name of the module that adds settings to the page.
  - 'page' and 'call': The value should be omitted.
@param ...
  (optional) If the parameter $type is set to 'call', every further parameter after $type is passed
  as an argument to the function called in the page header.
@return
  The JavaScript array that has been built so far.

Fixed a misnamed variable. In one place, I had 'arguments' and in the other, I had 'parameters'.

I forgot to mention that I replaced drupal_call_js() with drupal_add_js('function', 'call' [, parameters]).

Argh, patch didn't get attached. Here it is.

Made the PHPDoc comment wrap at column 80.

The call function has been there before, as drupal_call_js(). It is required by some contributed modules. The settings function is pretty important for future JavaScript modules. See for example http://drupal.kkaefer.com/ for an example of how settings can be used.

Rerolled against HEAD. Changed array_merge to array_merge_recursive to prevent overwriting settings.

Patch still applies.

Next, timcn, you forgot your settings.php in there ;-)

I actually can't find any settings.php rules in the patch.

What if mutlipe JS files define settings? That seems to overwrite each other.

In drupal_add_js(), no HTML code is generated. The values are just merged into the global (static actually) settings array. The code for settings is generated in drupal_get_js() when all modules have merged their settings into the array. That means, all settings are there. I am successfully running this patch with quite some JavaScript code (from different modules) for my SoC project.

Also, what about Google Analytics? Why? Well, that places code that goes in the *footer*, just before , same with other modules that place JS in the $closure. How would that work?

You're right. There is definitely a need to add JavaScript code to the $closure. We should figure out, in what places it makes sense to position JavaScript code.

Updated the patch. Note that settings was not broken before. The arrays were merged together so that only one Drupal.settings was required.

Changes

• Scopes allow you to insert your code in other locations than the head of the page. The default scope is 'header', but there is also a scope called 'footer' available. Themes can define and use arbitrary scopes.
• Removed $type = 'call' as it is probably easier to write drupal_add_js('alert("message")', 'inline'); than using the parameter construction.
• Renamed page to inline as it is easier to understand.
• Reworked the setting type:
  • It now uses a cool JavaScript function to extend the JavaScript Drupal object
  • You might now want to wrap your settings into another variable in order to prevent the pollution of the Drupal.settings namespace.
  • array_merge_recursive is now only called once. Before, it was called whenever you added a setting.
• Added the ability to defer the execution of JavaScript code. Take a look at the MSDN page if you don’t know what that means.
• The parameter $flags is not overloaded anymore.

I forgot to mention that I will work on JavaScript localization once this patch is in core.

Damn, forgot a print_r() in the code.

Rerolled the patch.

You're right. I changed the documentation for 'inline'. Thanks for testing.

Fixed a wrong indentation in drupal.js and took a file out that has nothing to do here ;)

Rerolled the patch to remove fuzziness. Setting this RTBC.

As per Steven's request, here is a documentation patch for Drupal.extend().

As per Steven's request, here is a documentation patch for Drupal.extend().

Well, actually objects can contain functions and variables. While functions are also objects, variables are not.

Updated the module upgrade page.

Updated the documentation patch with m3avrck's suggestion.

Just discovered that a variable has been misnamed.