can

<!DOCTYPE html>  <html lang="en"> <head> <meta charset="utf-8"> <title>CanJS - API Guide</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=" parent expanded"> <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> <ul> <li> <span>introduction</span> <ul> <li class=" "> <a class="page" href="mission.html" title="Learn about CanJS's mission, why it matters, and how we've worked (and will keep working) to accomplish it."> Mission </a> </li> <li class=" "> <a class="page" href="technical.html" title=""> Technical Highlights </a> </li> <li class=" "> <a class="page" href="who-uses-canjs.html" title=""> Who uses CanJS? </a> </li> </ul> </li> <li> <span>experiment</span> <ul> <li class=" "> <a class="page" href="chat.html" title="This guide walks through building real time chat application with CanJS's Core libraries. It takes about 30 minutes to complete."> Chat Guide </a> </li> <li class=" "> <a class="page" href="todomvc.html" title="This guide walks through building a slightly modified version of TodoMVC with CanJS's Core libraries and can-fixture. It takes about 1 hour to complete."> TodoMVC Guide </a> </li> <li class=" "> <a class="page" href="atm.html" title="This guide walks through building and testing an ATM application with CanJS's Core libraries. It teaches how to do test driven development (TDD) and manage complex state. It takes about 2 hours to complete."> ATM Guide </a> </li> <li class=" "> <a class="page" href="setup.html" title="CanJS is packaged in multiple ways so that it can fit into any development workflow. Learn how to setup CanJS in different environments."> Setting up CanJS </a> </li> </ul> </li> <li> <span>commitment</span> <ul> <li class="current parent expanded"> <a class="page" href="api.html" title="This page walks through how to use and understand CanJS's API documentation."> API Guide </a> </li> <li class=" "> <a class="page" href="examples.html" title=""> Examples </a> </li> <li class=" "> <a class="page" href="../roadmap.html" title="Learn about CanJS's future plans and how we make them, and how you can influence them."> Roadmap </a> </li> <li class=" "> <a class="page" href="../migrate-3.html" title=""> Migrating to 3.0 </a> </li> </ul> </li> <li> <span>contribute</span> <ul> <li class=" "> <a class="page" href="contributing/bug-report.html" title="Learn how to submit a bug report."> Bug Report </a> </li> <li class=" "> <a class="page" href="contributing/code.html" title="Learn how contribute a code change to CanJS."> Code </a> </li> <li class=" "> <a class="page" href="contributing/documentation.html" title="Learn how to improve CanJS's site and documentation."> Documentation </a> </li> <li class=" "> <a class="page" href="contributing/evangelism.html" title="Learn about resources that can help you spread the word about CanJS."> Evangelism </a> </li> <li class=" "> <a class="page" href="contributing/feature-suggestion.html" title="Learn how to suggest a feature."> Feature Suggestion </a> </li> <li class=" "> <a class="page" href="contributing/releases.html" title="Release and hosting information for CanJS maintainers."> Releases </a> </li> </ul> </li> </ul> </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=" "> <a class="page" href="../can-infrastructure.html" title="Utility libraries that power the core and ecosystem collection."> Infrastructure </a> </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="../guides.html">Guides</a></li> / <li><a href="api.html">API Guide</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>API Guide</h1> <div>page</div> </div> <section class="description"> <p>This page walks through how to use and understand CanJS's API documentation.</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/docs/can-guides/commitment/api-guide.md">source</a></li>   </ul> </section> <section class="body"> <h2>Documentation Structure</h2> <p>CanJS's documentation is broken down by pages for:</p> <ul> <li>library collections</li> <li>packages and modules and their exports</li> <li>functions, properties, and type definitions (typedefs) related to module exports</li> </ul> <p>For example, <a href="../can-define/map/map.prototype.on.html" title="Add event handlers to a map.">can-define/map/map.prototype.on</a> is a method that listens to changes on an observable map as follows:</p> <pre><code class="language-js">var DefineMap = require("can-define/map/map"); var map = new DefineMap({name: "Justin"}); map.on("name", function(ev, newVal, oldValue){ ... }) </code></pre> <p><code>.on</code> is a function the <code>prototype</code> of the <code>DefineMap</code> export of the <code>can-define/map/map</code> module. The <code>can-define/map/map</code> is part of CanJS's <a href="../can-core.html" title="The best, most hardened and generally useful libraries in CanJS.">Core</a> collection.</p> <p>So understanding CanJS's API pages are about understanding the relationships between:</p> <ul> <li>library collections</li> <li>packages and modules and their exports</li> <li>functions, properties, and type definitions (typedefs) related to module exports</li> </ul> <p>... and what's documented on those pages.</p> <h3>Library Collection pages</h3> <p>The API docs are divided in 4 collection pages:</p> <ul> <li><a href="../can-core.html" title="The best, most hardened and generally useful libraries in CanJS.">Core</a></li> <li><a href="../can-ecosystem.html" title="Useful libraries that extend or add important features to the core collection.">Ecosystem</a></li> <li><a href="../can-infrastructure.html" title="Utility libraries that power the core and ecosystem collection.">Infrastructure</a></li> <li><a href="../can-legacy.html" title="Former libraries that we still accept patches for, but are not under active development.">Legacy</a></li> </ul> <p>Each collection page acts as an overview and cheat sheet for the modules and functionality contained within the collection.</p> <p>The <a href="../can-core.html" title="The best, most hardened and generally useful libraries in CanJS.">Core</a> collection contains the documentation for the libraries that are use most commonly and directly within a CanJS application. This is where the Model-View-ViewModel libraries of CanJS are documented.</p> <p>The <a href="../can-ecosystem.html" title="Useful libraries that extend or add important features to the core collection.">Ecosystem</a> collection contains less commonly used libraries or libraries that aren't quite core ready yet. The most commonly used libraries here are <a href="../can-fixture.html" title="can-fixture intercepts an AJAX request and simulates the response with a file or function.">can-fixture</a>, <a href="../can-stache-converters.html" title="Provides a set of converters useful for two-way binding with form elements such as <input> and <select>.">can-stache-converters</a>, and <a href="../can-jquery.html" title="Extensions to the event system so that can events and jQuery events are cross-bound. Importing can-jquery will return the jQuery object and wire up the event system. var $ = require("can-jquery"); var div = $("<div>"); div.on("inserted", function(){ // it inserted! }); $("body").append(div);">can-jquery</a>.</p> <p>The <a href="../can-infrastructure.html" title="Utility libraries that power the core and ecosystem collection.">Infrastructure</a> collection contains the utility libraries that power the core and ecoystem collection. Often, this functionality is used indirectly. For example, 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> mixin is used to add <code>on</code>, <code>off</code>, and <code>dispatch</code> methods to <a href="../can-define.html" title="Exports the define method that defines observable properties and their behavior on a prototype object.">can-define</a> and <a href="../can-compute.html" title="Create an observable value.">can-compute</a>. And, <a href="../can-util.html" title="A set of utilities.">can-util</a> contains a wide variety of low-level DOM and JavaScript utilities.</p> <p>Sometimes <a href="../can-infrastructure.html" title="Utility libraries that power the core and ecosystem collection.">Infrastructure</a> is used directly. The most important examples are:</p> <ul> <li><a href="../can-event/batch/batch.html" title="Adds task batching abilities to event dispatching.">can-event/batch/batch</a> is used to batch changes for faster performance.</li> <li><a href="../can-util/dom/attr/attr.html" title="A module that makes it easy to access attributes and properties of elements.">attr</a> provides special <a href="../can-util/dom/attr/attr.special.focused.html" title="Signifies if an element, usually an <input> is the focused element on the page.">focused</a> and <a href="../can-util/dom/attr/attr.special.values.html" title="A special property that represents the selected values in a <select> element, usually a <select multiple>. The special property is needed because the DOM's native value property on a multiple select only gives you one of the selected options' values.">values</a> attributes that <a href="../can-stache-bindings.html" title="Provides template event, one-way, and two-way bindings.">can-stache-bindings</a> can be bound to.</li> <li><a href="../can-util/dom/events/events.html" title="Allows you to listen to a domEvent and special domEvents as well as dispatch domEvents. var domEvents = require("can-util/dom/events/events");">events</a> provides special <a href="../can-util/dom/events/attributes/attributes.html" title="Adds a listenable "attributes" event to DOM nodes, which fires when the node's attributes change.">attributes</a>, <a href="../can-util/dom/events/inserted/inserted.html" title="This event fires when the bound element is added to the DOM.">inserted</a>, and <a href="../can-util/dom/events/removed/removed.html" title="This event fires when the bound element is detached or destroyed.">removed</a> events.</li> <li><a href="../can-view-callbacks.html" title="Registered callbacks for behaviors">can-view-callbacks</a> lets you register behavior for custom elements and attributes.</li> </ul> <p>Finally, the <a href="../can-legacy.html" title="Former libraries that we still accept patches for, but are not under active development.">Legacy</a> collection. This is for libraries that are no longer under active development. Hopefully, you aren't there very often.</p> <blockquote> <p>Look to library collection pages for a high level cheat and explanation of every module within the collection.</p> </blockquote> <h2>Package and Module Pages</h2> <p>A package or module documents the "direct" functionality of the export and provides an overview of all functionality contained within the module or package.</p> <p>For example, <a href="../can-define/list/list.html" title="Create observable lists.">can-define/list/list</a> documents the "direct" functionality of the export, namely the <code>DefineList</code> function that is exported. While <a href="../can-define/list/list.extend.html" title="Define a custom list type.">DefineList.extend</a> is the most common starting place when using <code>DefineList</code>, the <code>DefineList</code> export method can only be used like <code>new DefineList()</code> directly. This is why <code>new DefineList()</code> is documented on <a href="../can-define/list/list.html" title="Create observable lists.">can-define/list/list</a>.</p> <p>However, after the <code>new DefineList()</code> signature is detailed, <a href="../can-define/list/list.html" title="Create observable lists.">can-define/list/list</a> has a <strong>#Use</strong> section that provides an overview of all functionality contained within the <code>can-define/list/list</code> module.</p> <blockquote> <p>Look to Package and module pages for details of what is specifically exported and an overview of what the module does, why it's useful, and how to use it.</p> </blockquote> <h2>Functions, Properties, and Typedef pages</h2> <p>Within a module, there might be a variety of functions, properties and types a module might provide.</p> <p>These values are generally organized by groupings. The most common groupings are:</p> <ul> <li><em>prototype</em> - A property or function is on the prototype of a parent function.</li> <li><em>static</em> - A property or method is a direct value on the parent function or object.</li> <li><em>events</em> - Events dispatched on the parent object or instances of the parent function.</li> <li><em>types</em> - Type definitions.</li> </ul> <p>Lets see a few examples and then give an overview of how their content is structured.</p> <h4>prototype</h4> <p><a href="../can-define/list/list.prototype.concat.html" title="Merge many collections together into a DefineList.">can-define/list/list.prototype.concat</a> is in the <em>prototype</em> group on <a href="../can-define/list/list.html" title="Create observable lists.">can-define/list/list</a> because <code>concat</code> is on the <code>can-define/list/list</code> export's <code>prototype</code>:</p> <pre><code class="language-js">var DefineList = require("can-define/list/list"); DefineList.prototype.concat //-> function </code></pre> <p>Because of how JavaScript works, this means that you can call <code>.concat</code> directly on any instance of <code>DefineList</code>:</p> <pre><code class="language-js">var hobbies = new DefineList(["learning"]); hobbies.concat(["programming"]); </code></pre> <h4>static</h4> <p><a href="../can-define/map/map.extend.html" title="Define a custom map type.">extend</a> s in the <em>static</em> group on <a href="../can-define/map/map.html" title="Create observable objects.">can-define/map/map</a> because <code>extend</code> is a direct property on the <code>can-define/map/map</code> export:</p> <pre><code class="language-js">var DefineMap = require("can-define/map/map"); DefineMap.prototype.map //-> function </code></pre> <h4>types</h4> <p>Sometimes a method might expect data passed to it in a certain format, or returns data in another format. These formats are often described separate from the method.</p> <p>For example, the <a href="../can-fixture.store.html" title="">can-fixture.store</a> method returns an object of the <a href="../can-fixture/StoreType.html" title="">Store type</a>.</p> <pre><code class="language-js">var fixture = require("can-fixture"); var todoStore = fixture.store([{id: 1, name: "trash"}]); todoStore.createData //-> function todoStore.destroyData //-> function todoStore.get //-> function </code></pre> <p>As you can see above, a <code>Store</code> can have lots of methods itself: <code>createData</code>, <code>destroyData</code>, etc. So this type that isn't directly accessible is documented under <code>can-fixture</code>'s <em>types</em>. It's also specified as the return value of <a href="../can-fixture.store.html" title="">can-fixture.store</a>.</p> <h3>Functions, Properties, and Typedef content</h3> <p>Each function, property, and typedef page will have one or more signature's describing what is being documented.</p> <p>Signatures are the <strong>what</strong> and the <strong>how</strong>. They should be precise on the behavior of what is being documented.</p> <p>Some function, property, and typedef pages have <strong>#Use</strong> sections that give more information and examples on what is being documented.</p> <blockquote> <p>Look to Functions, Properties, and Typedef pages to provide low level details on a specific piece of CanJS's API.</p> </blockquote> <h2>How to find what you're looking for ...</h2> <ol> <li>Get a good understand of the purpose behind each module.</li> <li>Start with core modules.</li> <li>Then checkout infrastructure modules.</li> </ol> <p>If you don't find what you want on the lowest level, walk up to the parent module, it might be in its <strong>#Use</strong> section.</p> <p>If not, let us know!</p> </section> <script type="text/javascript"> var docObject = {"src":{"path":"docs/can-guides/commitment/api-guide.md"},"description":"This page walks through how to use and understand CanJS's API documentation. \n","name":"guides/api","title":"API Guide","type":"page","parent":"guides/commitment","order":0,"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>