can

<!DOCTYPE html>  <html lang="en"> <head> <meta charset="utf-8"> <title>CanJS - attr</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=" "> <a class="page" href="can-infrastructure.html" title="Utility libraries that power the core and ecosystem collection."> Infrastructure </a> </li> <li class=" parent expanded"> <a class="page" href="can-legacy.html" title="Former libraries that we still accept patches for, but are not under active development."> Legacy </a> <ul> <li class=" "> <a class="module" href="can-ejs.html" title="EJS provides live ERB-style client-side templates."> can-ejs </a> </li> <li class=" "> <a class="module" href="can-list.html" title=""> can-list </a> </li> <li class=" parent expanded"> <a class="module" href="can-map.html" title="Create observable objects."> can-map </a> <ul> <li> <span>prototype</span> <ul> <li class=" "> <a class="property" href="can-map.prototype.DEFAULT-ATTR.html" title="Specify a default property and value."> DEFAULT-ATTR </a> </li> <li class="current parent expanded"> <a class="function" href="can-map.prototype.attr.html" title="Get or set properties on a Map."> attr </a> </li> <li class=" "> <a class="function" href="can-map.prototype.bind.html" title="Bind event handlers to a Map."> bind </a> </li> <li class=" "> <a class="function" href="can-map.prototype.compute.html" title="Make a can.compute from an observable property."> compute </a> </li> <li class=" "> <a class="function" href="can-map.prototype.each.html" title="Call a function on each property of a Map."> each </a> </li> <li class=" "> <a class="function" href="can-map.prototype.removeAttr.html" title="Remove a property from a Map."> removeAttr </a> </li> <li class=" "> <a class="function" href="can-map.prototype.serialize.html" title="Serialize this object to something that can be passed to JSON.stringify."> serialize </a> </li> <li class=" "> <a class="function" href="can-map.prototype.unbind.html" title="Unbind event handlers from a Map."> unbind </a> </li> </ul> </li> <li> <span>static</span> <ul> <li class=" "> <a class="function" href="can-map.keys.html" title="Returns an array of the map's keys."> keys </a> </li> </ul> </li> </ul> </li> <li class=" "> <a class="module" href="can-map-backup.html" title=""> can-map-backup </a> </li> <li class=" "> <a class="module" href="can-map-define.html" title="Defines the type, initial value, get, set, remove, and serialize behavior for attributes of a Map."> can-map-define </a> </li> <li class=" "> <a class="module" href="can-view-href.html" title="Sets an element's href attribute so that it's url will set the specified attribute values on can-route."> can-view-href </a> </li> </ul> </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-legacy.html">Legacy</a></li> / <li><a href="can-map.html">can-map</a></li> / <li><a href="can-map.prototype.attr.html">attr</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>attr</h1> <div>function</div> </div> <section class="description"> <p>Get or set properties on a Map.</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-map/tree/v3.0.2/docs/prototype.attr.md">source</a></li>   </ul> </section> <div class="signature"> <h2 class="signature-title"> <code>map.attr()</code> </h2> <p>Gets a collection of all the properties in this <code>Map</code>.</p> <div class="returns"> <h3 class="returns-title">Returns</h3> <p> <code>{Object}</code>: <p>an object with all the properties in this <code>Map</code>.</p> </p> </div> </div> <div class="signature"> <h2 class="signature-title"> <code>map.attr(key)</code> </h2> <p>Reads a property from this <code>Map</code>.</p> <div class="parameters"> <h3 class="parameters-title">Parameters</h3> <ol> <li><b>key</b> <code>{String}</code>: <p>the property to read</p> </li> </ol> </div> <div class="returns"> <h3 class="returns-title">Returns</h3> <p> <code>{*}</code>: <p>the value assigned to <em>key</em>.</p> </p> </div> </div> <div class="signature"> <h2 class="signature-title"> <code>map.attr(key, value)</code> </h2> <p>Assigns <em>value</em> to a property on this <code>Map</code> called <em>key</em>.</p> <div class="parameters"> <h3 class="parameters-title">Parameters</h3> <ol> <li><b>key</b> <code>{String}</code>: <p>the property to set</p> </li> <li><b>the</b> <code>{*}</code>: <p>value to assign to <em>key</em>.</p> </li> </ol> </div> <div class="returns"> <h3 class="returns-title">Returns</h3> <p> <code>{can.Map}</code>: <p>this Map, for chaining</p> </p> </div> </div> <div class="signature"> <h2 class="signature-title"> <code>map.attr(obj[, removeOthers])</code> </h2> <p>Assigns each value in <em>obj</em> to a property on this <code>Map</code> named after the corresponding key in <em>obj</em>, effectively merging <em>obj</em> into the Map.</p> <div class="parameters"> <h3 class="parameters-title">Parameters</h3> <ol> <li><b>obj</b> <code>{Object}</code>: <p>a collection of key-value pairs to set. If any properties already exist on the <code>Map</code>, they will be overwritten.</p> </li> <li><b>removeOthers</b> <code>{bool}</code>: <p>whether to remove keys not present in <em>obj</em>. To remove keys without setting other keys, use <code>[can.Map::removeAttr removeAttr]</code>.</p> </li> </ol> </div> <div class="returns"> <h3 class="returns-title">Returns</h3> <p> <code>{can.Map}</code>: <p>this Map, for chaining</p> </p> </div> </div> <section class="body"> <p><code>attr</code> gets or sets properties on the <code>Map</code> it's called on. Here's a tour through how all of its forms work:</p> <pre><code>var people = new Map({}); // set a property: people.attr('a', 'Alex'); // get a property: people.attr('a'); // 'Alex' // set and merge multiple properties: people.attr({ a: 'Alice', b: 'Bob' }); // get all properties: people.attr(); // {a: 'Alice', b: 'Bob'} // set properties while removing others: people.attr({ b: 'Bill', e: 'Eve' }, true); people.attr(); // {b: 'Bill', e: 'Eve'} </code></pre> <h2>Deep properties</h2> <p><code>attr</code> can also set and read deep properties. All you have to do is specify the property name as you normally would if you weren't using <code>attr</code>.</p> <pre><code>var people = new Map({names: {}}); // set a property: people.attr('names.a', 'Alice'); // get a property: people.attr('names.a'); // 'Alice' people.names.attr('a'); // 'Alice' // get all properties: people.attr(); // {names: {a: 'Alice'}} </code></pre> <p>Objects that are added to Observes become Observes themselves behind the scenes, so changes to deep properties fire events at each level, and you can bind at any level. As this example shows, all the same events are fired no matter what level you call <code>attr</code> at:</p> <pre><code>var people = new Map({names: {}}); people.bind('change', function(ev, attr, how, newVal, oldVal) { console.log('people change: ' + attr + ', ' + how + ', ' + newVal + ', ' + oldVal); }); people.names.bind('change', function(ev, attr, how, newVal, oldVal) { console.log('people.names change' + attr + ', ' + how + ', ' + newVal + ', ' + oldVal); }); people.bind('names', function(ev, newVal, oldVal) { console.log('people names: ' + newVal + ', ' + oldVal); }); people.names.bind('a', function(ev, newVal, oldVal) { console.log('people.names a: ' + newVal + ', ' + oldVal); }); people.bind('names.a', function(ev, newVal, oldVal) { console.log('people names.a: ' + newVal + ', ' + oldVal); }); people.attr('names.a', 'Alice'); // people change: names.a, add, Alice, undefined // people.names change: a, add, Alice, undefined // people.names a: Alice, undefined // people names.a: Alice, undefined people.names.attr('b', 'Bob'); // people change: names.b, add, Bob, undefined // people.names change: b, add, Bob, undefined // people.names b: Bob, undefined // people names.b: Bob, undefined </code></pre> <h2>Properties with dots in their name</h2> <p>As shown above, <code>attr</code> enables reading and setting deep properties so special care must be taken when property names include dots '<code>.</code>'. To read a property containing dots, escape each one using '<code>\</code>'. This prevents <code>attr</code> from performing a deep lookup and throwing an error when the deep property is not found.</p> <pre><code>var person = new Map({ 'first.name': 'Alice' }); person.attr('first.name'); // throws Error person.attr('first\.name'); // 'Alice' </code></pre> <p>When setting a property containing dots, pass an object to <code>attr</code> containing the property name and new value. Setting a property by passing a string to <code>attr</code> will attempt to set a deep property and will throw an error.</p> <pre><code>var person = new Map({ 'first.name': 'Alice' }); person.attr('first.name', 'Bob'); // throws Error person.attr('first\.name', 'Bob'); // throws Error person.attr({'first.name': 'Bob'}); // Works </code></pre> <h2>See also</h2> <p>For information on the events that are fired on property changes and how to listen for those events, see [can.Map.prototype.bind bind].</p> </section> <script type="text/javascript"> var docObject = {"src":{"path":"node_modules/can-map/docs/prototype.attr.md"},"description":"Get or set properties on a Map. \n","title":"attr","name":"can-map.prototype.attr","type":"function","parent":"can-map.prototype","order":2,"signatures":[{"code":"map.attr()","description":"\n\nGets a collection of all the properties in this `Map`.\n","params":[],"returns":{"types":[{"type":"Object","options":[]}],"description":"an object with all the properties in this `Map`.\n"}},{"code":"map.attr(key)","description":"\n\nReads a property from this `Map`.\n","params":[{"types":[{"type":"String"}],"name":"key","description":"the property to read"}],"returns":{"types":[{"type":"*"}],"description":"the value assigned to _key_.\n"}},{"code":"map.attr(key, value)","description":"\n\nAssigns _value_ to a property on this `Map` called _key_.\n","params":[{"types":[{"type":"String"}],"name":"key","description":"the property to set"},{"types":[{"type":"*"}],"name":"the","description":"value to assign to _key_."}],"returns":{"types":[{"type":"can.Map"}],"description":"this Map, for chaining\n"}},{"code":"map.attr(obj[, removeOthers])","description":"\n\nAssigns each value in _obj_ to a property on this `Map` named after the\ncorresponding key in _obj_, effectively merging _obj_ into the Map.\n","params":[{"types":[{"type":"Object","options":[]}],"name":"obj","description":"a collection of key-value pairs to set.\nIf any properties already exist on the `Map`, they will be overwritten.\n"},{"types":[{"type":"bool"}],"optional":true,"name":"removeOthers","defaultValue":"false","description":"whether to remove keys not present in _obj_.\nTo remove keys without setting other keys, use `[can.Map::removeAttr removeAttr]`.\n"}],"returns":{"types":[{"type":"can.Map"}],"description":"this Map, for chaining\n"}}],"_curReturn":{"types":[{"type":"can.Map"}],"description":"this Map, for chaining\n"},"_curParam":{"types":[{"type":"bool"}],"optional":true,"name":"removeOthers","defaultValue":"false","description":"whether to remove keys not present in _obj_.\nTo remove keys without setting other keys, use `[can.Map::removeAttr removeAttr]`.\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>