Wiki source code of XWiki JavaScript API
Version 34.1 by Thomas Mortagne on 2015/08/07
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | {{box cssClass="floatinginfobox" title="**Contents**"}} | ||
| 2 | {{toc/}} | ||
| 3 | {{/box}} | ||
| 4 | |||
| 5 | = Observable XWiki Events = | ||
| 6 | |||
| 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 | |||
| 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: | ||
| 10 | |||
| 11 | {{code language="javascript"}} | ||
| 12 | document.observe("xwiki:modulename:eventname", function(event) { | ||
| 13 | // Here, do something that will be executed at the moment the event is fired | ||
| 14 | doSomething(); | ||
| 15 | |||
| 16 | // The event can have an option memo object to pass to its observers some information: | ||
| 17 | console.log(event.memo.somethingINeedToKnow); | ||
| 18 | }); | ||
| 19 | {{/code}} | ||
| 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/]]. | ||
| 22 | |||
| 23 | == DOM Events (xwiki.js) == | ||
| 24 | |||
| 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"}} | ||
| 28 | document.observe("xwiki:dom:loaded", function(){ | ||
| 29 | // Initialization that can rely on the fact the DOM is XWiki-tranformed goes here. | ||
| 30 | }); | ||
| 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 | |||
| 38 | * **##xwiki:dom:loading##** | ||
| 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 | * **##xwiki:dom:updated##** | ||
| 41 | This event is sent whenever an important change in the DOM occurs, such as loading new content in a dialog box or tab, or refreshing the document content. Scripts that add behavior to certain elements, or which enhance the DOM, should listen to this event as well and re-apply their initialization process on the updated content, the same way that the whole DOM is enhanced on ##xwiki:dom:loaded##. The list of new or updated elements is sent in the ##event.memo.elements## property. For example:((( | ||
| 42 | {{code language="javascript"}} | ||
| 43 | var init = function(elements) { | ||
| 44 | // Search for special content to enhance in each DOM element in the "elements" list and enhance it | ||
| 45 | elements.each(function(element) { | ||
| 46 | element.select('.someBehavioralClass').each(function(item) { | ||
| 47 | enhance(item); | ||
| 48 | }); | ||
| 49 | }); | ||
| 50 | } | ||
| 51 | ['xwiki:dom:loaded', 'xwiki:dom:updated'].each(function(eventName) { | ||
| 52 | document.observe(eventName, function(event) { | ||
| 53 | init(event.memo && event.memo.elements || [document.documentElement]); | ||
| 54 | }); | ||
| 55 | }); | ||
| 56 | {{/code}} | ||
| 57 | |||
| 58 | {{warning}} | ||
| 59 | If your script is loaded **deferred**, all these events may be triggered **before your script is executed** and therefore **before it has the ablity to observe these events**. Since 3.1.1, to prevent your handler to never being called, never use ##dom:loaded## anymore, and check ##XWiki.isInitialized## before waiting for ##xwiki:dom:loading##, and ##XWiki.domIsLoaded## before waiting for ##xwiki:dom:loaded##. If the flag is true, you should proceed immediately with your handler. Here is a simple construct to properly handle this:((( | ||
| 60 | {{code}} | ||
| 61 | function init() { | ||
| 62 | // This is your initialization handler, that you generally hook to xwiki:dom:loaded | ||
| 63 | } | ||
| 64 | (XWiki && XWiki.domIsLoaded && init()) || document.observe("xwiki:dom:loaded", init); | ||
| 65 | {{/code}}))) | ||
| 66 | {{/warning}} | ||
| 67 | |||
| 68 | == Document content events (actionButtons.js) == | ||
| 69 | |||
| 70 | * **##xwiki:document:saved##** | ||
| 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 | * **##xwiki:document:saveFailed##** | ||
| 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 | |||
| 75 | == Action events (actionButtons.js) == | ||
| 76 | |||
| 77 | * **##xwiki:actions:cancel##** | ||
| 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. | ||
| 79 | * **##xwiki:actions:preview##** | ||
| 80 | This event is sent after the user clicks the "Preview" button of an editor (Wiki, WYSIWYG, object, rights, etc.), but before actually leaving the edit mode. | ||
| 81 | * **##xwiki:actions:save##** | ||
| 82 | This event is sent after the user clicks the "Save" or "Save & Continue" button of an editor (Wiki, WYSIWYG, object, rights, etc.), but before actually submitting the form. A memo is available if you need to know if the intend is to continue after the save, in ##event.memo['continue']##. You can use it as follows:((( | ||
| 83 | {{code language="javascript"}} | ||
| 84 | document.observe("xwiki:actions:save", function(event){ | ||
| 85 | var doContinue = event.memo['continue']; | ||
| 86 | if (doContinue) { | ||
| 87 | // do something specific | ||
| 88 | } | ||
| 89 | }); | ||
| 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 | ((( | ||
| 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 | |||
| 100 | == Document extra events (xwiki.js) == | ||
| 101 | |||
| 102 | * **##xwiki:docextra:loaded##** | ||
| 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.((( | ||
| 104 | {{code language="javascript"}} | ||
| 105 | document.observe("xwiki:docextra:loaded", function(event){ | ||
| 106 | var tabID = event.memo.id; | ||
| 107 | if (tabID == "attachments") { | ||
| 108 | // do something with the attachments tab retrieved content. | ||
| 109 | doSomething(event.memo.element); | ||
| 110 | } | ||
| 111 | }); | ||
| 112 | {{/code}} | ||
| 113 | ))) | ||
| 114 | * **##xwiki:docextra:activated##** | ||
| 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 | |||
| 117 | == WYSIWYG events (XWikiWysiwyg.js) == | ||
| 118 | |||
| 119 | WYSIWYG has it's own custom [[events list>>extensions:Extension.WYSIWYG Editor Module#HCustomevents]]. | ||
| 120 | |||
| 121 | == Suggest events (ajaxSuggest.js) == | ||
| 122 | |||
| 123 | * **##xwiki:suggest:selected##** (since 2.3) | ||
| 124 | This event is fired on the target input when a value was selected. | ||
| 125 | |||
| 126 | == Fullscreen events (fullScreenEdit.js) == | ||
| 127 | |||
| 128 | * **##xwiki:fullscreen:enter##** (since 3.0 M3) (fired before entering full screen editing) | ||
| 129 | * **##xwiki:fullscreen:entered##** (since 2.5.1) (fired after entering full screen editing) | ||
| 130 | * **##xwiki:fullscreen:exit##** (since 3.0 M3) (fired before exiting full screen editing) | ||
| 131 | * **##xwiki:fullscreen:exited##** (since 2.5.1) (fired after exiting full screen editing) | ||
| 132 | * **##xwiki:fullscreen:resized##** (since 2.5.1) | ||
| 133 | |||
| 134 | All events have the target DOM element in ##event.memo.target##. | ||
| 135 | |||
| 136 | == Annotations events (AnnotationCode/Settings jsx) == | ||
| 137 | |||
| 138 | * **##xwiki:annotations:filter:changed##** | ||
| 139 | * **##xwiki:annotations:settings:loaded##** | ||
| 140 | |||
| 141 | == Livetable events (livetable.js) == | ||
| 142 | |||
| 143 | * **##xwiki:livetable:newrow##** (##event.memo.row## holds the new row) | ||
| 144 | * **##xwiki:livetable:loadingEntries##** (since 2.3 RC1) | ||
| 145 | * **##xwiki:livetable:receivedEntries##** (since 2.3 RC1) (##event.memo.data## contains the received JSON data) | ||
| 146 | * **##xwiki:livetable:loadingComplete##** (since 2.4 M1) (##event.memo.status## contains the response status code) | ||
| 147 | * **##xwiki:livetable:displayComplete##** (since 2.4 M1) | ||
| 148 | * **##xwiki:livetable:ready##** (since 2.4.4) | ||
| 149 | * **##xwiki:livetable:loading##** (since 3.1.1) (should be used in place of ##xwiki:dom:loading## to startup livetables) | ||
| 150 | |||
| 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. | ||
| 164 | |||
| 165 | == Bridging custom XWiki events between Prototype and jQuery == | ||
| 166 | |||
| 167 | Starting with XWiki 6.4 you can catch from jQuery the custom XWiki events that are fired from Prototype. | ||
| 168 | |||
| 169 | {{code language="js"}} | ||
| 170 | require(['jquery', 'xwiki-events-bridge'], function($) { | ||
| 171 | $('.some-element').on('xwiki:moduleName:eventName', function(event, data) { | ||
| 172 | // Here, do something that will be executed at the moment the event is fired. | ||
| 173 | doSomething(); | ||
| 174 | |||
| 175 | // The passed data is a reference to the event.memo from Prototype. | ||
| 176 | console.log(data.somethingINeedToKnow); | ||
| 177 | }); | ||
| 178 | }); | ||
| 179 | {{/code}} | ||
| 180 | |||
| 181 | Starting with XWiki 7.1M1 the event listeners registered from Prototype are notified when a custom XWiki event is fired using the jQuery API. This doesn't mean you should write new event listeners using Prototype but that you can rely on existing event listeners until they are rewritten using jQuery. | ||
| 182 | |||
| 183 | {{code language="js"}} | ||
| 184 | // Prototype (old code that you don't have time to rewrite) | ||
| 185 | document.observe('xwiki:dom:updated', function(event) { | ||
| 186 | event.memo.elements.each(function(element) { | ||
| 187 | // Do something. | ||
| 188 | }); | ||
| 189 | }); | ||
| 190 | ... | ||
| 191 | // jQuery (new code, in a different file/page) | ||
| 192 | require(['jquery', 'xwiki-events-bridge'], function($) { | ||
| 193 | $(document).trigger('xwiki:dom:updated', {'elements': $('.some-container').toArray()}); | ||
| 194 | }); | ||
| 195 | {{/code}} | ||
| 196 | |||
| 197 | = Get some information about the current document {{info}}(Since 6.3M2){{/info}} = | ||
| 198 | |||
| 199 | In your javascript's applications, you can get (meta) information about the current document, though an AMD module. | ||
| 200 | |||
| 201 | {{code language="javascript"}} | ||
| 202 | require(['xwiki-meta'], function (xm) { | ||
| 203 | xm.document // get the current document (eg: Main.WebHome) | ||
| 204 | xm.wiki // get the current wiki (eg: xwiki) | ||
| 205 | xm.space // get the current space (eg: Main) | ||
| 206 | xm.page // get the current page name (eg: WebHome) | ||
| 207 | xm.version // get the current document version (eg: 1.1) | ||
| 208 | xm.restURL // get the REST url of the current doc (eg: /xwiki/rest/wikis/xwiki/spaces/Main/pages/WebHome) | ||
| 209 | xm.form_token // get the current CSRF token that you should pass to your scripts to avoid CSRF attacks. | ||
| 210 | }); | ||
| 211 | {{/code}} | ||
| 212 | |||
| 213 | {{warning}} | ||
| 214 | It is actually the only clean way. In the past, we used to add some <meta> tags in the <head> section of the page, but is not even valid in HTML5. So now we have introduced this API that we will maintain, meanwhile relying on any other element in the page could be broken in the future! | ||
| 215 | {{/warning}} | ||
| 216 | |||
| 217 | == Be retro-compatible with versions older than 6.3 == | ||
| 218 | |||
| 219 | If you want to be compatible with older version, you can use this trick: | ||
| 220 | |||
| 221 | {{code language="javascript"}} | ||
| 222 | require(['xwiki-meta'], function (xm) { | ||
| 223 | // Note that the require['xwiki-meta'] (meta information about the current document) is not available on | ||
| 224 | // XWiki versions < 6.3, then we get these meta information directly from the DOM. | ||
| 225 | var document = xm ? xm.document : $('meta[name="document"]').attr('content'); | ||
| 226 | var wiki = xm ? xm.wiki : $('meta[name="wiki"]').attr('content'); | ||
| 227 | var space = xm ? xm.space : $('meta[name="space"]').attr('content'); | ||
| 228 | var page = xm ? xm.wiki : $('meta[name="page"]').attr('content'); | ||
| 229 | var version = xm ? xm.version : $('meta[name="version"]').attr('content'); | ||
| 230 | var restURL = xm ? xm.restURL : $('meta[name="restURL"]').attr('content'); | ||
| 231 | var form_token = xm ? xm.form_token : $('meta[name="form_token"]').attr('content'); | ||
| 232 | }); | ||
| 233 | {{/code}} | ||
| 234 | |||
| 235 | = Work with Entity References {{info}}(Since 4.2M1){{/info}} = | ||
| 236 | |||
| 237 | You can resolve and serialize Entity References on the client side easily: | ||
| 238 | |||
| 239 | {{code language="js"}} | ||
| 240 | var documentReference = XWiki.Model.resolve('wiki:Space.Page', XWiki.EntityType.DOCUMENT); | ||
| 241 | var attachmentReference = new XWiki.AttachmentReference('logo.png', documentReference); | ||
| 242 | XWiki.Model.serialize(attachmentReference); | ||
| 243 | {{/code}} | ||
| 244 | |||
| 245 | You can check the full API [[here>>https://github.com/xwiki/xwiki-platform/blob/master/xwiki-platform-core/xwiki-platform-web/src/main/webapp/resources/uicomponents/model/entityReference.js]]. | ||
| 246 | |||
| 247 | Starting with XWiki 7.2M1 the ##XWiki.Model## JavaScript API is supporting nested spaces: | ||
| 248 | |||
| 249 | {{code language="js"}} | ||
| 250 | var documentReference = XWiki.Model.resolve('wiki:Path.To.My.Page', XWiki.EntityType.DOCUMENT); | ||
| 251 | documentReference.getReversedReferenceChain().map(function(entityReference) { | ||
| 252 | return entityReference.type + ': ' + entityReference.name | ||
| 253 | }).join() | ||
| 254 | // Will produce: | ||
| 255 | // 0: wiki,1: Path,1: To,1: My,2: Page | ||
| 256 | {{/code}} | ||
| 257 | |||
| 258 | Starting with 7.2M1 you can also pass a 'provider' as the third argument to ##XWiki.Model.resolve()##. The provider is used to fill missing references, and it is either a function that gets the entity type, an array of entity names or an entity reference. | ||
| 259 | |||
| 260 | {{code language="js"}} | ||
| 261 | var documentReference = XWiki.Model.resolve('Page', XWiki.EntityType.DOCUMENT, function(type) { | ||
| 262 | switch(type) { | ||
| 263 | case: XWiki.EntityType.WIKI: | ||
| 264 | return 'wiki'; | ||
| 265 | case: XWiki.EntityType.SPACE: | ||
| 266 | return 'Space'; | ||
| 267 | default: | ||
| 268 | return null; | ||
| 269 | } | ||
| 270 | }); | ||
| 271 | // Produces wiki:Space.Page | ||
| 272 | |||
| 273 | var documentReference = XWiki.Model.resolve('Page', XWiki.EntityType.DOCUMENT, ['wiki', 'Space']); | ||
| 274 | // Same output | ||
| 275 | |||
| 276 | var spaceReference = new XWiki.SpaceReference('wiki', 'Space'); | ||
| 277 | var documentReference = XWiki.Model.resolve('Page', XWiki.EntityType.DOCUMENT, spaceReference); | ||
| 278 | // Same output | ||
| 279 | {{/code}} | ||
| 280 | |||
| 281 | Starting with 7.2M2 you can construct Reference to Nested Spaces and a new ##equals()## method has been added. Examples using Jasmine: | ||
| 282 | |||
| 283 | {{code language="js"}} | ||
| 284 | // Construct a Nested Space reference | ||
| 285 | var reference = new XWiki.SpaceReference('wiki', ['space1', 'space2']); | ||
| 286 | expect(XWiki.Model.serialize(reference)).toEqual('wiki:space1.space2'); | ||
| 287 | reference = new XWiki.DocumentReference('wiki', ['space1', 'space2'], 'page'); | ||
| 288 | expect(XWiki.Model.serialize(reference)).toEqual('wiki:space1.space2.page'); | ||
| 289 | // Construct a non-Nested Space reference | ||
| 290 | reference = new XWiki.SpaceReference('wiki', 'space'); | ||
| 291 | expect(XWiki.Model.serialize(reference)).toEqual('wiki:space'); | ||
| 292 | // Try passing non-valid space parameters | ||
| 293 | expect(function() {new XWiki.SpaceReference('wiki', [])}).toThrow('Missing mandatory space name or invalid type for: []'); | ||
| 294 | expect(function() {new XWiki.SpaceReference('wiki', 12)}).toThrow('Missing mandatory space name or invalid type for: [12]'); | ||
| 295 | |||
| 296 | // Equals() examples | ||
| 297 | var reference1 = new XWiki.DocumentReference('wiki', ['space1', 'space2'], 'page'); | ||
| 298 | var reference2 = new XWiki.DocumentReference('wiki', ['space1', 'space2'], 'page'); | ||
| 299 | var reference3 = new XWiki.DocumentReference('wiki2', ['space1', 'space2'], 'page'); | ||
| 300 | expect(reference1.equals(reference2)).toBe(true); | ||
| 301 | expect(reference1.equals(reference3)).toBe(false); | ||
| 302 | {{/code}} | ||
| 303 | |||
| 304 | In 7.2M2 a new XWiki.EntityReferenceTree class which partially mimic Java EntityReferenceTree on Javascript side. There is not much yet, it was mostly introduced to make easier to manipulate a serialized Java EntityReferenceTree. | ||
| 305 | |||
| 306 | {{code}} | ||
| 307 | this.entities = XWiki.EntityReferenceTree.fromJSONObject(transport.responseText.evalJSON()); | ||
| 308 | {{/code}} |
