The control instance's HTMLElement (or window) wrapped by the util library for ease of use.

It is set by the first parameter to new Construct( element, options ) in [can.Control::setup]. By default, a control listens to events on this.element.

Example - NodeList

The following HelloWorld control sets the control`s text to "Hello World":

HelloWorld = Control({
    init: function(){
        this.element.text( 'Hello World' );
    }
});

// create the controller on the element
new HelloWorld( document.getElementById( '#helloworld' ) );

Wrapped NodeList

this.element is a wrapped NodeList of one HTMLELement (or window). This is for convenience in libraries like jQuery where all methods operate only on a NodeList. To get the raw HTMLElement, write:

this.element[0] //-> HTMLElement

The following details the NodeList used by each library with an example of updating its text:

jQuery jQuery( HTMLElement )

this.element.text("Hello World")

Zepto Zepto( HTMLElement )

this.element.text("Hello World")

Dojo new dojo.NodeList( HTMLElement )

this.element.text("Hello World")

Mootools $$( HTMLElement )

this.element.empty().appendText("Hello World")

YUI

this.element.set("text", "Hello World")

Changing this.element

Sometimes you don't want what's passed to new Control to be this.element. You can change this by overwriting setup or by unbinding, setting this.element, and rebinding.

Overwriting Setup

The following Combobox overwrites setup to wrap a select element with a div. That div is used as this.element. Notice how destroy sets back the original element.

Combobox = Control({
    setup: function( el, options ) {
        this.oldElement = $( el );
        var newEl = $( '<div/>' );
        this.oldElement.wrap( newEl );
        can.Control.prototype.setup.call( this, newEl, options );
    },
    init: function() {
        this.element //-> the div
    },
    "{element} .option click": function() {
        // event handler bound on the div
    },
    destroy: function() {
        var div = this.element; //save reference
        Control.prototype.destroy.call( this );
        div.replaceWith( this.oldElement );
    }
});

Unbinding, setting, and rebinding.

You could also change this.element by calling [can.Control::off], setting this.element, and then calling [can.Control::on] like:

move: function( newElement ) {
    this.off();
    this.element = $( newElement );
    this.on();
}