Changeset 13683

Timestamp:

05/10/08 20:25:50 (5 days ago)

Author:

dante

Message:

fixes #6668 - very exciting stuff - _Widget.destroy(true) will preserve the domNode (does NOT work with _Templated yet, but
that's the plan). This is a compromise between a "widget" and "named behaviors", where you can use _Widget to create
structured "behavioral" widgets around a single domNode. This is a great inclusion, though we be unnecessary if
dojo.behavior had a .remove() method (perhaps based on a handle returned from add()?)

noteworthy: this technically changes the API of an unsupported, unused param "finalize" (probably used in older days for
global cleanup, but unused since 0.9) to "preserveDom" ... true meaning "leave the node alone".

includes simple testcase to check widget count in registry, could easily be converted to unit test.

!strict

Location:

dijit/trunk

Files:

• tests/test_WidgetPreserve.html (added)
• _Widget.js (modified) (3 diffs)

dijit/trunk/_Widget.js

@@ -202 +202 @@
         //////////// DESTROY FUNCTIONS ////////////////////////////////
 
-        destroyRecursive: function(/*Boolean*/ finalize){
+        destroyRecursive: function(/*Boolean*/ preserveDom){
                 // summary:
                 //              Destroy this widget and it's descendants. This is the generic
@@ -208 +208 @@
                 //              cleanly discard with a widget. Once a widget is destroyed, it's
                 //              removed from the manager object.
-                // finalize: Boolean
-                //              is this function being called part of global environment
-                //              tear-down?
-
-                this.destroyDescendants();
-                this.destroy();
-        },
-
-        destroy: function(/*Boolean*/ finalize){
+                // preserveDom: Boolean
+                //              If true, this method will leave the original Dom structure alone
+                //              of descendant Widgets. Note: This will NOT work with _Templated
+                //              widgets.
+                //
+                this.destroyDescendants(preserveDom);
+                this.destroy(preserveDom);
+        },
+
+        destroy: function(/*Boolean*/ preserveDom){
                 // summary:
                 //              Destroy this widget, but not its descendants
-                // finalize: Boolean
-                //              is this function being called part of global environment
-                //              tear-down?
+                // preserveDom: Boolean
+                //              If true, this method will leave the original Dom structure alone.
+                //              Note: This will not yet work with _Templated widgets
 
                 this.uninitialize();
@@ -231 +232 @@
                 dojo.forEach(this._supportingWidgets || [], function(w){ w.destroy(); });
                 
-                this.destroyRendering(finalize);
+                this.destroyRendering(preserveDom);
                 dijit.registry.remove(this.id);
         },
 
-        destroyRendering: function(/*Boolean*/ finalize){
+        destroyRendering: function(/*Boolean*/ preserveDom){
                 // summary:
                 //              Destroys the DOM nodes associated with this widget
-                // finalize: Boolean
-                //              is this function being called part of global environment
-                //              tear-down?
-
+                // preserveDom: Boolean
+                //              If true, this method will leave the original Dom structure alone
+                //              during tear-down. Note: this will not work with _Templated
+                //              widgets yet. 
+                
                 if(this.bgIframe){
-                        this.bgIframe.destroy();
+                        this.bgIframe.destroy(preserveDom);
                         delete this.bgIframe;
                 }
 
                 if(this.domNode){
-                        dojo._destroyElement(this.domNode);
+                        if(!preserveDom){
+                                dojo._destroyElement(this.domNode);
+                        }
                         delete this.domNode;
                 }
 
                 if(this.srcNodeRef){
-                        dojo._destroyElement(this.srcNodeRef);
+                        if(!preserveDom){
+                                dojo._destroyElement(this.srcNodeRef);
+                        }
                         delete this.srcNodeRef;
                 }
         },
 
-        destroyDescendants: function(){
+        destroyDescendants: function(/* Boolean */ preserveDom){
                 // summary:
                 //              Recursively destroy the children of this widget and their
                 //              descendants.
-
+                // preserveDom: Boolean
+                //              If true, the preserveDom attribute is passed to all descendant
+                //              widget's .destroy() method. Not for use with _Templated widgets.
+                
                 // TODO: should I destroy in the reverse order, to go bottom up?
-                dojo.forEach(this.getDescendants(), function(widget){ widget.destroy(); });
+                dojo.forEach(this.getDescendants(), function(widget){ widget.destroy(preserveDom); });
         },