112 lines
3.7 KiB
Markdown
112 lines
3.7 KiB
Markdown
|
---
|
||
|
|
title: The Select2 data format
|
||
|
|
taxonomy:
|
||
|
|
category: docs
|
||
|
|
---
|
||
|
|
|
||
|
|
Select2 can render programmatically supplied data from an array or remote data source (AJAX) as dropdown options. These will be rendered as actual `<option>` elements in the target `<select>` control.
|
||
|
|
|
||
|
|
In order to accomplish this, Select2 expects a very specific data format. This format consists of a JSON object containing an array of objects keyed by the `results` key.
|
||
|
|
|
||
|
|
```
|
||
|
|
{
|
||
|
|
"results": [
|
||
|
|
{
|
||
|
|
"id": 1,
|
||
|
|
"text": "Option 1"
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"id": 2,
|
||
|
|
"text": "Option 2"
|
||
|
|
}
|
||
|
|
],
|
||
|
|
"pagination": {
|
||
|
|
"more": true
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
Each object should contain, _at a minimum_, an `id` and a `text` property. The `text` property will be displayed by default unless you are using `templateResult` and `templateSelection` to customize the way options and selections are rendered.
|
||
|
|
|
||
|
|
The response object may also contain pagination data, if you would like to use the "infinite scroll" feature. This should be specified under the `pagination` key.
|
||
|
|
|
||
|
|
Any additional parameters passed in with data objects will be included on the data objects that Select2 exposes.
|
||
|
|
|
||
|
|
## Transforming data into the required format
|
||
|
|
|
||
|
|
### Generating `id` properties
|
||
|
|
|
||
|
|
Select2 requires that the `id` property is used to uniquely identify the options that are displayed in the results list. If you use a property other than `id` (like `pk`) to uniquely identify an option, you need to map your old property to `id` before passing it to Select2.
|
||
|
|
|
||
|
|
If you cannot do this on your server or you are in a situation where the API cannot be changed, you can do this in JavaScript before passing it to Select2:
|
||
|
|
|
||
|
|
```
|
||
|
|
var data = $.map(yourArrayData, function (obj) {
|
||
|
|
obj.id = obj.id || obj.pk; // replace pk with your identifier
|
||
|
|
|
||
|
|
return obj;
|
||
|
|
});
|
||
|
|
```
|
||
|
|
|
||
|
|
### Generating `text` properties
|
||
|
|
|
||
|
|
Just like with the `id` property, Select2 requires that the text that should be displayed for an option is stored in the `text` property. You can map this property from any existing property using the following JavaScript:
|
||
|
|
|
||
|
|
```
|
||
|
|
var data = $.map(yourArrayData, function (obj) {
|
||
|
|
obj.text = obj.text || obj.name; // replace name with the property used for the text
|
||
|
|
|
||
|
|
return obj;
|
||
|
|
});
|
||
|
|
```
|
||
|
|
|
||
|
|
## Automatic string casting
|
||
|
|
|
||
|
|
Because the `value` attribute on a `<select>` tag must be a string, and Select2 generates the `value` attribute from the `id` property of the data objects, the `id` property on each data object must also be a string.
|
||
|
|
|
||
|
|
Select2 will attempt to convert anything that is not a string to a string, which will work for most situations, but it is recommended to explicitly convert your `id`s to strings ahead of time.
|
||
|
|
|
||
|
|
Blank `id`s or an `id` with a value of `0` are not permitted.
|
||
|
|
|
||
|
|
## Grouped options
|
||
|
|
|
||
|
|
When options are to be generated in `<optgroup>` sections, options should be nested under the `children` key of each group object. The label for the group should be specified as the `text` property on the group's corresponding data object.
|
||
|
|
|
||
|
|
```
|
||
|
|
{
|
||
|
|
"results": [
|
||
|
|
{
|
||
|
|
"text": "Group 1",
|
||
|
|
"children" : [
|
||
|
|
{
|
||
|
|
"id": 1,
|
||
|
|
"text": "Option 1.1"
|
||
|
|
}
|
||
|
|
{
|
||
|
|
"id": 2,
|
||
|
|
"text": "Option 1.2"
|
||
|
|
}
|
||
|
|
]
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"text": "Group 2",
|
||
|
|
"children" : [
|
||
|
|
{
|
||
|
|
"id": 3,
|
||
|
|
"text": "Option 2.1"
|
||
|
|
}
|
||
|
|
{
|
||
|
|
"id": 4,
|
||
|
|
"text": "Option 2.2"
|
||
|
|
}
|
||
|
|
]
|
||
|
|
}
|
||
|
|
],
|
||
|
|
"paginate": {
|
||
|
|
"more": true
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
>>>> Because Select2 generates an `<optgroup>` when creating nested options, only [a single level of nesting is supported](/dropdown/option-groups). Any additional levels of nesting is not guaranteed to be displayed properly across all browsers and devices.
|