Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Better selection button docs #350

Merged
merged 1 commit into from
Nov 22, 2016
Merged

Better selection button docs #350

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 44 additions & 17 deletions docs/javascript.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ The simplest module looks like:
```javascript
;(function(Modules) {
'use strict'

Modules.SomeModule = function() {
this.start = function($element) {
// module code
Expand Down Expand Up @@ -342,40 +342,67 @@ and stop the elements before they get to the bottom.

## Selection buttons

Script to support a design of radio buttons and checkboxes requiring them to be wrapped in `<label>` tags:
`GOVUK.SelectionButtons` adds classes to a parent `<label>` of a radio button or checkbox, allowing you to style it based on the input’s state. Given this example HTML structure:

<label>
<input type="radio" name="size" value="medium" />
</label>
```html
<label>
<input type="radio" name="size" value="medium" />
Medium size
</label>
```

When the input is focused or its `checked` attribute is set, classes are added to their parent labels so their styling can show this.
When the input is focused or its `checked` attribute is set, representative classes are added to the label.

### Usage

#### GOVUK.SelectionButtons

To apply this behaviour to elements with the above HTML pattern, call the `GOVUK.SelectionButtons` constructor with their inputs:
To apply this behaviour to elements that follow the above HTML, call the `GOVUK.SelectionButtons` constructor with a jQuery collection of the inputs:

```
var $buttons = $("label input[type='radio'], label input[type='checkbox']")
```javascript
var $buttons = $('label input[type=radio], label input[type=checkbox]')
var selectionButtons = new GOVUK.SelectionButtons($buttons)
```

You can also call `GOVUK.SelectionButtons` with a selector:
If you want to bind your events to the document instead of the elements directly (delegated events) you can call `GOVUK.SelectionButtons` with a selector string:

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

This will bind all events to the document meaning any new elements (for example, by AJAX) that match this selector will automatically gain this functionality.

If you do add elements that need this functionality dynamically to the page, you will need to initialise their state. You can do this by calling `SelectionButtons.setInitialState` with the same selector string:

```javascript
var buttonSelector = 'label input[type=radio], label input[type=checkbox]'
var selectionButtons = new GOVUK.SelectionButtons(buttonSelector)
```

This will bind all events to the document, meaning any changes to content (for example, by AJAX) will not effect the button's behaviour.
then later, after adding more elements:

```javascript
selectionButtons.setInitialState(buttonSelector)
```

The classes that get added to the `<label>` tags can be passed in as options:

```javascript
var $buttons = $('label input[type=radio], label input[type=checkbox]')
var selectionButtons = new GOVUK.SelectionButtons($buttons, {
focusedClass: 'selectable-focused',
selectedClass: 'selectable-selected'
})
```
var $buttons = $("label input[type='radio'], label input[type='checkbox']")
var selectionButtons = new GOVUK.SelectionButtons($buttons, { focusedClass : 'selectable-focused', selectedClass : 'selectable-selected' })

var selectionButtons = new GOVUK.SelectionButtons("label input[type='radio'], label input[type='checkbox']", { focusedClass : 'selectable-focused', selectedClass : 'selectable-selected' })
or, using delegated events:

```javascript
var buttonSelector = 'label input[type=radio], label input[type=checkbox]'
var selectionButtons = new GOVUK.SelectionButtons($buttonSelector, {
focusedClass: 'selectable-focused',
selectedClass: 'selectable-selected'
})
```

#### destroy method
Expand All @@ -384,15 +411,15 @@ The returned instance object includes a `destroy` method to remove all events bo

Using any of the `selectionButtons` objects created above, it can be called like so:

```
```javascript
selectionButtons.destroy();
```

### Deprecated functionality

The previous method of calling selection buttons is now deprecated. If you need to call them using this method, you will need to define this function:

```
```javascript
GOVUK.selectionButtons = function (elms, opts) {
new GOVUK.SelectionButtons(elms, opts)
}
Expand Down