From c5029611493e33cbc1d270708c3ea352d8f8b884 Mon Sep 17 00:00:00 2001 From: Kevin Brown Date: Wed, 9 Sep 2015 12:30:12 -0400 Subject: [PATCH] Answers to some of the questions --- .../options-new/core/amd-support.html | 25 +++++- docs/_includes/options-new/core/options.html | 37 +++++++++ docs/_includes/options-new/data/ajax.html | 78 +++++++++++++++++++ docs/_includes/options-new/data/array.html | 32 ++++++-- .../options-new/selections/multiple.html | 12 +++ .../options-new/selections/placeholder.html | 40 ++++++++-- 6 files changed, 206 insertions(+), 18 deletions(-) diff --git a/docs/_includes/options-new/core/amd-support.html b/docs/_includes/options-new/core/amd-support.html index 8aeae54f..0f508ff8 100644 --- a/docs/_includes/options-new/core/amd-support.html +++ b/docs/_includes/options-new/core/amd-support.html @@ -2,12 +2,33 @@

Can I use Select2 with my AMD or CommonJS loader?

- + +

+ Yes, Select2 should work with most AMD or CommonJS loaders without any issues. +

+

How do I tell Select2 where to look for modules?

- + +

+ For most AMD and CommonJS setups, the location of the data files used by Select2 will be automatically determined and handled without you needing to do anything. +

+ +

+ If you are using Select2 in a build environment where preexisting module names are changed during a build step, Select2 may not be able to find optional dependencies or language files. You can manually set the prefixes to use for these files using the amdBase and amdLanugageBase options. +

+ +
+$.fn.select2.defaults.set('amdBase', 'select2/');
+$.fn.select2.defaults.set('amdLanguageBase', 'select2/i18n/');
+
+

Select2 is being placed before jQuery in my JavaScript file

+ +

+ Due to a bug in older versions of the r.js build tool, Select2 was sometimes placed before jQuery in then compiled build file. Because of this, Select2 will trigger an error because it won't be able to find or load jQuery. +

\ No newline at end of file diff --git a/docs/_includes/options-new/core/options.html b/docs/_includes/options-new/core/options.html index c2a21a10..e9bec7e0 100644 --- a/docs/_includes/options-new/core/options.html +++ b/docs/_includes/options-new/core/options.html @@ -7,6 +7,35 @@ Can default options be set for all dropdowns? +

+ In some cases, you need to set the default options for all instances of + Select2 in your web application. This is especially useful when you are + migrating from past versions of Select2, or you are using non-standard + options like custom AMD builds. Select2 exposes the + default options through $.fn.select2.defaults, which allows + you to set them globally. +

+ +

+ When setting options globally, any past defaults that have been set will + be overriden. Default options are only used when an option is requested + that has not been set during initialization. +

+ +

+ You can set default options by calling + $.fn.select2.defaults.set("key", "value"). The key that is + set should take the same format as keys set using + HTML data-* attributes which + means that two dashes (--) will be replaced by a level of + nesting, and a single dash (-) will convert it to a camelCase + string. +

+ +
+$.fn.select2.defaults.set("theme", "classic");
+
+

How can I set a default value for a nested option?

@@ -14,4 +43,12 @@

How can I reset all of the global default options?

+ +

+ You can reset the default options by calling +

+ +
+$.fn.select2.defaults.reset();
+
\ No newline at end of file diff --git a/docs/_includes/options-new/data/ajax.html b/docs/_includes/options-new/data/ajax.html index 83f90fe3..02776ca1 100644 --- a/docs/_includes/options-new/data/ajax.html +++ b/docs/_includes/options-new/data/ajax.html @@ -3,10 +3,18 @@ Can Select2 be connected to a remote data source? +

+ Select2 supports connecting to a remote data source using the ajax option. +

+

How can I set the initially selected options when using AJAX?

+

+ You can refer to the following Stack Overflow answer if you want to set the initial value for AJAX requests: Select2 4.0.0 initial value with AJAX +

+

What should the results returned to Select2 look like?

@@ -15,15 +23,85 @@ Is there a way to modify the response before passing it back to Select2? +

+ You can use the ajax.processResults option to modify the data returned from the server before passing it to Select2. +

+ +
+$('select').select2({
+  ajax: {
+    url: '/example/api',
+    processResults: function (data) {
+      return {
+        results: data.items
+      };
+    }
+  }
+});
+
+

A request is being triggered on every key stroke, can I delay this?

+

+ By default, Select2 will trigger a new AJAX request whenever the user changes their search term. You can set a time limit for debouncing requests using the ajax.delay option. +

+ +
+$('select').select2({
+  ajax: {
+    url: '/example/api',
+    delay: 250
+  }
+});
+
+ +

