Changes for page XWiki JavaScript API

Summary

• Page properties (1 modified, 0 added, 0 removed)

Details

Page properties

Content

...	...	@@ -24,7 +24,7 @@
24	24
25	25	* **##xwiki:dom:loaded##**
26	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 language="javascript"}}
	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	});
...	...	@@ -33,22 +33,7 @@
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##**
36		-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:(((
37		-{{code language="javascript"}}
38		-var init = function(elements) {
39		- // Search for special content to enhance in each DOM element in the "elements" list and enhance it
40		- elements.each(function(element) {
41		- element.select('.someBehavioralClass').each(function(item) {
42		- enhance(item);
43		- });
44		- });
45		-}
46		-['xwiki:dom:loaded', 'xwiki:dom:updated'].each(function(eventName) {
47		- document.observe(eventName, function(event) {
48		- init(event.memo && event.memo.elements || [document.documentElement]);
49		- });
50		-});
51		-{{/code}}
	36	+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.
52	52
53	53	{{warning}}
54	54	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:(((