Changes for page XWiki JavaScript API

Last modified by Simon Urli on 2022/09/14

<
From version < 18.1 >
edited by Caleb James DeLisle
on 2013/12/05
To version < 17.1 >
edited by Sergiu Dumitriu
on 2012/10/25
>
Change comment: Example of proper initialization using xwiki:dom:loaded and xwiki:dom:updated

Summary

Details

Page properties
Title
... ... @@ -1,1 +1,0 @@
1 -XWiki JavaScript API
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.CalebJamesDeLisle
1 +XWiki.Sergiu
Content
... ... @@ -1,9 +1,9 @@
1 -{{box cssClass="floatinginfobox" title="**Contents**"}}
2 -{{toc/}}
3 -{{/box}}
1 +{{box cssClass="floatinginfobox" title="**Contents**"}}{{toc/}}{{/box}}
4 4  
5 -= Observable XWiki Events =
3 += XWiki JavaScript API =
6 6  
5 +== Observable XWiki Events ==
6 +
7 7  Stay in touch with what happens in the wiki! XWiki will fire custom javascript events on certain moment and upon certain actions that occur in the navigation flow.
8 8  
9 9  Event names are build on the following model: ##xwiki:modulename:eventname##. Your JavaScript script or extension can get notified of such an event the following way:
... ... @@ -18,23 +18,18 @@
18 18  });
19 19  {{/code}}
20 20  
21 -Check out the real examples below or read more about [[Prototype.js's event system>>http://prototypejs.org/doc/latest/dom/Element/fire/]].
21 +Check out the real examples below, or [[read more>>http://prototypejs.org/api/element/fire]] about Prototype.js's event system
22 22  
23 -== DOM Events (xwiki.js) ==
23 +=== DOM Events (xwiki.js) ===
24 24  
25 25  * **##xwiki:dom:loaded##**
26 -This event is similar to [[prototype's dom:loaded event>>http://prototypejs.org/doc/latest/dom/document/observe/]], with the difference that in the time-lapse between ##dom:loaded## and ##xwiki:dom:loaded##, XWiki may have transformed the DOM. Example of DOM transformations operated by XWiki is setting the right target of links that have rel="external" attribute so that the document can be XHTML valid and still have the desired effect, making internal rendering error messages expandable, insert document template handlers for links to non-existent documents, and so on. In the future there might be more transformations operated by XWiki upon DOM initialization. This event is meant for code to be notified of loading of the XWiki-transformed version of the initial DOM. As ##dom:loaded##, it can be used as follows:(((
27 -{{code language="javascript"}}
26 +This event is similar to [[prototype's dom:loaded event>>http://www.prototypejs.org/api/document/observe]], with the difference that in the time-lapse between ##dom:loaded## and ##xwiki:dom:loaded##, XWiki may have transformed the DOM. Example of DOM transformations operated by XWiki is setting the right target of links that have rel="external" attribute so that the document can be XHTML valid and still have the desired effect, making internal rendering error messages expandable, insert document template handlers for links to non-existent documents, and so on. In the future there might be more transformations operated by XWiki upon DOM initialization. This event is meant for code to be notified of loading of the XWiki-transformed version of the initial DOM. As ##dom:loaded##, it can be used as follows:(((
27 +{{code}}
28 28  document.observe("xwiki:dom:loaded", function(){
29 29   // Initialization that can rely on the fact the DOM is XWiki-tranformed goes here.
30 30  });
31 31  {{/code}})))
32 -(((
33 -{{info}}
34 -It is recommended to bind startup scripts to this event instead of ##window.load## or ##document.dom:loaded##.
35 -{{/info}}
36 -)))
37 -
32 +**It is recommended to bind startup scripts to this event** instead of ##window.load## or ##document.dom:loaded##.
38 38  * **##xwiki:dom:loading##**
39 39  ##xwiki:dom:loading## is sent between ##dom:loaded## and ##xwiki:dom:loaded##, before XWiki changes the DOM. This is the event that should start all scripts making important DOM changes that other scripts should see.
40 40  * **##xwiki:dom:updated##**
... ... @@ -45,13 +45,13 @@
45 45   elements.each(function(element) {
46 46   element.select('.someBehavioralClass').each(function(item) {
47 47   enhance(item);
48 - });
49 - });
43 + })
44 + }
50 50  }
51 51  ['xwiki:dom:loaded', 'xwiki:dom:updated'].each(function(eventName) {
52 52   document.observe(eventName, function(event) {
53 53   init(event.memo && event.memo.elements || [document.documentElement]);
54 - });
49 + }
55 55  });
56 56  {{/code}}
57 57  
... ... @@ -65,7 +65,7 @@
65 65  {{/code}})))
66 66  {{/warning}}
67 67  
68 -== Document content events (actionButtons.js) ==
63 +=== Document content events (actionButtons.js) ===
69 69  
70 70  * **##xwiki:document:saved##**
71 71  This event is sent after the document has been successfully saved in an asynchronous request (i.e. after clicking the //Save and Continue// button).
... ... @@ -72,7 +72,7 @@
72 72  * **##xwiki:document:saveFailed##**
73 73  This event is sent when a save and continue attempt failed for some reason. The XMLHttpRequest response object is sent in the memo, as ##event.memo.response##.
74 74  
75 -== Action events (actionButtons.js) ==
70 +=== Action events (actionButtons.js) ===
76 76  
77 77  * **##xwiki:actions:cancel##**
78 78  This event is sent after the user clicks the "Cancel" button of an editor (Wiki, WYSIWYG, object, rights, etc.), but before actually cancelling the edit.
... ... @@ -88,16 +88,12 @@
88 88   }
89 89  });
90 90  {{/code}})))
91 -(((
92 -{{warning}}
93 -While most properties can be accessed as ##event.memo.property##, this doesn't work with ##event.memo.continue## since ##continue## is a reserved keyword.
94 -{{/warning}}
95 -)))
96 -(((
86 +
87 +{{warning}}Caveat: While most properties can be accessed as ##event.memo.property##, this doesn't work with ##event.memo.continue## since ##continue## is a reserved keyword.{{/warning}}
88 +
97 97  All these events contain as extra information, in the second parameter sent to event listeners (the memo), the original click event (if any, and which can be stopped to prevent the action from completing), and the form being submitted, as ##event.memo.originalEvent##, and ##event.memo.form## respectively.
98 -)))
99 99  
100 -== Document extra events (xwiki.js) ==
91 +=== Document extra events (xwiki.js) ===
101 101  
102 102  * **##xwiki:docextra:loaded##**
103 103  This event is fired upon reception of the content of a document footer tab by AJAX. This event is useful if you need to operate transformations of the received content. You can filter on which tab content to operate (comments or attachment or information or ...) using the event memo. The DOM element in which the retrieved content has been injected is also passed to facilitate transformations.(((
... ... @@ -114,16 +114,16 @@
114 114  * **##xwiki:docextra:activated##**
115 115  This event is fired upon activation of a tab. It differs from the loaded event since tabs are loaded only once if the user clicks going back and forth between tabs. This event will notify of each tab activation, just after the tab content is actually made visible. The tab ID is passed in the memo as for ##xwiki:docextra:loaded##
116 116  
117 -== WYSIWYG events (XWikiWysiwyg.js) ==
108 +=== WYSIWYG events (XWikiWysiwyg.js) ===
118 118  
119 119  WYSIWYG has it's own custom [[events list>>extensions:Extension.WYSIWYG Editor Module#HCustomevents]].
120 120  
121 -== Suggest events (ajaxSuggest.js) ==
112 +=== Suggest events (ajaxSuggest.js) ===
122 122  
123 123  * **##xwiki:suggest:selected##** (since 2.3)
124 124  This event is fired on the target input when a value was selected.
125 125  
126 -== Fullscreen events (fullScreenEdit.js) ==
117 +=== Fullscreen events (fullScreenEdit.js) ===
127 127  
128 128  * **##xwiki:fullscreen:enter##** (since 3.0 M3) (fired before entering full screen editing)
129 129  * **##xwiki:fullscreen:entered##** (since 2.5.1) (fired after entering full screen editing)
... ... @@ -133,12 +133,12 @@
133 133  
134 134  All events have the target DOM element in ##event.memo.target##.
135 135  
136 -== Annotations events (AnnotationCode/Settings jsx) ==
127 +=== Annotations events (AnnotationCode/Settings jsx) ===
137 137  
138 138  * **##xwiki:annotations:filter:changed##**
139 139  * **##xwiki:annotations:settings:loaded##**
140 140  
141 -== Livetable events (livetable.js) ==
132 +=== Livetable events (livetable.js) ===
142 142  
143 143  * **##xwiki:livetable:newrow##** (##event.memo.row## holds the new row)
144 144  * **##xwiki:livetable:loadingEntries##** (since 2.3 RC1)
... ... @@ -149,15 +149,3 @@
149 149  * **##xwiki:livetable:loading##** (since 3.1.1) (should be used in place of ##xwiki:dom:loading## to startup livetables)
150 150  
151 151  The livetable sends both generic events, named as above, and events specific to each livetable, containing the table name on the third position, such as ##xwiki:livetable:alldocs:loadingEntries##. The generic event has the table name in the memo, as ##event.memo.tableId##.
152 -
153 -== RequireJS and jQuery APIs ==
154 -
155 -By default XWiki uses PrototypeJS which is bound to the $ symbol. Starting in XWiki 5.2, you may use jQuery by //requiring// it using the [[RequireJS>>http://requirejs.org/]] AMD standard. To do this you would write your code as follows:
156 -
157 -{{code language="javascript"}}
158 -require(['jquery'], function ($) {
159 - $('#xwikicontent').append('<p>Inside of this function, $ becomes jquery!</p>');
160 -});
161 -{{/code}}
162 -
163 -The best part is, any scripts which are loaded using require are loaded //asynchronously// (all at the same time) and if they are not required, they are never loaded at all.

Get Connected