Table of Contents

DokuWiki makes use ofJavaScript to enhance the user experience. Like forstylesheets all JavaScript files are delivered through a single dispatcher to minimize HTTP requests, for caching andcompression.

This page gives you an overview how JavaScript is loaded from DokuWiki core,plugins andtemplates. It also gives some info about event handling and coding style when writing JavaScript for use in DokuWiki.

All JavaScript code is collected from all found files and concatenated as one block of code. It is then whitespace compressed (ifcompress is enabled) and delivered as one file. As a live example you can view the JavaScript file that is in effect on this websitelib/exe/js.php.

This file will be cached in the DokuWiki cache at[dokuwiki folder]/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 loads the JavaScript files from the following locations and in this order:

• autogenerated JavaScript (language strings, config settings,toolbar)
• lib/scripts/*.js
• lib/plugins/*/script.js
• lib/tpl/<currenttemplate>/script.js
• conf/userscript.js (placed at the end of the entire code block)

As you can see you can provide JavaScript with yourtemplates andplugins (through ascript.js file) and can define your own scripts inconf/userscript.js (just create this file if it does not yet exist).

All JavaScript is loaded with thedefer attribute.Here's more information about deferred loading.

If you load JavaScript through other means than the recommended methods below and that JavaScript has dependencies on any DokuWiki provided code, you need to ensure it is deferred as well. This also means that you cannot usedocument.write that relies on DokuWiki-loaded scripts.

From the 2020 Hogfather version onwards, all javascript must be load in a deferred way. To update your existing templates javascript to work in this version, you can add thedefer attribute to the<script> tag.

Temporary, the feature flagdefer js is available, which allows disabling.

DokuWiki's JavaScript dispatcher allows you to use special JavaScript comments to include other script files. This is useful for cases where usually only a single JavaScript file would be parsed, e.g. in templates or plugins.

Included files are not checked for updates by the cache logic. You need to touch the master file for updating the cache.

Includes arenot supported inside included files to avoid any circular references.

Includepath may only consist of letter,digit, underscore, “/” and “.”.

/* DOKUWIKI:include somefile.js */

This syntax will include the given file where the comment is placed. The filename is relative to the file containing the include markup unless it starts with a slash which indicates an absoluteURL path.

/* DOKUWIKI:include_once common_library.js */

This syntax will include the given file where the comment is placed. The filename is relative to the file containing the include markup unless it starts with a slash which indicates an absoluteURL path.

The file will only be included if not a file of the same base name was previously loaded through the include_once statement. This name is shared over all script files (from all plugins), so you should use a meaningful file name.

Using this statement makes sense if you write multiple independentplugins all using the same JavaScript library. Including it withinclude_once using the same basename will make sure the library is loaded only once even if multiple of your plugins are installed.

When writing JavaScript for the use within DokuWiki you should follow a few rules. Because of the nature of JavaScript, failing to do so might result in not only breaking your script but all scripts in DokuWiki.

As mentioned above, DokuWiki will shrink the JavaScript code when thecompress option is enabled (which it is by default). To do this without introducing syntax errors, the JavaScript has to be checked more strictly than it might be when run uncompressed.

To check your code you should use theJSLint online service.

• debug your code withcompress disabled but
• verify your code still works withcompress enabled

Do not assume people have JavaScript enabled, when writing new DokuWiki functionality. Instead use JavaScript as enhancement of the user interface only, when JavaScript is not available your code should fallback to normal page reload based behavior.

jQuery makes this very easy.

The old way of doing things is to embed JavaScript directly in theHTML. However, JavaScript and (X)HTML shouldn't be mixed, and indeed with DokuWiki there are many cases where theycannot be mixed. Here are some examples ofINAPPROPRIATE MIXING1):

<bodyonload="refreshPage()"> <p>some HTML</p> <scriptlanguage="JavaScript">  doSomethingHere();</script> <p>more<ahref="http://example.com"onclick="doSomethingElse()">HTML</a></p> </body>

This isn't just a matter of philosophical purity: some of the JavaScript may not work. In the above example, it turns out that both DokuWiki and the<body> tag are trying to assign the page'sonload handler to different JavaScript functions. Browsers cannot handle this conflict and the results are unpredictable.

Strictly speaking, it is possible to embed JavaScript in yourHTML, but only if you know that the JavaScript has no conflict with DokuWiki. Because this requires knowledge of DokuWiki's implementation, and because DokuWiki's implementation can change, this is still not a good idea. It's wiser to be philosophically pure.

To modify a DOM object the JavaScript must be able to locate the object. The easiest way to locate the object is to give the associatedHTML tag an ID. This ID must be unique among all IDs on the page so that referencing this ID produces exactly the right DOM object.

When you are producing your ownHTML (e.g. from a template or plugin) that should be accessed from JavaScript later, be sure that the ID does not conflict with an existing ID. In particular, be sure that it won't conflict with the IDs automatically assigned to section headers. The easiest way to ensure this is to use two adjacent underscores (__) in your ID. Because section IDs are always validpagenames, they will never contain adjacent underscores.

As said before you should avoid mixing JavaScript andHTML. However if you need to use inline JavaScript, you should use thetpl_inlineScript() method (develonly).

tpl_inlineScript('    alert("This is inline script code");');

Using this method will create the appropriate script tag including a nonce attribute if needed.

If you need to add inline JavaScript to the <head> section you should write anaction_plugin and handle theTPL_METAHEADER_OUTPUT event. When you define only some variables see theJSINFO variable below.

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 ourJQuery FAQ for Plugin Developers.

jQuery is only used in compatibility mode. There is no$() method²⁾. Use thejQuery() method instead.

Do not map$() tojQuery(), not even within your own (anonymous) functions.

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 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 usedTemplate
• DOKU_COOKIE_PARAM – parameters required to set similar cookies as in PHP
  • path – cookie path
  • secure – whether secure cookie
• LANG –an array of languagestrings
• JSINFO – an array of useful page info (see the section below)
• NS – $INFO['namespace'] passed through the functiontpl_metaheaders()

DokuWiki passes the global$JSINFO to JavaScript (seemailinglist 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 constantDOKU_UHN has been deprecated)
• useHeadingContent – whether to use the first title for Content links (the former global constantDOKU_UHC has been deprecated)

Other keys can easily be added from within PHP code. The usual way is using anaction plugin like this:

publicfunction register(EventHandler$controller){$controller->register_hook('DOKUWIKI_STARTED','AFTER',$this,'addUser');}publicfunction addUser(Event$event,$param){global$JSINFO,$INPUT;$JSINFO['user']=$INPUT->server->str('REMOTE_USER');}

If you want to make sure that your plugin's data don't interfere with other plugins or DokuWiki itself consider usingplugin_<pluginName> as prefix/top-level key.

The contents of the$JSINFO php variable are sent to the browser in thetpl_metaheaders() function which is called from within the usedtemplate.

If you need JSINFO in thepop-up media manager or in themedia detail page you have to use respectivelyMEDIAMANAGER_STARTED orDETAIL_STARTED in stead ofDOKUWIKI_STARTED.

Also see: Javascript inTips for Programming Plugins