DoneJS StealJS jQuery++ FuncUnit DocumentJS
3.14.1
5.0.0 4.3.0 2.3.35
  • About
  • Guides
  • API Docs
  • Community
  • Contributing
  • Bitovi
    • Bitovi.com
    • Blog
    • Design
    • Development
    • Training
    • Open Source
    • About
    • Contact Us
  • About
  • Guides
  • API Docs
    • Observables
      • can-compute
      • can-define
      • can-define/list/list
      • can-define/map/map
      • can-define-stream
      • can-define-stream-kefir
      • can-event
      • can-event/async/async
      • can-event/batch/batch
      • can-event/lifecycle/lifecycle
      • can-kefir
      • can-list
      • can-map
        • prototype
          • DEFAULT-ATTR
          • attr
          • bind
          • compute
          • each
          • removeAttr
          • serialize
          • unbind
        • static
          • keys
      • can-map-backup
      • can-map-define
      • can-observation
      • can-observe
      • can-simple-map
      • can-simple-observable
      • can-stream
      • can-stream-kefir
    • Data Modeling
      • can-connect
      • can-connect-cloneable
      • can-connect-feathers
      • can-connect-ndjson
      • can-connect-signalr
      • can-fixture
      • can-fixture-socket
      • can-ndjson-stream
      • can-set
    • Views
      • can-component
      • can-ejs
      • can-element
      • can-react-component
      • can-stache
      • can-stache/helpers/route
      • can-stache-bindings
      • can-stache-converters
      • can-view-autorender
      • can-view-callbacks
      • can-view-href
      • can-view-import
      • can-view-live
      • can-view-model
      • can-view-nodelist
      • can-view-parser
      • can-view-scope
      • can-view-target
      • react-view-model
      • react-view-model/component
      • steal-stache
    • Routing
      • can-deparam
      • can-param
      • can-route
      • can-route-pushstate
    • JS Utilities
      • can-assign
      • can-define-lazy-value
      • can-globals
      • can-key-tree
      • can-make-map
      • can-parse-uri
      • can-string
      • can-string-to-any
      • can-util
      • can-zone
      • can-zone-storage
    • DOM Utilities
      • can-ajax
      • can-attribute-encoder
      • can-control
      • can-dom-events
      • can-event-dom-enter
      • can-event-dom-radiochange
      • can-jquery
    • Data Validation
      • can-define-validate-validatejs
      • can-validate
      • can-validate-interface
      • can-validate-legacy
      • can-validate-validatejs
    • Typed Data
      • can-cid
      • can-construct
      • can-construct-super
      • can-namespace
      • can-reflect
      • can-reflect-promise
      • can-types
    • Polyfills
      • can-symbol
      • can-vdom
    • Core
    • Infrastructure
      • can-global
      • can-test-helpers
    • Ecosystem
    • Legacy
  • Community
  • Contributing
  • GitHub
  • Twitter
  • Chat
  • Forum
  • News
Bitovi

can-map

  • npm package badge
  • Star
  • Edit on GitHub

Create observable objects.

new Map([props])

Creates a new instance of can.Map.

Parameters

  1. props {Object}:

    Properties and values to seed the Observe with.

Returns

{can.Map}:

An instance of can.Map with the properties from props.

Map.extend([name,] [staticProperties,] instanceProperties)

Creates a new extended constructor function.

Use

Watch this video to see an example of creating an ATM machine using can.Map:

Map provides a way for you to listen for and keep track of changes to objects. When you use the getters and setters provided by Map, events are fired that you can react to. Map also has support for working with deep properties. Observable arrays are also available with can-list, which is based on Map.

Working with Observes

To create an Observe, use new Map([props]). This will return a copy of props that emits events when its properties are changed with attr.

You can read the values of properties on Observes directly, but you should never set them directly. You can also read property values using attr.

var aName = {a: 'Alexis'},
    map = new can.Map(aName);

// Observes are copies of data:
aName === map; // false

// reading from an Observe:
map.attr();    // {a: 'Alexis'}
map.a;         // 'Alexis'
map.attr('a'); // 'Alexis'

// setting an Observe's property:
map.attr('a', 'Alice');
map.a; // Alice

// removing an Observe's property;
map.removeAttr('a');
map.attr(); // {}

// Don't do this!
map.a = 'Adam'; // wrong!

Find out more about manipulating properties of a map under [can.Map.prototype.attr attr] and [can.Map.prototype.removeAttr removeAttr].

Listening to changes

The real power of maps comes from being able to react to properties being added, set, and removed. Maps emit events when properties are changed that you can bind to.

Map has two types of events that fire due to changes on a map:

  • the change event fires on every change to a map.
  • an event named after the property name fires on every change to that property.
var o = new Map({});
o.bind('change', function(ev, attr, how, newVal, oldVal) {
    console.log('Something on o changed.');
});
o.bind('a', function(ev, newVal, oldVal) {
    console.log('a was changed.');
});

o.attr('a', 'Alexis'); // 'Something on o changed.'
                       // 'a was changed.'
o.attr({
    'a': 'Alice',      // 'Something on o changed.' (for a's change)
    'b': 'Bob'         // 'Something on o changed.' (for b's change)
});                    // 'a was changed.'

o.removeAttr('a');     // 'Something on o changed.'
                       // 'a was changed.'

For more detail on how to use these events, see [can.Map.prototype.bind bind] and [can.Map.prototype.unbind unbind]. There is also a plugin called [can.Map.delegate] that makes binding to specific types of events easier:

var o = new Map({});
o.delegate('a', 'add', function(ev, newVal, oldVal) {
    console.log('a was added.');
});
o.delegate('a', 'set', function(ev, newVal, oldVal) {
    console.log('a was set.');
});
o.delegate('a', 'remove', function(ev, newVal, oldVal) {
    console.log('a was removed.');
});
o.delegate('a', 'change', function(ev, newVal, oldVal) {
    console.log('a was changed.');
});

o.attr('a', 'Alexis'); // 'a was added.'
                       // 'a was changed.'

o.attr('a', 'Alice'); // 'a was set.'
                      // 'a was changed.'

o.removeAttr('a'); // 'a was removed.'
                   // 'a was changed.'

Object.prototype.watch

Due to a method available on the base Object prototype called "watch", refrain from using properties with the same name on Gecko based browsers as there will be a collision. Source

CanJS is part of DoneJS. Created and maintained by the core DoneJS team and Bitovi. Currently 3.14.1.

On this page

Get help

  • Chat with us
  • File an issue
  • Ask questions
  • Read latest news