%META:TOPICINFO{author="ProjectContributor" date="1730892243" format="1.1" version="1"}%
%META:TOPICPARENT{name="JQueryPlugin"}%
---+!! %TOPIC%

%TOC%

%STARTINCLUDE%
Follow [[http://drupal.org/node/172169][Drupal&#8217;s JavaScript coding standards]]

See also [[https://foswiki.org/Development/UsingJQueryWithFoswiki][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%).

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

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

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

---++ <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() {
  var opts = $(this).data();
  // initializer
});
</verbatim>

use

<verbatim class="js">
$(".jqPluginName").livequery(function() {
  var opts = $(this).data();
  // 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. 
%STOPINCLUDE%

%META:PREFERENCE{name="TOPICTITLE" title="TOPICTITLE" type="Local" value="JQuery Coding Standards"}%
