JQueryCodingStandards < System

---+!! %TOPIC%

%TOC%

<!--%JQREQUIRE{"chili"}%-->
%STARTINCLUDE%
Follow [[http://drupal.org/node/172169][Drupal&#8217;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:

<verbatim class="js">
(function($) {

  // code using $ variable

})(jQuery);
</verbatim>

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 =&lt;script&gt;= 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:

<verbatim class="js">
$(function() { ... });
</verbatim>

instead of 

<verbatim class="js">
$(document).ready(function() { ... });
</verbatim>

---++ Global variables

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

<verbatim class="js">
(function() {

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

})();
</verbatim>

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

<verbatim class="js">
foswiki.foo = 'bar';
</verbatim>

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:
<verbatim>
var pubUrlPath = foswiki.getPreference('PUBURLPATH');
</verbatim>

In addition, the JQuery =foswiki= plugin adds the macros specified by the
global =EXPORTEDPREFERENCES= preference (currently %EXPORTEDPREFERENCES%).

---++ Avoid Internet Explorer errors

   * Use an object if you need an associative array, not an array. [[http://ajaxian.com/archives/javascript-associative-arrays-considered-harmful][ [source&#93; ]]
   * Declare all local variables with =var= before they are used.
   * Remove trailing commas from array and object definitions, i.e.:
     <verbatim class="js">var object = { foo: 'bar' }</verbatim> not 
     <verbatim class="js">var object = { foo: 'bar', }</verbatim>

---++ Metadata

Use JQueryMetadata to integrate jQuery plugins into Foswiki.

---++ <nop>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:

<verbatim class="js">
$(".jqPluginName").each(function() {
  // initializer
});
</verbatim>

use

<verbatim class="js">
$(".jqPluginName").livequery(function() {
  // initializer
});
</verbatim>

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
%STOPINCLUDE%
This topic: System > JQueryPlugin > JQueryCodingStandards
Topic revision: 28 Sep 2011, ProjectContributor (raw view)
Copyright © by the contributing authors. All material on this site is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback