Declarative event bindings
JavaScript HTML
Latest commit 4584008 Jan 4, 2017 @phillipskevin phillipskevin committed on GitHub Merge pull request #46 from canjs/greenkeeper/can-util-3.2.2
chore(package): update can-util to version 3.2.2
Permalink
Failed to load latest commit information.
docs Added package.json to docs Oct 12, 2016
test moving test.html to match other repos Sep 19, 2016
.editorconfig tests pass Apr 18, 2016
.gitignore
.jshintrc
.npmignore
.travis.yml tests pass Apr 18, 2016
build.js using can-namespace, can-types Dec 14, 2016
can-control.js
can-control_test.js using can-namespace, can-types Dec 14, 2016
control.processor.md
package.json chore(package): update can-util to version 3.2.2 Jan 3, 2017
readme.md

readme.md

can-control

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.

  2. selector {CSSSelectorString}: A CSS selector for event delegation.
  3. eventName {String}: The name of the event to listen for.
  4. 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