can

<!DOCTYPE html>  <html lang="en"> <head> <meta charset="utf-8"> <title>CanJS - can-event/batch/batch</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=" "> <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> </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="../async/async.html" title="Makes the event system asynchronous. WARNING: This is experimental technology."> can-event/async/async </a> </li> <li class="current parent expanded"> <a class="module" href="batch.html" title="Adds task batching abilities to event dispatching."> can-event/batch/batch </a> <ul> <li class=" "> <a class="function" href="batch.afterPreviousEvents.html" title="Run code when all previuos state has settled."> afterPreviousEvents </a> </li> <li class=" "> <a class="function" href="batch.collecting.html" title=""> collecting </a> </li> <li class=" "> <a class="function" href="batch.dispatch.html" title="Dispatchs an event within the event batching system."> dispatch </a> </li> <li class=" "> <a class="function" href="batch.dispatching.html" title=""> dispatching </a> </li> <li class=" "> <a class="function" href="batch.queue.html" title="Queues a method to be called."> queue </a> </li> <li class=" "> <a class="function" href="batch.start.html" title="Begin an event batch."> start </a> </li> <li class=" "> <a class="function" href="batch.stop.html" title="End an event batch."> stop </a> </li> </ul> </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="batch.html">can-event/batch/batch</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>can-event/batch/batch</h1> <div>module</div> </div> <section class="description"> <p>Adds task batching abilities to event dispatching.</p> </section> </section> <section class="on-this-page-table"> </section> <section class="title-footer"> <ul class="title-links">  <li><a href="//github.com/canjs/canjs/tree/v3.0.0/node_modules/can-event/batch/batch.md">source</a></li>   </ul> </section> <div class="signature"> <h2 class="signature-title"> <code>Object</code> </h2> <p>The <code>can-event/batch/batch</code> module adds task batching abilities to the <a 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> module. It:</p> <ul> <li>Provides a <a href="batch.queue.html" title="Queues a method to be called.">queue</a> method to add batched work.</li> <li>Provides <a href="batch.dispatch.html" title="Dispatchs an event within the event batching system.">dispatch</a> and overwrites <a href="../../can-event.dispatch.html" title="can-event.dispatch">can-event.dispatch</a> to use the task queue when dispatching events.</li> <li>Provides a <a href="batch.start.html" title="Begin an event batch.">start</a> and <a href="batch.stop.html" title="End an event batch.">stop</a> method that can create a new task queue.</li> <li>Provides <a href="batch.collecting.html" title="">collecting</a> which returns the queue collecting tasks.</li> <li>Provides <a href="batch.dispatching.html" title="">dispatching</a> which returns the queue dispatching tasks.</li> <li>Dispatches <code>batchEnd</code> when a queue's tasks have been completed.</li> </ul> </div> <section class="body"> <h2>Use</h2> <p>To batch events, call <a href="batch.start.html" title="Begin an event batch.">start</a>, then make changes that <a href="batch.dispatch.html" title="Dispatchs an event within the event batching system.">dispatch</a> batched events, then call <a href="batch.stop.html" title="End an event batch.">stop</a>.</p> <p>For example, a map might have a <code>first</code> and <code>last</code> property:</p> <pre><code class="language-js">var Person = DefineMap.extend({ first: "string", last: "string" }); var baby = new Person({first: "Roland", last: "Shah"}); </code></pre> <p>Normally, when <code>baby</code>'s <code>first</code> and <code>last</code> are fired, those events are dispatched immediately:</p> <pre><code class="language-js">baby.on("first", function(ev, newFirst){ console.log("first is "+newFirst); }).on("last", function(ev, newLast){ console.log("last is "+newLast); }); baby.first = "Ramiya"; // console.logs -> "first is Ramiya" baby.last = "Meyer"; // console.logs -> "first is Meyer" </code></pre> <p>However, if a batch is used, events will not be dispatched until <a href="batch.stop.html" title="End an event batch.">stop</a> is called:</p> <pre><code class="language-js">var canBatch = require("can-event/batch/batch"); canBatch.start(); baby.first = "Lincoln"; baby.last = "Sullivan"; canBatch.stop(); // console.logs -> "first is Lincoln" // console.logs -> "first is Sullivan" </code></pre> <h2>Performance</h2> <p>CanJS synchronously dispatches events when a property changes. This makes certain patterns easier. For example, if you are utilizing live-binding and change a property, the DOM is immediately updated.</p> <p>Occasionally, you may find yourself changing many properties at once. To prevent live-binding from performing unnecessary updates, update the properties within a pair of calls to <code>canBatch.start</code> and <code>canBatch.stop</code>.</p> <p>Consider a todo list with a <code>completeAll</code> method that marks every todo in the list as complete and <code>completeCount</code> that counts the number of complete todos:</p> <pre><code class="language-js">var Todo = DefineMap.extend({ name: "string", complete: "boolean" }); var TodoList = DefineList.extend({ "#": Todo, completeAll: function(){ this.forEach(function(todo){ todo.complete = true; }) }, completeCount: function(){ return this.filter({complete: true}).length; } }) </code></pre> <p>And a template that uses the <code>completeCount</code> and calls <code>completeAll</code>:</p> <pre><code><ul> {{#each todos}} <li><input type='checklist' {($checked)}="complete"/> {{name}}</li> {{/each}} </ul> <button ($click)="todos.completeAll()"> Complete {{todos.completeCount}} todos </button> </code></pre> <p>When <code>completeAll</code> is called, the <code>{{todos.completeCount}}</code> magic tag will update once for every completed count. We can prevent this by wrapping <code>completeAll</code> with calls to <code>start</code> and <code>stop</code>:</p> <pre><code class="language-js"> completeAll: function(){ canBatch.start(); this.forEach(function(todo){ todo.complete = true; }); canBatch.end(); }, </code></pre> <h2>batchNum</h2> <p>All events created within a set of <code>start</code> / <code>stop</code> calls share the same batchNum value. This can be used to respond only once for a given batchNum.</p> <pre><code>var batchNum; person.on("name", function(ev, newVal, oldVal) { if(!ev.batchNum || ev.batchNum !== batchNum) { batchNum = ev.batchNum; // your code here! } }); </code></pre> </section> <script type="text/javascript"> var docObject = {"src":{"path":"node_modules/can-event/batch/batch.md"},"description":"Adds task batching abilities to event dispatching. \n","type":"module","title":"","types":[{"type":"Object","options":[]}],"name":"can-event/batch/batch","parent":"can-infrastructure","signatures":[{"code":"Object","description":"\n\nThe `can-event/batch/batch` module adds task batching abilities to\nthe [can-event] module. It:\n\n - Provides a [can-event/batch/batch.queue] method to add batched work.\n - Provides [can-event/batch/batch.dispatch] and overwrites [can-event.dispatch can-event.dispatch] to use the task queue when dispatching events.\n - Provides a [can-event/batch/batch.start] and [can-event/batch/batch.stop] method that can create a new task queue.\n - Provides [can-event/batch/batch.collecting] which returns the queue collecting tasks.\n - Provides [can-event/batch/batch.dispatching] which returns the queue dispatching tasks.\n - Dispatches `batchEnd` when a queue's tasks have been completed.\n","params":[]}],"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>