addMapChangeListener arguments token and before about collections HOT 3 CLOSED

It is mention in the documentation under Map Changes: http://documentup.com/montagejs/collections#change-listeners/map-changes

The listener may be a delegate object with one of the following methods, in order of precedence:

listener.handleMap + Change or WillChange
listener.handle + token + Map + Change or WillChange
listener.call

Example:
The token can be useful when you're listening to map changes of different objects.

var delegate = {
    handleArticlesMapChange: function(value, key, object) {

    },
    handleMoviesMapChange: function(value, key, object) {

    }
};

articles.addMapChangeListener(delegate, "Articles");
movies.addMapChangeListener(delegate, "Movies");

The before is a flag that when set to true will make the listener to be called just before the change instead of after the change. When this is the case the delegate method name to be called is in the handle*MapWillChange format.

from collections.

ok got it, thanks @aadsm

It is a bit complicated, no?

One would expect on(fn, 'token'); to listen for changes on the token prop and have fn triggered...

from collections.

The Maps are different, in that they have properties (length, store) and content. So that there is no confusion about whether you want to listen to a property change (addOwnPropertyChangeListener) or a change in the content there are different methods. Maps also have the advantage over normal objects in that we know when any key/value changes, and so the API exposes that power.

If you want to listen to just one key/value change in a Map you can use an if inside the listener. If you want to listen to a property on the actual object (or any Javascript object) then you need to use addOwnPropertyChangeListener.

I agree it is confusing at first, but they do do different tasks that can't be combined without introducing ambiguity.

from collections.