From version < 9.1 >
edited by Sergiu Dumitriu
on 2010/11/06
To version < 10.1 >
edited by Sergiu Dumitriu
on 2010/11/06
< >
Change comment: There is no comment for this version

Summary

Details

Page properties
Content
... ... @@ -1,13 +1,5 @@
1 -{{velocity filter="none"}}
2 -{{html clean="false" wiki="true"}}
3 -#startfloatingbox()
4 -**Contents:**
1 +{{box cssClass="floatinginfobox" title="**Contents**"}}{{toc/}}{{/box}}
5 5  
6 -{{toc start="" depth="" numbered=""/}}
7 -#endfloatingbox()
8 -{{/html}}
9 -{{/velocity}}
10 -
11 11  = XWiki JavaScript API =
12 12  
13 13  == Observable XWiki Events ==
... ... @@ -16,13 +16,13 @@
16 16  
17 17  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 18  
19 -{{code}}
20 -document.observe("xwiki:modulename:eventname", function(event){
21 - // Here, do something that will be executed at the moment the event is fired
22 - doSomething();
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();
23 23  
24 - // The event can have an option memo object to pass to its observers some information:
25 - console.log(event.memo.somethingINeedToKnow);
16 + // The event can have an option memo object to pass to its observers some information:
17 + console.log(event.memo.somethingINeedToKnow);
26 26  });
27 27  {{/code}}
28 28  
... ... @@ -30,61 +30,55 @@
30 30  
31 31  === DOM Events (xwiki.js) ===
32 32  
33 -* **##xwiki:dom:loading##**
34 -* **##xwiki:dom:loaded##**
25 +* **##xwiki:dom:loading##** (((
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 follow:
35 35  
36 -These events are 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. 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 follow:
37 -
38 38  {{code}}
39 39  document.observe("xwiki:dom:loaded", function(){
40 - // Initialization that can rely on the fact the DOM is XWiki-tranformed goes here.
30 + // Initialization that can rely on the fact the DOM is XWiki-tranformed goes here.
41 41  });
42 42  {{/code}}
43 43  
44 44  **It is recommended to bind startup scripts to this event** instead of ##window.load## or ##document.dom:loaded##.
45 -
35 +)))
36 +* **##xwiki:dom:loaded##** (((
46 46  ##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.
38 +)))
47 47  
48 48  === Document content events (actionButtons.js) ===
49 49  
50 -* **##xwiki:document:saved##**
42 +* **##xwiki:document:saved##**
43 +This event is sent after the document has been successfully saved in an asynchronous request (i.e. after clicking the //Save and Continue// button).
44 +* **##xwiki:document:saveFailed##**
45 +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##.
51 51  
52 -This is event is sent after the document has been successfully saved in an asynchronous request (i.e. after clicking the //Save and Continue// button).
53 -
54 -* **##xwiki:document:saveFailed##**
55 -
56 56  === Action events (actionButtons.js) ===
57 57  
58 58  * **##xwiki:actions:cancel##**
59 -
60 60  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.
61 -
62 62  * **##xwiki:actions:preview##**
63 -
64 64  This event is sent after ther use clicks the "Preview" button of an editor (Wiki, WYSIWYG, object, rights, etc.), but before actually leaving the edit mode.
65 -
66 -* **##xwiki:actions:save##**
67 -
53 +* **##xwiki:actions:save##**(((
68 68  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:
69 69  
70 -{{code}}
56 +{{code language="javascript"}}
71 71  document.observe("xwiki:dom:loaded", function(event){
72 - var doContinue = event.memo.continue;
73 - if (doContinue) {
74 - // do something specific
75 - }
58 + var doContinue = event.memo.continue;
59 + if (doContinue) {
60 + // do something specific
61 + }
76 76  });
77 77  {{/code}}
64 +)))
78 78  
79 -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.
66 +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.
80 80  
81 81  === Document extra events (xwiki.js) ===
82 82  
83 -* **##xwiki:docextra:loaded##**
84 -
70 +* **##xwiki:docextra:loaded##**(((
85 85  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.
86 86  
87 -{{code}}
73 +{{code language="javascript"}}
88 88  document.observe("xwiki:docextra:loaded", function(event){
89 89   var tabID = event.memo.id;
90 90   if (tabID == "attachments") {
... ... @@ -93,7 +93,7 @@
93 93   }
94 94  });
95 95  {{/code}}
96 -
82 +)))
97 97  * **##xwiki:docextra:activated##**
98 98  
99 99  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##
Contents:The [toc] macro is a standalone macro and it cannot be used inline

