can

<!DOCTYPE html>  <html lang="en"> <head> <meta charset="utf-8"> <title>CanJS - on</title> <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no"> <link rel="stylesheet" type="text/css" href="./static/bundles/bit-docs-site/static.css"> <link rel="shortcut icon" sizes="16x16 24x24 32x32 48x48 64x64" href="/docs/images/canjs_favicon.ico"> <link rel="apple-touch-icon" sizes="57x57" href="../docs/images/canjs_favicon_57x57.png"> <link rel="apple-touch-icon-precomposed" sizes="57x57" href="../docs/images/canjs_favicon_57x57.png"> <link rel="apple-touch-icon" sizes="72x72" href="../docs/images/canjs_favicon_72x72.png"> <link rel="apple-touch-icon" sizes="114x114" href="../docs/images/canjs_favicon_114x114.png"> <link rel="apple-touch-icon" sizes="120x120" href="../docs/images/canjs_favicon_128x128.png"> <link rel="apple-touch-icon" sizes="144x144" href="../docs/images/canjs_favicon_144x144.png"> <link rel="apple-touch-icon" sizes="152x152" href="../docs/images/canjs_favicon_152x152.png"> <meta content="yes" name="apple-mobile-web-app-capable"> <meta name="apple-mobile-web-app-status-bar-style" content="white-translucent"> <script> (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) })(window,document,'script','https://www.google-analytics.com/analytics.js','ga'); ga('create', 'UA-2302003-11', 'auto'); ga('send', 'pageview'); </script> </head> <body> <input type="checkbox" id="nav-trigger" class="nav-trigger"/> <label for="nav-trigger">Menu</label> <div id="everything"> <div id="left" class="column"> <div class="top-left"> <div class="brand"> <div class="logo"> <a href="../index.html" alt="CanJS"></a> <div class="dropdown project-dropdown"> <a href="https://donejs.com/">DoneJS</a> <a href="http://stealjs.com/">StealJS</a> <a href="http://jquerypp.com/">jQuery ++</a> <a href="https://funcunit.com/">FuncUnit</a> <a href="http://documentjs.com/">DocumentJS</a> </div> </div> <div class="version"> <div class="version-number"> 3.0.0 </div> <div class="dropdown version-dropdown"> <a href="https://v2.canjs.com">2.3.27</a> </div> </div> </div> <div class="search-bar"> <p>   </p> </div> </div> <div class="bottom-left"> <div class="social-side-container"> <ul class="social-side"> <li> <a class="header-mobile github" href="https://github.com/canjs/canjs" target="_blank"><img class="social-icon-small" src="../docs/images/github.png">Github</a> </li> <li> <a class="header-mobile twitter" href="https://twitter.com/canjs" target="_blank"><img class="social-icon-small" src="../docs/images/twitter.png">Twitter</a> </li> </ul> <ul class="social-side"> <li> <a class="header-mobile" href="https://gitter.im/canjs/canjs" target="_blank">Chat</a> </li> <li> <a class="header-mobile" href="http://forums.donejs.com/c/canjs" target="_blank">Forum</a> </li> </ul> </div> <ul> <li class=" "> <a class="page" href="guides.html" title="Welcome to CanJS! These guides are here to help you develop and improve your relationship with CanJS. After all, picking a JavaScript framework is a commitment. We want CanJS to be the framework you marry. This page helps you know how advance through the different stages of this relationship:"> Guides </a> </li> <li class=" "> <a class="page" href="can-core.html" title="The best, most hardened and generally useful libraries in CanJS."> Core </a> </li> <li class=" "> <a class="page" href="can-ecosystem.html" title="Useful libraries that extend or add important features to the core collection."> Ecosystem </a> </li> <li class=" parent expanded"> <a class="page" href="can-infrastructure.html" title="Utility libraries that power the core and ecosystem collection."> Infrastructure </a> <ul> <li class=" "> <a class="module" href="can-construct.html" title="Provides a way to easily use the power of prototypal inheritance without worrying about hooking up all the particulars yourself. Use can-construct.extend to create an inheritable constructor function of your own."> can-construct </a> </li> <li class=" parent expanded"> <a class="module" href="can-control.html" title="Create organized, memory-leak free, rapidly performing, stateful controls with declarative event binding. Use 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."> can-control </a> <ul> <li> <span>static</span> <ul> <li class=" "> <a class="property" href="can-control.defaults.html" title="Default values for the Control's options."> defaults </a> </li> <li class=" "> <a class="function" href="can-control.extend.html" title=""> extend </a> </li> <li class=" "> <a class="property" href="can-control.processors.html" title="A collection of hookups for custom events on Controls."> processors </a> </li> </ul> </li> <li> <span>prototype</span> <ul> <li class=" "> <a class="function" href="can-control.prototype.destroy.html" title="Remove a Control from an element and clean up the Control."> destroy </a> </li> <li class=" "> <a class="property" href="can-control.prototype.element.html" title="The element passed to the Control when creating a new instance."> element </a> </li> <li class="current parent expanded"> <a class="function" href="can-control.prototype.on.html" title="Bind an event handler to a Control, or rebind all event handlers on a Control."> on </a> </li> <li class=" "> <a class="property" href="can-control.prototype.options.html" title="Options used to configure a control."> options </a> </li> <li class=" "> <a class="function" href="can-control.prototype.setup.html" title="Perform pre-initialization logic for control instances and classes."> setup </a> </li> </ul> </li> </ul> </li> <li class=" "> <a class="module" href="can-event.html" title="Add event functionality into your objects. The canEvent object provides a number of methods for handling events in objects. This functionality is best used by mixing the canEvent object into an object or prototype. However, event listeners can still be used even on objects that don't include canEvent. All methods provided by canEvent assume that they are mixed into an object -- this should be the object dispatching the events."> can-event </a> </li> <li class=" "> <a class="module" href="can-event/async/async.html" title="Makes the event system asynchronous. WARNING: This is experimental technology."> can-event/async/async </a> </li> <li class=" "> <a class="module" href="can-event/batch/batch.html" title="Adds task batching abilities to event dispatching."> can-event/batch/batch </a> </li> <li class=" "> <a class="module" href="can-observation.html" title="Provides a mechanism to notify when an observable has been read and a way to observe those reads called within a given function."> can-observation </a> </li> <li class=" "> <a class="module" href="can-simple-map.html" title="A performant live-bound map."> can-simple-map </a> </li> <li class=" "> <a class="page" href="can-util.html" title="A set of utilities."> can-util </a> </li> <li class=" "> <a class="module" href="can-view-callbacks.html" title="Registered callbacks for behaviors"> can-view-callbacks </a> </li> <li class=" "> <a class="module" href="can-view-live.html" title="Setup live-binding between the DOM and a compute manually."> can-view-live </a> </li> <li class=" "> <a class="module" href="can-view-model.html" title="Gets the ViewModel of an element."> can-view-model </a> </li> <li class=" "> <a class="module" href="can-view-nodelist.html" title="Adds nesting of text nodes can.view.nodeLists are used to make sure "directly nested" live-binding sections update content correctly. Consider the following template: <div> {{#if items.length}} Items: {{#items}} <label></label> {{/items}} {{/if}} </div> The {{#if}} and {{#items}} seconds are "directly nested" because they share the same <div> parent element. If {{#items}} changes the DOM by adding more <labels>, {{#if}} needs to know about the <labels> to remove them if {{#if}} is re-rendered. {{#if}} would be re-rendered, for example, if all items were removed."> can-view-nodelist </a> </li> <li class=" "> <a class="module" href="can-view-parser.html" title="Parse HTML and mustache tokens."> can-view-parser </a> </li> <li class=" "> <a class="module" href="can-view-scope.html" title="Create a lookup node for keys."> can-view-scope </a> </li> <li class=" "> <a class="module" href="can-view-target.html" title=""> can-view-target </a> </li> </ul> </li> <li class=" "> <a class="page" href="can-legacy.html" title="Former libraries that we still accept patches for, but are not under active development."> Legacy </a> </li> </ul> </div> </div> <div id="right" class="column"> <div class="top-right"> <div class="top-right-top"> <ul class="top-right-bitovi"> <li class="dropdown"> <a href="http://bitovi.com" class="bitovi icon-bits">Bitovi</a> <ul class="dropdown-menu"> <li><a href="http://bitovi.com">Bitovi.com</a></li> <li><a href="http://bitovi.com/blog/">Blog</a></li> <li><a href="http://bitovi.com/consulting/">Consulting</a></li> <li><a href="http://bitovi.com/training/">Training</a></li> <li><a href="http://bitovi.com/open-source/">Open Source</a></li> </ul> </li> </ul> <div class="brand"> <div class="logo"> <a href="../index.html" alt="CanJS"></a> </div> </div> <ul class="top-right-links"> <li> <a href="https://gitter.im/canjs/canjs">Chat</a> </li> <li> <a href="http://forums.donejs.com/c/canjs">Forum</a> </li> <li> <a class="github-button nav-social" href="https://github.com/canjs/canjs" data-count-href="/canjs/canjs/stargazers" data-count-api="/repos/canjs/canjs#stargazers_count">Star</a> </li> <li> <a href="https://twitter.com/canjs" class="twitter-follow-button nav-social" data-show-count="true" data-show-screen-name="false">Follow @canjs</a><script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script> </li> </ul> </div> <div class="breadcrumb"> <li><a href="../index.html">CanJS</a></li> / <li><a href="can-infrastructure.html">Infrastructure</a></li> / <li><a href="can-control.html">can-control</a></li> / <li><a href="can-control.prototype.on.html">on</a></li> <li class="breadcrumb-dropdown">/ <a> On this page</a> <ul class="on-this-page"></ul> </li> <div class="nav-toggle" title="Back to top"></div> </div> </div> <div class="bottom-right"> <article> <section class="title"> <div class="page-type"> <h1>on</h1> <div>function</div> </div> <section class="description"> <p>Bind an event handler to a Control, or rebind all event handlers on a Control.</p> </section> </section> <section class="on-this-page-table"> </section> <section class="title-footer"> <ul class="title-links">  <li><a href="//github.com/canjs/can-control/tree/v3.0.3/docs/on.md">source</a></li>   </ul> </section> <div class="signature"> <h2 class="signature-title"> <code>control.on([el,] selector, eventName, func)</code> </h2> <div class="parameters"> <h3 class="parameters-title">Parameters</h3> <ol> <li><b>el</b> <code>{HTMLElement|jQuery|collection|Object}</code>: <p>The element to be bound. If no element is provided, the control's element is used instead.</p> </li> <li><b>selector</b> <code>{CSSSelectorString}</code>: <p>A CSS selector for event delegation.</p> </li> <li><b>eventName</b> <code>{String}</code>: <p>The name of the event to listen for.</p> </li> <li><b>func</b> <code>{function|String}</code>: <p>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.</p> </li> </ol> </div> <div class="returns"> <h3 class="returns-title">Returns</h3> <p> <code>{Number}</code>: <p>The id of the binding in this._bindings.</p> <p><code>on(el, selector, eventName, func)</code> binds an event handler for an event to a selector under the scope of the given element.</p> </p> </div> </div> <div class="signature"> <h2 class="signature-title"> <code>control.on()</code> </h2> <p>Rebind all of a control's event handlers.</p> <div class="returns"> <h3 class="returns-title">Returns</h3> <p> <code>{Number}</code>: <p>The number of handlers bound to this Control.</p> </p> </div> </div> <section class="body"> <p><code>this.on()</code> is used to rebind all event handlers when <a href="can-control.prototype.options.html" title="Options used to configure a control.">this.options</a> has changed. It can also be used to bind or delegate from other elements or objects.</p> <h2>Rebinding</h2> <p>By using templated event handlers, a control can listen to objects outside <code>this.element</code>. This is extremely common in MVC programming. For example, the following control might listen to a task model's <code>completed</code> property and toggle a strike className like:</p> <pre><code>TaskStriker = Control({ "{task} completed": function(){ this.update(); }, update: function(){ if ( this.options.task.completed ) { this.element.addClass( 'strike' ); } else { this.element.removeClass( 'strike' ); } } }); var taskstriker = new TaskStriker({ task: new Task({ completed: 'true' }) }); </code></pre> <p>To update the <code>taskstriker</code>'s task, add a task method that updates this.options and rebinds the event handlers for the new task like:</p> <pre><code>TaskStriker = Control({ "{task} completed": function(){ this.update(); }, update: function() { if ( this.options.task.completed ) { this.element.addClass( 'strike' ); } else { this.element.removeClass( 'strike' ); } }, task: function( newTask ) { this.options.task = newTask; this.on(); this.update(); } }); var taskstriker = new TaskStriker({ task: new Task({ completed: true }) }); // Now, add a new task that is not yet completed taskstriker.task(new Task({ completed: false })); </code></pre> <h2>Adding new events</h2> <p>If events need to be bound to outside of the control and templated event handlers are not sufficient, you can call this.on to bind or delegate programmatically:</p> <pre><code>init: function() { // calls somethingClicked( el, ev ) this.on( 'click', 'somethingClicked' ); // calls function when the window is clicked this.on( window, 'click', function( ev ) { // do something }); }, somethingClicked: function( el, ev ) { // ... } </code></pre> </section> <script type="text/javascript"> var docObject = {"src":{"path":"node_modules/can-control/docs/on.md"},"description":"Bind an event handler to a Control, or rebind all event handlers on a Control. \n","title":"on","name":"can-control.prototype.on","type":"function","parent":"can-control.prototype","signatures":[{"code":"control.on([el,] selector, eventName, func)","description":"","params":[{"types":[{"type":"HTMLElement"},{"type":"jQuery"},{"type":"collection"},{"type":"Object","options":[]}],"optional":true,"name":"el","defaultValue":"this.element","description":"\nThe element to be bound. If no element is provided, the control's element is used instead."},{"types":[{"type":"CSSSelectorString"}],"name":"selector","description":"A CSS selector for event delegation."},{"types":[{"type":"String"}],"name":"eventName","description":"The name of the event to listen for."},{"types":[{"type":"function","returns":{"types":[{"type":"undefined"}]},"params":[]},{"type":"String"}],"name":"func","description":"A callback function or the String name of a control function. If a control\nfunction name is given, the control function is called back with the bound element and event as the first\nand second parameter. Otherwise the function is called back like a normal bind."}],"returns":{"types":[{"type":"Number"}],"description":"The id of the binding in this._bindings.\n\n`on(el, selector, eventName, func)` binds an event handler for an event to a selector under the scope of the given element.\n"}},{"code":"control.on()","description":"\n\nRebind all of a control's event handlers.\n","params":[],"returns":{"types":[{"type":"Number"}],"description":"The number of handlers bound to this Control.\n"}}],"_curReturn":{"types":[{"type":"Number"}],"description":"The number of handlers bound to this Control.\n"},"comment":" ","pathToRoot":".."}; </script> </article> <footer><p>CanJS is part of <a href="http://donejs.com" target="_blank">DoneJS</a>. Created and maintained by the core <a href="https://donejs.com/About.html#section=section_Team" target="_blank">DoneJS team</a> and <a href="http://bitovi.com" target="_blank">Bitovi</a>. <strong>Currently 3.0.0.</strong></p></footer> </div> </div> </div> <script> steal = { instantiated: { "bundles/bit-docs-site/static.css!$css" : null } }; </script> <script type='text/javascript' data-main="bit-docs-site/static" src="./static/node_modules/steal/steal.production.js"></script> <script async defer src="https://buttons.github.io/buttons.js"></script> </body> </html>