node package manager
Easy collaboration. Discover, share, and reuse code in your team. Create a free org ยป

can-control

can-control

Greenkeeper badge

Build Status

API

can-control

Create organized, memory-leak free, rapidly performing, stateful controls with declarative event binding. Use can.Control to create UI controls like tabs, grids, and context menus, and organize them into higher-order business rules with [can.route]. It can serve as both a traditional view and a traditional controller.

Control( [staticProperties,] instanceProperties )

Create a new, extended, control constructor function. This functionality is inherited from [can.Construct] and is deprecated in favor of using [can.Control.extend].

  1. staticProperties {Object}: An object of properties and methods that are added the control constructor function directly. The most common property to add is [can.Control.defaults].

  2. instanceProperties {Object}: An object of properties and methods that belong to instances of the Control constructor function. These properties are added to the control's prototype object. Properties that look like event handlers (ex: "click" or "li mouseenter") are setup as event handlers (see Listening to events).

  • returns {constructor(element, options) => can.Construct}: A control constructor function that has been extended with the provided staticProperties and instanceProperties.

new Control( element, options )

Create an instance of a control. [can.Control.prototype.setup] processes the arguments and sets up event binding. Write your initialization code in [can.Control.prototype.init]. Note, you never call new can.Control() directly, instead, you call it on constructor functions extended from can.Control.

  1. element {HTMLElement|can.NodeList|CSSSelectorString}: Specifies the element the control will be created on.

  2. options {Object}: Option values merged with [can.Control.defaults can.Control.defaults] and set as [can.Control.prototype.options this.options].

  • returns {}: A new instance of the constructor function extending can.Control.

Control.extend([staticProperties,] instanceProperties)

Create a new, extended, control constructor function.

  1. staticProperties {Object}: An object of properties and methods that are added the control constructor function directly. The most common property to add is [can.Control.defaults].

  2. instanceProperties {Object}: An object of properties and methods that belong to instances of the can.Control constructor function. These properties are added to the control's prototype object. Properties that look like event handlers (ex: "click" or "li mouseenter") are setup as event handlers.

  • returns {constructor(element, options) => can.Construct}: A control constructor function that has been extended with the provided staticProperties and instanceProperties.

defaults {Object}

Default values for the Control's options.

Object

processors {Object\<[can.Control.processor](#-functionelement-eventname-selector-handler-undefined)(element, eventName, selector, handler, undefined)\>}

A collection of hookups for custom events on Controls.

Object<can.Control.processor(element, eventName, selector, handler, undefined)>

control.destroy()

Prepares a control for garbage collection and is a place to reset any changes the control has made.

element {can.NodeList}

The element passed to the Control when creating a new instance.

can.NodeList

control.on([el,] selector, eventName, func)

  1. el {HTMLElement|jQuery|collection|Object}:

The element to be bound. If no element is provided, the control's element is used instead.

  1. selector {CSSSelectorString}: A CSS selector for event delegation.
  2. eventName {String}: The name of the event to listen for.
  3. func {function|String}: A callback function or the String name of a control function. If a control function name is given, the control function is called back with the bound element and event as the first and second parameter. Otherwise the function is called back like a normal bind.
  • returns {Number}: The id of the binding in this._bindings.

    on(el, selector, eventName, func) binds an event handler for an event to a selector under the scope of the given element.

control.on()

Rebind all of a control's event handlers.

  • returns {Number}: The number of handlers bound to this Control.

options {Object}

Options used to configure a control.

Object

control.setup(element, options)

  1. element {HTMLElement|NodeList|String}: The element as passed to the constructor.
  2. options {Object}: option values for the control. These get added to this.options and merged with [can.Control.static.defaults defaults].
  • returns {undefined|Array}: return an array if you want to change what init is called with. By default it is called with the element and options passed to the control.

Contributing

Making a Build

To make a build of the distributables into dist/ in the cloned repository run

npm install
node build

Running the tests

Tests can run in the browser by opening a webserver and visiting the test.html page. Automated tests that run the tests from the command line in Firefox can be run with

npm test