destroy

Allowing Garbage Collection

Destroy is called whenever a control's element is removed from the page using the library's standard HTML modifier methods. This means that you don't have to call destroy yourself and it will be called automatically when appropriate.

The following Clicker widget listens on the window for clicks and updates its element's innerHTML. If we remove the element, the window's event handler is removed auto-magically:

 Clickr = can.Control({
  "{window} click": function() {
    this.element.html( this.count ?
    this.count++ : this.count = 0 );
  }
});

// create a clicker on an element
new Clicker( "#clickme" );

// remove the element
$( '#clickme' ).remove();

The methods you can use that will destroy controls automatically by library:

jQuery and Zepto

• $.fn.remove
• $.fn.html
• $.fn.replaceWith
• $.fn.empty

Dojo

• dojo.destroy
• dojo.empty
• dojo.place (with the replace option)

Mootools

• Element.prototype.destroy

YUI

• Y.Node.prototype.remove
• Y.Node.prototype.destroy

Teardown in Destroy

Sometimes, you want to reset a controlled element back to its original state when the control is destroyed. Overwriting destroy lets you write teardown code of this manner. When overwriting destroy, make sure you call Control's base functionality.

The following example changes an element's text when the control is created and sets it back when the control is removed:

Changer = can.Control.extend({
  init: function() {
    this.oldText = this.element.text();
    this.element.text( "Changed!!!" );
  },
  destroy: function() {
    this.element.text( this.oldText );
    can.Control.prototype.destroy.call( this );
  }
});

// create a changer which changes #myel's text
var changer = new Changer( '#myel' );

// destroy changer which will reset it
changer.destroy();

Base Functionality

Control prepares the control for garbage collection by:

• unbinding all event handlers
• clearing references to this.element and this.options
• clearing the element's reference to the control
• removing it's [can.Control.pluginName] from the element's className