Add document level events to selection buttons

[tombye]

The current version of GOVUK.selectionButtons (see #121) works by taking a jQuery-wrapped collection of DOM nodes as the first parameter, and binding events to them:

var $buttons = $("label input[type='radio'], label input[type='checkbox']");
GOVUK.selectionButtons($buttons);

This sometimes doesn't work on pages where the HTML is replaced by AJAX because the elements those events are bound to may no longer be in the page.
This pull request (PR) makes a new version called GOVUK.SelectionButtons which has the ability to take a selector string instead, which it uses to assign a live event to the document:

var selectionButtons = new GOVUK.SelectionButtons("label input[type='radio'], label input[type='checkbox']");

This means once you've called GOVUK.selectionButtons, any changes to the content of the page will not effect the functionality. This is backwards-compatible, the existing interface is still supported.

This PR also includes a new destroy method for clean-up of the events it creates:

selectionButtons.destroy();

In addition, the tests for selection-buttons have been rewritten. The previous ones were too tied to the implementation and didn't describe the requirements very well.

[edds]

I find this abstraction where setEventTypes creates this.bindEvents quite confusing to read. If I follow it through correctly you could drop line 17 and SelectionButtons.prototype.setEventTypes and create something like:

SelectionButtons.prototype.bindEvents = function (elmsOrSelector) {
  if (typeof elmsOrSelector === 'string') {
    this.bindDocumentLevelEvents(elmsOrSelector);
  } else {
    this.bindElementLevelEvents(elmsOrSelector);
  }
}

[tombye]

I like the use of elmsOrSelector to make it explicit what's happening and losing SelectionButtons.prototype.setEventTypes too. I ended up doing a similar thing with SelectionButtons.prototype.markSelected.

I would like to keep the local variables that identify the type we end up using (and include something that points to the fact the variable sent into SelectionButtons.prototype.bindElementLevelEvents is a jQuery object.

How about this?

SelectionButtons.prototype.bindEvents = function (elmsOrSelector) {
  var selector,
      $elms;

  if (typeof elmsOrSelector === 'string') {
    selector = elmsOrSelector;
    this.bindDocumentLevelEvents(selector);
  } else {
    $elms = $(elmsOrSelector);
    this.bindElementLevelEvents($elms);
  }
};

(I'll change the bind prefix separately btw, including it here so as not to confuse issues.)

[edds]

I am not sure how much value there is in an explicit identification that the object sent to bindElementLevelEvents is a jQuery object. To me that is a concern of the method receiving not sending as if another developer wanted to find out what was being sent then I would look at the function definition of bindElementLevelEvents. However, having the extra variables doesn't hurt so it is up to you.

I wouldn't add the extra $elms = $(elmsOrSelector); over just $elms = elmsOrSelector; though as that adds an extra jQuery wrap which has no value but does incur computation.

[edds]

I am finding the naming of the internal methods in this being named bindThing gets a little confusing now we are using the real Function.prototype.bind. I think they would be better named addThing which better matches addEventListener.

[edds]

Is this method just for testing? Otherwise if it provides value it should be documented.

[tombye]

It was written just for testing. I can imagine it might add some value as a 'teardown' method if you're doing a lot with live events.

I'd be interested in your thoughts on leaving it in. Not been in this situation before.

[tombye]

For that last one, are you just talking about bindEvents?

[tombye]

Ignore that, it's clear what the others are. Agree that it would add clarity so changing all methods prefixed with bind.

[tombye]

After a chat with @edds about GOVUK.selectionButtons being unnecessary and GOVUK.selectionButtons.removeEventsFor being better as an instance method I've changed the interface and some of the structure.

The added destroy method allows users to unbind any events GOVUK.SelectionButtons has set. This moves responsibility for all events set onto the user which is why all internal tracking of events has been removed.

[edds]

this.setInitialState($(this.selector)); can be this.setInitialState($elms); as you have already created the jQuery object.

[edds]

One minor comment. Otherwise this is looking good to me. We will need to make sure we bump the toolkit version by a major number for this and make the reasoning clear in the changelog.

[tombye]

Yes, agreed. If this is merged I can do the version bump with a full explanation.