====== JavaScript ======
DokuWiki makes uses of [[wp>JavaScript]] to enhance the user experience. Like for [[css|stylesheets]] all JavaScript files are delivered through a single dispatcher to minimize HTTP requests, for caching and [[config:compress|compression]].
This page gives you an overview how JavaScript is loaded from DokuWiki core, [[:plugins]] and [[:templates]]. It also gives some info about event handling and coding style when writing JavaScript for use in DokuWiki.
===== JavaScript Loading =====
All JavaScript code is collected from all found files and concatenated as one block of code. It is then whitespace compressed (if [[config:compress]] is enabled) and delivered as one file. As a live example you can view the JavaScript file that is in effect on this website [[this>lib/exe/js.php|lib/exe/js.php]]. This file will be cached in the DokuWiki cache at ''/dokuwiki/data/cache'' and DokuWiki also instructs browsers to cache this file. So when you are developing new JavaScript, make sure to refresh those caches (hitting Shift-F5, Shift+CTRL+R or similar), whenever your script was updated.
DokuWiki will load JavaScript from the following places:
* autogenerated JavaScript (language strings, config settings, [[:toolbar]])
* lib/scripts/*.js
* lib/plugins/*/script.js
* lib/tpl/ more HTML
If you need to add inline JavaScript to the section you should write an [[action_plugin]] and handle the [[devel:event:tpl_metaheader_output|TPL_METAHEADER_OUTPUT]] event. When you define only some variables see the [[#JSINFO]] variable below.
===== jQuery =====
Since the October 2011 release "Angua", DokuWiki ships with the jQuery and jQuery UI libraries.
Please follow these coding conventions when working with jQuery in DokuWiki. Please also refer to our [[devel:jqueryfaq|JQuery FAQ for Plugin Developers]].
==== No $() ====
jQuery is only used in compatibility mode. There is no ''$()'' method((it might be defined but will **not** do what you expect)). Use the ''jQuery()'' method instead.
Do not map ''$()'' to ''jQuery()'', not even within your own (anonymous) functions.
==== Prefix jQuery object variables ====
To make it clear that a variable contains an instance of the jQuery object all these variables should be prefixed by a ''$'' character:
var $obj = jQuery('#some__id');
===== DokuWiki JavaScript Environment =====
==== Predefined Global Variables ====
DokuWiki defines certain JavaScript variables for the use in your script:
* ''DOKU_BASE'' -- the full webserver path to the DokuWiki installation
* ''DOKU_TPL'' -- the full webserver path to the used [[:Template]]
* ''DOKU_COOKIE_PARAM'' -- parameters required to set similar cookies as in PHP
* ''path'' -- cookie path
* ''secure'' -- whether secure cookie
* ''LANG'' -- [[devel:localization#template_localization|an array of languagestrings]]
* ''JSINFO'' -- an array of useful page info (see the section below)
* ''NS'' -- $INFO['namespace'] passed through the function ''tpl_metaheaders()''
==== JSINFO ====
DokuWiki passes the global [[devel:environment#jsinfo|$JSINFO]] to JavaScript (see [[http://www.freelists.org/post/dokuwiki/INFO,44|mailinglist discussion]]). This variable is an associative array usually containing the keys:
* ''id'' -- the current page's ID
* ''namespace'' -- the current namespace.
And after 2018-04-05:
* ''ACT'' -- the current mode
* ''useHeadingNavigation'' -- whether to use the first title for Navigation links (the former global constant ''DOKU_UHN'' has been deprecated)
* ''useHeadingContent'' -- whether to use the first title for Content links (the former global constant ''DOKU_UHC'' has been deprecated)
Other keys can easily be added from within PHP code. The usual way is using an [[action plugin]] like this:
function register(Doku_Event_Handler $controller) {
$controller->register_hook('DOKUWIKI_STARTED', 'AFTER', $this, '_adduser');
}
function _adduser(&$event, $param) {
global $JSINFO;
$JSINFO['user'] = $_SERVER['REMOTE_USER'];
}
If you want to make sure that your plugin's data don't interfere with other plugins or DokuWiki itself consider using ''plugin_