JQueryCodingStandards

Follow Drupal’s JavaScript coding standards

See also UsingJQueryWithFoswiki for more information, tips and tricks.

Wrap $

When writing a jQuery plugin, if you want to use the jQuery $ variable, you have to wrap your code like this:

(function($) {

  // code using $ variable

})(jQuery);

If you fail to wrap your code, you will end up with $ being reported as an undefined variable, or even some other more obscure and hard to debug error if other libraries are also loaded.

JQueryPlugin itself does not use the $ variable, so will not conflict with other javascript libraries that may be loaded.

Scripts that use $ that are pasted by users into topics (inside <script> tags) will work as written, so long as the plugin configuration setting {JQueryPlugin}{NoConflict} is set to 0 (the default). If it is set to 1, scripts using $ that are pasted into topics will have to be wrapped as described here.

We recommend that scripts using $ are always wrapped.

Shorthands

Use the jQuery shorthand $ where possible:

$(function() { ... });

instead of

$(document).ready(function() { ... });

Global variables

If you want to use global variables within the scope of your code, wrap your code like this:

(function() {

  var foo = 'bar'; // yay, it's almost like I'm global

})();

If you want to use global variables in the global scope, put the variable in the foswiki namespace:

foswiki.foo = 'bar';

Mind the predefined global variables. See next section.

Propagating perl settings to javascript

The standard foswiki library initializes the global foswiki object with a subset of preference settings from foswiki, SCRIPTURLPATH, SCRIPTSUFFIX, and PUBURLPATH. These are sufficient to call scripts on the server and build attachment URLs. They are accessed using the foswiki.getPreference method:

var pubUrlPath = foswiki.getPreference('PUBURLPATH');

In addition, the JQuery foswiki plugin adds the macros specified by the global EXPORTEDPREFERENCES preference (currently PUBURL, PUBURLPATH, SCRIPTSUFFIX, SCRIPTURL, SCRIPTURLPATH, SERVERTIME, SKIN, SYSTEMWEB, TOPIC, USERNAME, USERSWEB, WEB, WIKINAME, WIKIUSERNAME, NAMEFILTER).

For local parameters however, use HTML 5 data attributes to pass parameters from Foswiki to a jQuery plugin. For example:

<div class="jqPluginName" data-param1="value1" data-param2="value2">
</div>

The plugin code will then use $(".jqPluginName").data() to extract the parameters as a JSON object.

LiveQuery

Normally when using jQuery you initialise plugins on HTML elements in a $(document).ready() call, using the jQuery each method to iterate over elements matching a selector. This works fine so long as all HTML elements are loaded when the page is loaded. Any elements that are loaded later - for example, as the result of an AJAX call, won't be initialised. In this case, you should use JQueryLiveQuery, which will take care of initialising dynamically loaded elements automatically.

Instead of:

$(".jqPluginName").each(function() {
  var opts = $(this).data();
  // initializer
});

use

$(".jqPluginName").livequery(function() {
  var opts = $(this).data();
  // initializer
});

Bear in mind that a page containing your script might end up being loaded by another page using a dynamic AJAX request. So ideally, you would use livequery on all elements all of the time.