Since the October 2011 release of DokuWiki, codenamed “Angua”, our homegrown set of JavaScript utility functions was replaced with the well known jQuery library. This FAQ tries to cover all questions plugin and template authors might have relating to their use of JavaScript.

We encourage plugin and template authors to look into these issues ASAP, because the compatibility layers currently in use will soon go away.

jQuery is a well known, widely used and tested library. It is well documented and makes JavaScript development much easier. Supporting jQuery was an often requested feature by 3rd party plugin and template developers. Using jQuery should lower entry barriers for new DokuWiki developers creating new, modern user interfaces.

“Angua” will ship with jQuery 1.6.4, future DokuWiki releases will ship with newer jQuery releases. We're going to focus on stability rather than bleeding edge on future library upgrades, so it might not always be the most recent jQuery version. We also include jQuery UI 1.8.16 with “Angua” with all components included.

You can query the available versions with jQuery().jquery and jQuery().ui.version.

If your plugin or template doesn't use any JavaScript, then it obviously isn't affected by the change at all.

Note: The compatibility wrappers / layer for deprecated JavaScript functions (since Autumn 2011 “Angua” release) have been removed with the Spring 2013 “Weatherwax” release. If your plugin uses deprecated JavaScript, you need to update it (see below).

Freshly installed “Angua” and “Adora Belle” releases trigger warning messages about deprecated JavaScript calls (by compatibility layer) that you can inspect in the Firebug error console or the Chrome inspector. Most of the warnings will give you a hint how to replace the deprecated code with jQuery functions:

(“Weatherwax” and “Binky” do not support the compatibility layer any more, but you can reactivate it - no hints here because this might be misunderstood as “how to still use old plugins”; if you want to fix old plugins you should have the knowledge to find your way)

Here are the most commonly used, deprecated bits from our old library and some simple examples how to replace them with jQuery features.

as a shortcut to document.getElementById('…') - use jQuery's selectors instead, namely jQuery('#…').

• Note that $() is not (and never was) the jQuery shortcut, jQuery is only available in it's long form of jQuery().

/* Old code */
var obj = $('some__id');
// obj now is a DOM object
 
/* New code */
var $obj = jQuery('#some__id');
// $obj is a jQuery object - if you really need the DOM object use [0] e.g.:
var obj = $obj[0];

use jQuery's selectors instead

/* Old code */
var htmlelements = getElementsByClass( 'class', document, 'tag');
// htmlelements now is an array of DOM elements
for(var n in htmlelements ) {
  dosomething( htmlelements[n] );
}
 
/* New code */
jQuery('tag.class').each(function(){
    dosomething(this);
});
 
/* Or, this new code */
let $jqueryelements = jQuery('tag.class');
// $jqueryelements is a jquery thing: an array plus some other stuff.
$jqueryelements.each(function(){
    dosomething(this);
});
/* or, if you prefer (I don't know wich one is better) */
for (let n = 0; n < $jqueryelements.length; ++n ) {
    dosomething($jqueryelements[n]);
}

• It common to start the variable which contain a jQuery object with a $-character, but it is not required.

registering callbacks to be run when the DOM is ready to be used - use jQuery's callback mechanism instead.

/* Old code */
addInitEvent(function(){
    alert("DOM is ready");
});
 
/* New code */
jQuery(function(){
    alert("DOM is ready");
});

Registering event handlers - use jQuery's event methods instead.

/* Old code */
addEvent(obj, "click", function(){ 
    alert("Click happened!")
});
 
/* Recenter old code */
jQuery(obj).click(function(){ 
    alert("Click happened!") 
});
 
/* New code */
jQuery(obj).on("click", function(){ 
    alert("Click happened!") 
});

• replace “click” by the event you need e.g. “change”, “blur”, “focus” and the like (see jQuery link above)

executing AJAX requests - use jQuery's AJAX methods instead.

/* Old code */
sack = new sack(DOKU_BASE + 'lib/exe/ajax.php');                                                        
sack.AjaxFailedAlert = '';                                                                              
sack.encodeURIString = false;
sack.runAJAX('call=linkwiz&q='+encodeURI(value));
 
/* New code */
jQuery.post(
    DOKU_BASE + 'lib/exe/ajax.php',
    { call: 'linkwiz', q: value }
);

Please see javascript which has been updated with some jQuery specific rules.

If you really want to support old (pre-“Angua”) DokuWiki versions, you should have two versions of your plugin. The easiest way is to simply save your current plugin version (or tag it in your code revision system) and then upgrade your plugin to jQuery. Then add a link to the old, outdated version to your plugin's page.

Please refrain from supporting jQuery and non-jQuery in the same plugin version, as this increases code size and decreases maintainability. This means you should not add any own compatibility wrappers to your plugin. We already have compatibility wrappers in place for a whole year. Users should be encouraged to upgrade their old DokuWiki versions instead of making it easy for them to be lazy .

You do not necessarily rewrite all your DOM-Manipulation to make use of jQuery. But when replacing deprecated functions you might encounter places where jQuery makes DOM manipulation much easier using less code than with native DOM functions, in such cases consider rewriting your code with jQuery.

Please avoid the use of any unnecessary jQuery plugin. We already provide the full jQuery UI library which should cover most of your needs already. We might add commonly used/requested plugins to the core later - please write to the mailinglist if you think something should be added.

If you really want to use a plugin, it should be given a common, canonical name and loaded with our include_once syntax for JavaScript. The filename should be prefixed with jquery. and not contain any version numbers. This way multiple plugins can share the same jQuery plugin. Please do not use minified versions of the jQuery plugin - we're using our own minifier that can be easily disabled for debugging purposes.

For example, if you want to use the qTip jQuery plugin, choose “Development - Uncompressed source code” from the download page. The resulting filename (eg. jquery.qtip-1.0.0-rc3.js)) then has to be renamed to jquery.qtip.js and placed in your plugin folder. Then load it from your plugin's main script like this:

/* DOKUWIKI:include_once jquery.qtip.js */

Yes, of course. Simply override our default jQuery UI CSS in your own template CSS files. The default theme used by DokuWiki can be found in lib/scripts/jquery/jquery-ui-theme/smoothness.css. Do not edit this file! Override styles in your own template instead.

• override styles in CSS of your template. See also dokuwiki stylesheets for details.