Follow
Drupal’s JavaScript coding standards
See also
Foswiki:Development/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 %EXPORTEDPREFERENCES%).
Avoid Internet Explorer errors
Metadata
Use
JQueryMetadata to integrate jQuery plugins into Foswiki.
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() {
// initializer
});
use
$(".jqPluginName").livequery(function() {
// 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. However be warned that
livequery
can be very slow on very large pages, especially on internet explorer.
See
JQueryMetadata for a more thorough example of using metadata and livequery