From version < 17.2 >
edited by Sergiu Dumitriu
on 2012/10/25
To version < 17.3 >
edited by Manuel Smeria
on 2013/01/08
< >
Change comment: added the title and adjusted the headers properly, updated links, rewording

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +XWiki JavaScript API
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.Sergiu
1 +XWiki.ManuelSmeria
Content
... ... @@ -1,9 +1,9 @@
1 -{{box cssClass="floatinginfobox" title="**Contents**"}}{{toc/}}{{/box}}
1 +{{box cssClass="floatinginfobox" title="**Contents**"}}
2 +{{toc/}}
3 +{{/box}}
2 2  
3 -= XWiki JavaScript API =
5 += Observable XWiki Events =
4 4  
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,18 +18,23 @@
18 18  });
19 19  {{/code}}
20 20  
21 -Check out the real examples below, or [[read more>>http://prototypejs.org/api/element/fire]] about Prototype.js's event system
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 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://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:(((
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 27  {{code language="javascript"}}
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 -**It is recommended to bind startup scripts to this event** instead of ##window.load## or ##document.dom:loaded##.
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 +
33 33  * **##xwiki:dom:loading##**
34 34  ##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.
35 35  * **##xwiki:dom:updated##**
... ... @@ -60,7 +60,7 @@
60 60  {{/code}})))
61 61  {{/warning}}
62 62  
63 -=== Document content events (actionButtons.js) ===
68 +== Document content events (actionButtons.js) ==
64 64  
65 65  * **##xwiki:document:saved##**
66 66  This event is sent after the document has been successfully saved in an asynchronous request (i.e. after clicking the //Save and Continue// button).
... ... @@ -67,7 +67,7 @@
67 67  * **##xwiki:document:saveFailed##**
68 68  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##.
69 69  
70 -=== Action events (actionButtons.js) ===
75 +== Action events (actionButtons.js) ==
71 71  
72 72  * **##xwiki:actions:cancel##**
73 73  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.
... ... @@ -83,12 +83,16 @@
83 83   }
84 84  });
85 85  {{/code}})))
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 -
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 +(((
89 89  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 +)))
90 90  
91 -=== Document extra events (xwiki.js) ===
100 +== Document extra events (xwiki.js) ==
92 92  
93 93  * **##xwiki:docextra:loaded##**
94 94  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.(((
... ... @@ -105,16 +105,16 @@
105 105  * **##xwiki:docextra:activated##**
106 106  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##
107 107  
108 -=== WYSIWYG events (XWikiWysiwyg.js) ===
117 +== WYSIWYG events (XWikiWysiwyg.js) ==
109 109  
110 110  WYSIWYG has it's own custom [[events list>>extensions:Extension.WYSIWYG Editor Module#HCustomevents]].
111 111  
112 -=== Suggest events (ajaxSuggest.js) ===
121 +== Suggest events (ajaxSuggest.js) ==
113 113  
114 114  * **##xwiki:suggest:selected##** (since 2.3)
115 115  This event is fired on the target input when a value was selected.
116 116  
117 -=== Fullscreen events (fullScreenEdit.js) ===
126 +== Fullscreen events (fullScreenEdit.js) ==
118 118  
119 119  * **##xwiki:fullscreen:enter##** (since 3.0 M3) (fired before entering full screen editing)
120 120  * **##xwiki:fullscreen:entered##** (since 2.5.1) (fired after entering full screen editing)
... ... @@ -124,12 +124,12 @@
124 124  
125 125  All events have the target DOM element in ##event.memo.target##.
126 126  
127 -=== Annotations events (AnnotationCode/Settings jsx) ===
136 +== Annotations events (AnnotationCode/Settings jsx) ==
128 128  
129 129  * **##xwiki:annotations:filter:changed##**
130 130  * **##xwiki:annotations:settings:loaded##**
131 131  
132 -=== Livetable events (livetable.js) ===
141 +== Livetable events (livetable.js) ==
133 133  
134 134  * **##xwiki:livetable:newrow##** (##event.memo.row## holds the new row)
135 135  * **##xwiki:livetable:loadingEntries##** (since 2.3 RC1)

XWiki JavaScript API

Observable XWiki Events

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);
});

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

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

DOM Events (xwiki.js)

DOM Events (xwiki.js)

  • xwiki:dom:loaded
    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 follows:
    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
    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 follows:
    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
    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:updated
    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:
    var init = function(elements) {
     // Search for special content to enhance in each DOM element in the "elements" list and enhance it
     elements.each(function(element) {
        element.select('.someBehavioralClass').each(function(item) {
          enhance(item);
        });
      });
    }
    ['xwiki:dom:loaded', 'xwiki:dom:updated'].each(function(eventName) {
     document.observe(eventName, function(event) {
        init(event.memo && event.memo.elements || [document.documentElement]);
      });
    });

    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:

    function init() {
     // This is your initialization handler, that you generally hook to xwiki:dom:loaded
    }
    (XWiki && XWiki.domIsLoaded && init()) || document.observe("xwiki:dom:loaded", init);

    Document content events (actionButtons.js)

    Document content events (actionButtons.js)

    • 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)

    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 the user 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:actions:save", function(event){
       var doContinue = event.memo['continue'];
       if (doContinue) {
         // do something specific
       }
      });

      While most properties can be accessed as event.memo.property, this doesn't work with event.memo.continue since continue is a reserved keyword.

      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.

    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.

    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)

    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
      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 events (XWikiWysiwyg.js)

    WYSIWYG has it's own custom events list.

    Suggest events (ajaxSuggest.js)

    Suggest events (ajaxSuggest.js)

    • xwiki:suggest:selected (since 2.3)
      This event is fired on the target input when a value was selected.

    Fullscreen events (fullScreenEdit.js)

    Fullscreen events (fullScreenEdit.js)

    • xwiki:fullscreen:enter (since 3.0 M3) (fired before entering full screen editing)
    • xwiki:fullscreen:entered (since 2.5.1) (fired after entering full screen editing)
    • xwiki:fullscreen:exit (since 3.0 M3) (fired before exiting full screen editing)
    • xwiki:fullscreen:exited (since 2.5.1) (fired after exiting full screen editing)
    • xwiki:fullscreen:resized (since 2.5.1)

    All events have the target DOM element in event.memo.target.

    Annotations events (AnnotationCode/Settings jsx)

    Annotations events (AnnotationCode/Settings jsx)

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

    Livetable events (livetable.js)

    Livetable events (livetable.js)

    • xwiki:livetable:newrow (event.memo.row holds the new row)
    • xwiki:livetable:loadingEntries (since 2.3 RC1)
    • xwiki:livetable:receivedEntries (since 2.3 RC1) (event.memo.data contains the received JSON data)
    • xwiki:livetable:loadingComplete (since 2.4 M1) (event.memo.status contains the response status code)
    • xwiki:livetable:displayComplete (since 2.4 M1)
    • xwiki:livetable:ready (since 2.4.4)
    • xwiki:livetable:loading (since 3.1.1) (should be used in place of xwiki:dom:loading to startup livetables)

    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.

Get Connected