Difference between destroy(), destroyRecursive(true), destroyDescendants()

Question

While creating a widget i checking for existence of a div like below then destroying the content & again creating.

if (dijit.byId("TPContainer")) {
    dijit.byId("TPContainer").destroyRecursive(true);
    dojo.place('<div id="TPContainer"></div>',dojo.byId("TitleContainer"));
}

But before loading a HTML template

var container = dijit.byId("mainContainer");
container.destroyDescendants();
container.set("href", TemplateLink);

I just took the code from elsewhere. But not clear about the concept. I don't know when to use which destroy function available with Dojo. can somebody explain when to use which destroy function? & what differentiate them?

Answer 1

Taking a look at the Dojo api (currently 1.10) these methods are defined in _WidgetBase (though destroy comes from dijit/Destroyable) and inherited by all widgets. Since these are kind of buried in the api docs and not written in the _Widgetbase tutorial page I will list them here.

Internally, destroyBlah methods call destroy for themselves (where applicable) and their children so these function as simply helper methods to make it easier to destroy things.

---

destroy(preserveDom)

Parameter: preserveDom

Type: Boolean

Description: If true, this method will leave the original DOM structure alone. Note: This will not yet work with _TemplatedMixin widgets

Summary:

Destroy this widget, but not its descendants. Descendants means widgets inside of this.containerNode. Will also destroy any resources (including widgets) registered via this.own().

This method will also destroy internal widgets such as those created from a template, assuming those widgets exist inside of this.domNode but outside of this.containerNode.

For 2.0 it's planned that this method will also destroy descendant widgets, so apps should not depend on the current ability to destroy a widget without destroying its descendants. Generally they should use destroyRecursive() for widgets with children.

---

destroyDescendants(preserveDom)

Parameter: preserveDom

Type: Boolean

Description: (Optional) If true, the preserveDom attribute is passed to all descendant widget's .destroy() method. Not for use with _Templated widgets.

Summary:

Recursively destroy the children of this widget and their descendants.

---

destroyRecursive(preserveDom)

Parameter: preserveDom

Type: Boolean

Description: (Optional) If true, this method will leave the original DOM structure alone of descendant Widgets. Note: This will NOT work with dijit._TemplatedMixin widgets.

Destroy this widget and its descendants

This is the generic "destructor" function that all widget users should call to cleanly discard with a widget. Once a widget is destroyed, it is removed from the manager object.

---

In your first example, destroyRecursive will call destroy on the widget (but not the dom element because of the true parameter) that it is being called on. Contrast that to your second example where destroy is being called on only descendents of the widget that it's being called on. Since there is no preserveDom specified, it will destroy the dom elements as well as the widget registries.