XWiki JavaScript API

Observable XWiki Events

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.

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:

document.observe("xwiki:modulename:eventname", function(event){
  // Here, do something that will be executed at the moment the event is fired
  doSomething();

  // The event can have an option memo object to pass to its observers some information:
  console.log(event.memo.somethingINeedToKnow);
});
document.observe("xwiki:modulename:eventname", function(event) {
 // Here, do something that will be executed at the moment the event is fired
 doSomething();

 // The event can have an option memo object to pass to its observers some information:
 console.log(event.memo.somethingINeedToKnow);
});

Check out the real examples below, or read more about Prototype.js's event system

DOM Events (xwiki.js)

  • xwiki:dom:loading 
  • xwiki:dom:loaded

These events are similar to prototype's dom:loaded event, 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. 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 follow:

document.observe("xwiki:dom:loaded", function(){
  // Initialization that can rely on the fact the DOM is XWiki-tranformed goes here.
});

It is recommended to bind startup scripts to this event instead of window.load or document.dom:loaded.

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.

  • xwiki:dom:loading

    This event is similar to prototype's dom:loaded event, 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 follow:

    document.observe("xwiki:dom:loaded", function(){
     // Initialization that can rely on the fact the DOM is XWiki-tranformed goes here.
    });

    It is recommended to bind startup scripts to this event instead of window.load or document.dom:loaded.

  • xwiki:dom:loaded

    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.

Document content events (actionButtons.js)

  • xwiki:document:saved 

This is event is sent after the document has been successfully saved in an asynchronous request (i.e. after clicking the Save and Continue button).

  • xwiki:document:saveFailed 
  • xwiki:document:saved
    This event is sent after the document has been successfully saved in an asynchronous request (i.e. after clicking the Save and Continue button).
  • xwiki:document:saveFailed
    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.

Action events (actionButtons.js)

  • xwiki:actions:cancel 

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.

  • xwiki:actions:preview 

This event is sent after ther use clicks the "Preview" button of an editor (Wiki, WYSIWYG, object, rights, etc.), but before actually leaving the edit mode.

  • xwiki:actions:save

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:

document.observe("xwiki:dom:loaded", function(event){
  var doContinue = event.memo.continue;
  if (doContinue) {
    // do something specific
   }
});
  • xwiki:actions:cancel
    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.
  • xwiki:actions:preview
    This event is sent after ther use clicks the "Preview" button of an editor (Wiki, WYSIWYG, object, rights, etc.), but before actually leaving the edit mode.
  • xwiki:actions:save

    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:

    document.observe("xwiki:dom:loaded", function(event){
     var doContinue = event.memo.continue;
     if (doContinue) {
       // do something specific
     }
    });

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.

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.

Document extra events (xwiki.js)

  • xwiki:docextra:loaded 

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.

document.observe("xwiki:docextra:loaded", function(event){
  var tabID = event.memo.id;
  if (tabID == "attachments") {
    // do something with the attachments tab retrieved content.
    doSomething(event.memo.element);
   }
});
  • xwiki:docextra:activated
  • xwiki:docextra:loaded

    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.

    document.observe("xwiki:docextra:loaded", function(event){
      var tabID = event.memo.id;
      if (tabID == "attachments") {
        // do something with the attachments tab retrieved content.
        doSomething(event.memo.element);
       }
    });
  • xwiki:docextra:activated

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

WYSIWYG events (XWikiWysiwyg.js)

WYSIWYG has it's own custom events list.

Suggest events (ajaxSuggest.js)

  • xwiki:suggest:selected (since 2.3)

This event is fired when a value was selected

Fullscreen events (fullScreenEdit.js) (since 2.5.1)

  • xwiki:fullscreen:entered 
  • xwiki:fullscreen:exited 
  • xwiki:fullscreen:resized 

Annotations events (AnnotationCode/Settings jsx)

  • xwiki:annotations:filter:changed
  • xwiki:annotations:settings:loaded

Livetable events (livetable.js)

  • xwiki:livetable:newrow
  • xwiki:livetable:loadingEntries (since 2.3 RC1)
  • xwiki:livetable:receivedEntries (since 2.3 RC1)
  • xwiki:livetable:loadingComplete (since 2.4 M1)
  • xwiki:livetable:displayComplete (since 2.4 M1)
  • xwiki:livetable:ready (since 2.4.4)

Get Connected