mediawiki-extensions-Popups/doc/change_listener.md

Change Listeners

Redux's Store#subscribe allows you to subscribe to updates to the state tree. These updates are delivered every time an action is dispatched to the store, which may or may not result in a change of state.

In the Page Previews codebase, a change listener is a function that is only called when the state tree has changed. As such, change listeners are predominantly responsible for updating the UI so that it matches the state in the store.

Registering Change Listeners

Change listeners are registered automatically during boot in the registerChangeListeners function. It expects the values of the mw.popups.changeListeners map to be factory functions that accept, currently, the bound action creators, i.e.

mw.popups.changeListeners.foo = function ( boundActions ) {
  var $link = $( '<a>' )
    .attr( 'href': '#' )
    .click( boundActions.showSettings );

  return function ( prevState, state ) {
    // ...
  }
};

You'll note that the above change listener is effectful and maintains some local state ($link), both of which are acceptable. The former is unavoidable and the latter is to avoid populating the state tree with unimportant data.