Differences

This shows you the differences between two versions of the page.

--- devel:javascript [2014-01-03 19:14] – [Use unobtrusive JavaScript] 188.23.147.57
+++ devel:javascript [2024-04-10 15:21] (current) – [Inline scripts] andi
@@ Line 5: / Line 5: @@
 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 =====
+===== JavaScript Loading =====
-All JavaScript is collected and delivered by [[xref>lib/exe/js.php]]. This file will concatenate all found files, whitespace compress (if
+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 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.
-[[config:compress]] is enabled) and cache the result. It also instructs browsers to cache the file, so when you are developing new JavaScript, be sure to refresh your browser cache (hitting Shift-F5, Shift+CTL+R or similar) whenever your script was updated.
 DokuWiki will load JavaScript from the following places:
@@ Line 18: / Line 17: @@
   * conf/userscript.js
-As you can see you can provide JavaScript with your [[:templates]] and [[:plugins]] (through a ''script.js'' file) and can define your own scripts in ''conf/userscript.js''.
+As you can see you can provide JavaScript with your [[:templates]] and [[:plugins]] (through a ''script.js'' file) and can define your own scripts in ''conf/userscript.js'' (just create this file if it does not yet exist).
+==== Deferred Loading ====
+All JavaScript is loaded with the [[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#attr-defer|defer]] attribute. [[https://flaviocopes.com/javascript-async-defer/|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 use ''document.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 the ''defer'' attribute to the ''<script>'' tag.
+Temporary, the feature flag [[config:defer js]] is available, which allows disabling.
 ==== Include Syntax ====
@@ Line 26: / Line 35: @@
 :!: Included files are not checked for updates by the cache logic. You need to touch the master file for updating the cache.
-:!: Includes are *not* supported inside included files to avoid any circular references.
+:!: Includes are **not** supported inside included files to avoid any circular references.
 :!: Includepath may only consist of letter,digit, underscore, "/" and ".".
@@ Line 99: / Line 108: @@
 ==== Inline scripts ====
-As said before you should avoid mixing JavaScript and XHTML. However if you need to use inline JavaScript, you should wrap it like this:
+As said before you should avoid mixing JavaScript and HTML. However if you need to use inline JavaScript, you should use the [[xref>tpl_inlineScript()]] method ([[devel:develonly]]).
-<code>
+<code php>
-<script type="text/javascript">/*<![CDATA[*/
+tpl_inlineScript('
-...
+    alert("This is inline script code");
-/*!]]>*/</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 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.
@@ Line 147: / Line 158: @@
 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:
 <code php>
-function register(Doku_Event_Handler $controller) {
+public function register(EventHandler $controller) {
-    $controller->register_hook('DOKUWIKI_STARTED', 'AFTER',  $this, '_adduser');
+    $controller->register_hook('DOKUWIKI_STARTED', 'AFTER',  $this, 'addUser');
 }
-function _adduser(&$event, $param) {
+public function addUser(Event $event, $param) {
-    global $JSINFO;
+    global $JSINFO, $INPUT;
-    $JSINFO['user'] = $_SERVER['REMOTE_USER'];
+    $JSINFO['user'] = $INPUT->server->str('REMOTE_USER');
 }
 </code>
+If you want to make sure that your plugin's data don't interfere with other plugins or DokuWiki itself consider using ''plugin_<pluginName>'' as prefix/top-level key.
 The contents of the ''$JSINFO'' php variable are sent to the browser in the [[xref>tpl_metaheaders()]] function which is called from within the used [[template]].
+If you need JSINFO in the [[:media_manager|pop-up media manager]] or in the [[devel:templates:detail.php|media detail page]] you have to use respectively [[devel:event:MEDIAMANAGER_STARTED]] or [[devel:event:DETAIL_STARTED]] in stead of [[devel:event:DOKUWIKI_STARTED]].
+Also see: Javascript in [[https://www.dokuwiki.org/devel:plugin_programming_tips#adding_javascript|"Tips for programming plugins"]]