addMapChangeListener arguments token and before

[thanpolas]

I read in the docs about the events emitted by the Map:

collection.addMapChangeListener(listener, token, before);

But i cannot find the functionality of the token and before arguments. I looked in the tests and they are not being used, no mention in the docs...

Do they serve a purpose?

[aadsm]

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.

[thanpolas]

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...

[Stuk]

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.