+ This will tell Select2 to wait 250 milliseconds before sending the request out to your API. +

+

I want to add more query parameters to the request, where can this be done?

+

+ By default, Select2 will send the query term as well as the pagination data as query parameters in requests. You can override the data that is sent to your API, or change any of the query paramters, by overriding the ajax.data option. +

+ +
+$('select').select2({
+  ajax: {
+    data: function (params) {
+      var query = {
+        search: params.term,
+        page: params.page
+      }
+
+      // Query paramters will be ?search=[term]&page=[page]
+      return query;
+    }
+  }
+});
+
+

Can an AJAX plugin other than jQuery.ajax be used?

+ +

+ Select2 uses the transport method defined in ajax.transport to send requests to your API. By default, this transport method is jQuery.ajax but this can be changed. +

+ +
+$('select').select2({
+  ajax: {
+    transport: function (params, success, failure) {
+      var request = new AjaxRequest(params.url, params);
+      request.on('success', success);
+      request.on('failure', failure);
+    }
+  }
+});
+
\ No newline at end of file diff --git a/docs/_includes/options-new/data/array.html b/docs/_includes/options-new/data/array.html index 727fd167..b73ee095 100644 --- a/docs/_includes/options-new/data/array.html +++ b/docs/_includes/options-new/data/array.html @@ -2,36 +2,52 @@

Can I load data into Select2 using an array?

- +

Yes, but only when you are initially creating it.

- +

What properties are required on the objects passed in to the array?

- + +

+ The id and text properties are required on each object, and these are the properties that Select2 uses for the internal data objects. Any additional paramters passed in with data objects will be included on the data objects that Select2 exposes. +

+

How should nested results be formatted?

- +

How many levels of nesting are allowed?

- + +

+ Because Select2 falls back to an <optgroup> when creating nested options, only a single level of nesting can be supported. +

+

Why are <option> tags being created?

- +

The data option is a shortcut that Select2 provides which allows you to load options into your select from a data array.

- +

My objects don't use id for their unique identifiers, what can I do?

- + +

+ You can re-map your identifier before passing it to Select2. +

+

My objects use a property other than text for the text that needs to be displayed

+ +

+ These can also be re-mapped. +

\ No newline at end of file diff --git a/docs/_includes/options-new/selections/multiple.html b/docs/_includes/options-new/selections/multiple.html index 720db70d..645a0b61 100644 --- a/docs/_includes/options-new/selections/multiple.html +++ b/docs/_includes/options-new/selections/multiple.html @@ -2,4 +2,16 @@

Can I allow users to make multiple selections?

+ +

+ Yes, Select2 supports making multiple selections through the use of the multiple option that can be passed in when initializing Select2. +

+ +

+ Can the multiple attribute be used on my <select> element? +

+ +

+ Yes, Select2 will automatically map the value of the multiple attribute to the multiple option during initialization. +

\ No newline at end of file diff --git a/docs/_includes/options-new/selections/placeholder.html b/docs/_includes/options-new/selections/placeholder.html index 88eddea6..bcb08b5f 100644 --- a/docs/_includes/options-new/selections/placeholder.html +++ b/docs/_includes/options-new/selections/placeholder.html @@ -2,28 +2,52 @@

How can I have Select2 display a placeholder?

- + +

+ Select2 supports displaying a placeholder by default using the placeholder option. This can be either a data object matching the placeholder option, or a string to display as the placeholder if you are using a blank placeholder option. +

+

My first option is being displayed instead of my placeholder

- + +

+ This usually means that you do not have a blank <option></option> as the first option in your <select>. +

+ +

+ Note that this does not apply to multiple selects, as the browser does not select the first option by default when multiple selections can be made. +

+

I am using AJAX, can I still show a placeholder?

- + +

+ Yes, Select2 supports placeholders for all configurations. You will still need to add in the placeholder option if you are using a single select. +

+

- Can I use a placeholder without a blank value? + Can I use an option without a blank value as my placeholder?

- + +

+ The placeholder option allows you to pass in a data object instead of just a string if you need more flexibility. The id of the data object should match the value of the placeholder option. +

+

Can I change how the placeholder looks?

- + +

+ The placeholder option should go through the standard templating methods, including templateSelection, so you can change how it is displayed. +

+

My placeholders aren't being displayed in Internet Explorer

- +

- You need to include Placeholders.js on your page, or use the full build. + Select2 uses the native placeholder attribute on input boxes for the multiple select, and that attribute is not supported in older versions of Internet Explorer. You need to include Placeholders.js on your page, or use the full build, in order to add placeholder attribute support to input boxes.

\ No newline at end of file