diff --git a/docs/_includes/options/data/array.html b/docs/_includes/options/data/array.html index b73ee095..73176c4a 100644 --- a/docs/_includes/options/data/array.html +++ b/docs/_includes/options/data/array.html @@ -4,9 +4,21 @@

- Yes, but only when you are initially creating it. + While Select2 is designed to be used with a <select> tag, the data that is used to search through and display the results can be loaded from a JavaScript array using the data option. This option should be passed in during the initialization of Select2.

+
+$('select').select2({
+  data: [
+    {
+      id: 'value',
+      text: 'Text to display'
+    },
+    // ... more data objects ...
+  ]
+});
+
+

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

@@ -19,12 +31,29 @@ How should nested results be formatted? +

+ Nested results should be specified using the children property on the data objects that are passed in. This children property should be an array of data objects that are grouped under this option, and the label for the group should be specified as the text property on the root data object. +

+ +
+{
+  text: 'Group label',
+  children: [
+    {
+      id: 'nested-1',
+      text: 'First nested option'
+    },
+    // ... more data objects ...
+  ]
+}
+
+

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. + Because Select2 falls back to an <optgroup> when creating nested options, only a single level of nesting is supported. Any additional levels of nesting is not guarenteed to be displayed properly across all browsers and devices.

@@ -35,6 +64,8 @@ The data option is a shortcut that Select2 provides which allows you to load options into your select from a data array.

+ {% include options/not-written.html %} +

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

@@ -43,6 +74,8 @@ You can re-map your identifier before passing it to Select2.

+ {% include options/not-written.html %} +

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

@@ -50,4 +83,6 @@

These can also be re-mapped.

+ + {% include options/not-written.html %} \ No newline at end of file diff --git a/docs/_includes/options/data/select.html b/docs/_includes/options/data/select.html index b915c921..5db2b608 100644 --- a/docs/_includes/options/data/select.html +++ b/docs/_includes/options/data/select.html @@ -3,20 +3,32 @@ Can Select2 be used with a <select> tag? +

+ Select2 was designed to be a replacement for the standard <select> boxes that are displayed by the browser, so by default it supports all options and operations that are available in a standard select box, but with added flexibility. There is no special configuration required to make Select2 work with a <select> tag. +

+

Does Select2 support nesting options?

- Yes, just like in a standard select. + A standard <select> box can display nested options by wrapping them with in an <optgroup> tag.

+
+<select>
+  <optgroup label="Group Name">
+    <option>Nested option</option>
+  </optgroup>
+</select>
+
+

How many levels of nesting can there be?

- Only a single level of nesting is allowed per the HTML specification. + Only a single level of nesting is allowed per the HTML specification. If you nest an <optgroup> within another <optgroup>, Select2 will not be able to detect the extra level of nesting and errors may be triggered as a result.

@@ -24,7 +36,7 @@

- No. This is a limitation of the HTML specification and is not a limitation that Select2 can overcome. + No. This is a limitation of the HTML specification and is not a limitation that Select2 can overcome. You can emulate grouping by using an <option> instead of an <optgroup> and changing the style by using CSS, but this is not recommended as it is not fully accessible.