From 7fd65b30258d1f8988c44eaf98f8ba314b95b41b Mon Sep 17 00:00:00 2001 From: alexweissman Date: Mon, 11 Sep 2017 14:34:54 -0400 Subject: [PATCH] expand the 'programmatic control' chapter --- .../01.add-select-clear-items/docs.md | 103 +++++++ .../01.methods/docs.md | 261 ------------------ .../02.retrieving-selections/docs.md | 40 +++ .../03.methods/docs.md | 132 +++++++++ .../{02.events => 04.events}/docs.md | 2 + pages/12.programmatic-control/chapter.md | 6 +- 6 files changed, 281 insertions(+), 263 deletions(-) create mode 100644 pages/12.programmatic-control/01.add-select-clear-items/docs.md delete mode 100644 pages/12.programmatic-control/01.methods/docs.md create mode 100644 pages/12.programmatic-control/02.retrieving-selections/docs.md create mode 100644 pages/12.programmatic-control/03.methods/docs.md rename pages/12.programmatic-control/{02.events => 04.events}/docs.md (97%) diff --git a/pages/12.programmatic-control/01.add-select-clear-items/docs.md b/pages/12.programmatic-control/01.add-select-clear-items/docs.md new file mode 100644 index 00000000..074915c6 --- /dev/null +++ b/pages/12.programmatic-control/01.add-select-clear-items/docs.md @@ -0,0 +1,103 @@ +--- +title: Add, select, or clear items +metadata: + description: Programmatically adding, selecting, and clearing options in a Select2 control. +taxonomy: + category: docs +--- + +## Creating new options in the dropdown + +New options can be added to a Select2 control programmatically by creating a new [Javascript `Option` object](https://developer.mozilla.org/en-US/docs/Web/API/HTMLOptionElement/Option) and appending it to the control: + +``` +var data = { + id: 1, + text: 'Barn owl' +}; + +var newOption = new Option(data.name, data.id, false, false); +$('#mySelect2').append(newOption).trigger('change'); +``` + +The third parameter of `new Option(...)` determines whether the item is "default selected"; i.e. it sets the `selected` attribute for the new option. The fourth parameter sets the options actual selected state - if set to `true`, the new option will be selected by default. + +### Create if not exists + +You can use `.find` to select the option if it already exists, and create it otherwise: + +``` +// Set the value, creating a new option if necessary +if ($('#mySelect2').find("option[value='" + data.id + "']").length) { + $('#mySelect2').val(data.id).trigger('change'); +} else { + // Create a DOM Option and pre-select by default + var newOption = new Option(data.name, data.id, true, true); + // Append it to the select + $('#mySelect2').append(newOption).trigger('change'); +} +``` + +## Selecting an option + +To programmatically select an option/item for a Select2 control, use the jQuery `.val()` method: + +``` +$('#mySelect2').val('US'); // Select the option with a value of 'US' +$('#mySelect2').trigger('change'); // Notify any JS components that the value changed +``` + +Select2 will listen for the `change` event on the `` element that it is attached to. When you make any external changes that need to be reflected in Select2 (such as changing the value), you should trigger this event. - -### Preselecting options in an remotely-sourced (AJAX) Select2 - -For Select2 controls that receive their data from an [AJAX source](/data-sources/ajax), using `.val()` will not work. The options won't exist yet, because the AJAX request is not fired until the control is opened and/or the user begins searching. This is further complicated by server-side filtering and pagination - there is no guarantee when a particular item will actually be loaded into the Select2 control! - -The best way to deal with this, therefore, is to simply add the preselected item as a new option. For remotely sourced data, this will probably involve creating a new API endpoint in your server-side application that can retrieve individual items: - -``` -// Set up the Select2 control -$('#mySelect2').select2({ - ajax: { - url: '/api/students' - } -}); - -// Fetch the preselected item, and add to the control -var studentSelect = $('#mySelect2'); -$.ajax({ - type: 'GET', - url: '/api/students/s/' + studentId -}).then(function (data) { - // create the option and append to Select2 - var option = new Option(data.full_name, data.id, true, true); - studentSelect.append(option).trigger('change'); - - // manually trigger the `select2:select` event - studentSelect.trigger({ - type: 'select2:select', - params: { - data: data - } - }); -}); -``` - -Notice that we manually trigger the `select2:select` event and pass along the entire `data` object. This allows other handlers to [access additional properties of the selected item](/programmatic-control/events#triggering-events). - -### Limiting the scope of the `change` event - -It's common for other components to be listening to the `change` event, or for custom event handlers to be attached that may have side effects. To limit the scope to **only** notify Select2 of the change, use the `.select2` event namespace: - -``` -$('#mySelect2').val('US'); // Change the value or make some change to the internal state -$('#mySelect2').trigger('change.select2'); // Notify only Select2 of changes -``` - -## Retrieving the selected values - -There are two ways to programmatically access the selection data: using `.select2('data')`, or by using a jQuery selector. - -### Using the `data` method - -Calling `select2('data')` will return a JavaScript array of objects representing the current selection. Each object will contain all of the properties/values that were in the source data objects passed through `processResults` and `templateResult` callbacks (as in Loading data from an array and Connecting to a remote data source). - -``` -$('#mySelect2').select2('data'); -``` - -### Using a jQuery selector - -Selected items can also be accessed via the `:selected` jQuery selector: - -``` -$('#mySelect2').find(':selected'); -``` - -It is possible to extend the `